The ModelChain Endpoint

Definition

The ModelChain endpoint runs the energy calculation in a synchronous way. This will probably be the principal endpoint that you use with the web API.

  • API endpoint: https://solarfarmer.dnv.com/api/ModelChain
  • It is a HTTP POST request
  • Inputs:
    • projectId: (string) - an identifier for the project - used to group related runs and for billing
    • files: a list of value pairs (e.g. a list of Tuples in Python), the first value of each pair being one of the following values, the second the contents of the file.
      • tmyFile - solar resource file - either a Meteonorm .dat file or TSV file (see below)
      • metDataTransferFile - solar resource file produced by the SolarFarmer desktop app (usually called "MeteorologicalConditionsDatasetDto_Protobuf.gz")
      • horFile - a horizon file
      • ondFiles - set all OND inverter files with this first value
      • panFiles - set all PAN module specification files with this first value
    • request: an object of type EnergyCalculationInputs (see Generating API input files from the SolarFarmer desktop application for how to generate this from the SolarFarmer desktop application)
  • Outputs:

See the ModelChain Endpoint Tutorial to learn how to use this endpoint.

Note

All classes (including descriptions of classes and their properties) referred to below can be found

Input files

You can specify various input files that can be used in the calculation. All these can also be specified by filling in the data in various classes, but sometimes (especially for the PAN and OND files) it is much easier to provide the data in a file.

Solar resource files

There are 3 ways to specify the solar resource data for your calculation:

  1. The tmyFile property (as described above), or
  2. The metDataTransferFile property (as described above), or
  3. Specify the resource data within the EnergyCalculationInputs object.

You should only use one of the above 3 options.

If using the tmyFile property in the files dictionary supplied to the endpoint, this can be one of two formats:

A Meteonorm PVsyst Hourly TMY (.dat) file

This should be a TMY (Typical Meteorological Year) containing hourly values (8760 values).

Note

If you are synthesizing this Meteonorm file yourself, the time reference value (the offset in minutes) should always be set to -30.

A TSV file (Tab Separated Variable)

Meteorological data in a Tab Separated Variable format.

Important

The contents must NOT be TMY data. It is expecting consecutive solar records (with the same interval between the records), so mixing up years for different months (that often happens in TMY data) would not work.

Also, if you specify a .dat or .tsv file, ensure that the MeteorologicalConditionsDataset property is NOT set in the EnergyCalculationInputs object in your EnergyCalculationInputs.json file, otherwise it will use that and not your meteorological data file.

Column headers that are supported:

Header Property Expected Range
Date or Time Date time stamp (YYYY-MM-DDThh:mm+OO:OO)*
GHI or SolarTotal or Glob GHI (W/m²) 0 - 1300
DHI or DIF or Diffuse DHI (W/m²) 0 - 1000
POA or Gpoa or Plane Plane of array irradiance (W/m²) 0 - 1300
TAmb or Temp Ambient temperature (°C) -35 - 60
WS or Wind or Speed or WindSpeed Wind speed (m/s) 0 - 50
PW or Water Precipitable water (cm) 0 - 100
Pressure or AP Air pressure (mbar) 750 - 1100
Humidity or RH Relative humidity (%) 0 - 100
Albedo Surface albedo (per unit) 0 - 1

* The format for the date time is ISO 8601 format:

  • YYYY = a four-digit year
  • MM = a two-digit month of the year (01 through 12)
  • DD = a two-digit day of that month (01 through 31)
  • T always needs to be there (as the letter 'T') - denotes the start of the time
  • hh = a zero-padded hour (00 through 23)
  • mm = a zero-padded minute (00 through 59)
  • + or - = if the following offset needs adding or subtracting
  • OO:OO = a zero-padded hour and minute of the offset that need adding to the time stamps in the file to translate them to the local time.

So,

  • If the dates and time stamps are in local time of the PV plant, the offset should be +00:00.
  • If the dates and time stamps are in UTC, and the PV plant is in California (UTC -8), the offset value would be -08:00
  • If the dates and time stamps are in UTC, and the PV plant is in Mumbai, India (UTC +5.5), the offset value would be +05:30

Currently, the minimum data columns required to run the calculation are either of the following column combinations:

  • Date timestamp, GHI, Ambient temperature or
  • Date timestamp, POA, Ambient temperature.

The other columns will be used if provided, otherwise default values will be used.

The valid ranges for the meteorological variables for irradiance are inspired by the physically possible limits in quality control tests for surface radiation (QC-RAD methodology [26]). The rest of variables are defined by empirical estimations. In case the values of the meteorological variables fell outside of the expected range, the values would be capped to the lower or upper limit, whichever applicable.

If the meteorological data have missing records (Not a Number - NaN values), you can choose to use the property MissingMetDataHandling in the EnergyCalculationOptions object, which can be set to FailOnValidation or RemoveTimestamp. The first option is the default and it would return a validation error message indicating the amount of missing values for the required variables to run the calculation. Removing the timestamp will skip that weather record. Note that when skipping any particular weather record, the monthly and annual records will be aggregated by using the next available timestamp for the period missing. This may affect the results of your energy calculation.

Note

SolarFarmer value for missing data or invalid entries is 9999 or -9999. Use any of these values in your TSV file to consider any missing or Not a Number (NaN) values.

The first row should be the column headers. Subsequent rows contain the entries (one for each timestamp). All headers and values separated using a tab. All decimal points for values should use a period (.) as the separator rather than a comma (,) (e.g., 3.141592 rather than 3,141592).

When providing a solar resource file with POA data, the properties SolarMeasurementPlaneAzimuth and SolarMeasurementPlaneTilt must be defined in the EnergyCalculationOptions object. These properties refer to the tilt and azimuth angles of the instrument (e.g., pyranometer) and are used in the calculation. If these values are not set, they will be assumed 0 and the calculations will not be accurate.

Alternatively, you may wish to define your own solar data and set this in the optional MeteorologicalConditionsDataset property (of type MeteorologicalConditionsDataset) in the EnergyCalculationInputs object.

When providing albedo in the solar resource file, the optional property UseAlbedoFromMetDataWhenAvailable in the EnergyCalculationOptions object should be set to true (default is true). The section MonthlyAlbedo remains a required element in the EnergyCalculationInputs object, where the monthly albedo values will be used for any timestamp where the albedo value is NaN. If the property UseAlbedoFromMetDataWhenAvailable is false, the monthly albedo data will be used for the calculation regardless of the presence of an albedo column in the solar resource file.

Horizon files

The files dictionary supplied to the endpoint contains the horFile property for you to supply a horizon file to be used in the energy calculation. This should have a .hor file extension.

If IncludeHorizon is set to True in the EnergyCalculationOptions object, you must supply either a horFile or set the HorizonAzimuths and HorizonAngles in the EnergyCalculationInputs object.

The horizon file is a simple text file containing 361 lines, each with 2 values:

  • an azimuth (in degrees)
  • elevation angle (in degrees). This is the elevation from the horizon.

The azimuth values generally start at -180 and go to 180 in increments of 1.

You have to be careful with the azimuth values as there are different conventions as to what the values mean. These are the conventions that the web API expects if you provide a horizon file:

  • If the site is in the northern hemisphere, azimuth values: -180 = north, -90 = east, 0 = south, 90 = west
  • If the site is in the southern hemisphere, azimuth values: -180 = south, -90 = west, 0 = north, 90 = east

Alternatively you may wish to define your own horizon data and set this in the optional HorizonAzimuths and HorizonAngles properties of the EnergyCalculationInputs input object (these lists should contain the same number of elements, and the indices correspond).

If you define your own horizon data the azimuths should be between 0 and 359 and no matter which hemisphere the site is located: 0 = north, 90 = east, 180 = south, 270 = west.

OND inverter files

You can specify all the OND inverter specification files supplied to the endpoint by using ondFiles for each of the OND files when you add then to the files collection supplied to the endpoint. You can specify up to 50 OND files should they be needed.

The older way of specifying these (ondFile1, ondFile2, and ondFile3) can still be used, but this will eventually be deprecated and the newer ondFiles name should be used instead.

Provide PVsyst .OND inverter files to be used in the calculation. These should be text files (generally from PVsyst version 6.40 onwards) as opposed to binary format, which is not supported.

The filename of the .OND file is important - the InverterSpecID property of the Inverter class should match with the filename (without the .OND extension).

Alternatively you may wish to define your own inverter specification manually using the InverterSpecification class for each one, adding them to the InverterSpecifications property of the PVPlant. If you use .OND files you do not have to define these inverter specifications.
Using .OND files is the recommended way, as defining the values yourself is very prone to mistakes and errors.

PAN module specification files

You can specify all the PAN module specification files supplied to the endpoint by using panFiles for each of the PAN files when you add then to the files collection supplied to the endpoint. You can specify up to 50 PAN files should they be needed.

The older way of specifying these (panFile1, panFile2, and panFile3) can still be used, but this will eventually be deprecated and the newer panFiles name should be used instead.

Provide PVsyst .PAN module specification files to be used in the calculation. These should be text files (generally from PVsyst version 6.40 onwards) as opposed to binary format, which is not supported.

The filename of the .PAN file is important - the ModuleSpecificationID property of the Layout class should match with the filename (without the .PAN extension).

Alternatively you may wish to define your own module specification manually using the ModuleSpecification class for each one, adding them to the ModuleSpecifications property of the PVPlant. If you use .PAN files you do not have to define these module specifications. Using .PAN files is the recommended way, as defining the values yourself is very prone to mistakes and errors.

The EnergyCalculationInputs object

This is the main object supplied to the ModelChain endpoint and the most difficult to set up. We will go through the example file section by section, helping you to understand the different parts.

Location

This is the site's location and is an object of type Location. It is required. Longitude and latitude should be WGS84 and in decimal degrees. Altitude is in metres above sea level.

E.g. (a site in Rome, Italy)

  "Location": {
    "Longitude": 7.371682,
    "Latitude": 46.955067,
    "Altitude": 575.0
  },

PVPlant

This is the main descriptor of the site and is an object of type PVPlant. It is required. It includes all the components, their specifications and how many of each there are and how they are connected.

Transformers, Inverters, Layouts for 2D plants

The Transformers property of the PVPlant object is a list of Transformer objects that are present in the site. It is required.

Each Transformer object contains a list of Inverter objects.

Each Inverter object contains a list of Layout objects.

The Layout objects describe the layout of the strings - the module specification used, the mounting type, the string length, the pitch, azimuth, etc.

This hierarchy defines the electrical configuration of the site for 2D plants. 3D plants are defined slightly differently and are documented in the ModelChainAsync Endpoint page.

An example of one transformer, that includes 1 inverter, which has 1 layout for a 2D fixed-tilt plant:

    "Transformers": [
      {
        "TransformerSpecID": "Transformer Specification 1",
        "TransformerCount": 1,
        "Inverters": [
          {
            "Name": "Sungrow SG125HV APP01",
            "InverterSpecID": "Sungrow_SG125HV_APP",
            "InverterCount": 1,
            "Layouts": [
              {
                "LayoutCount": 1,
                "InverterInput": [
                  0
                ],
                "ModuleSpecificationID": "CanadianSolar_CS6U-330M_APP",
                "MountingTypeID": "Fixed-Tilt Rack Template 1",
                "IsTrackers": false,
                "Azimuth": 180.0,
                "Pitch": 10.0,
                "TotalNumberOfStrings": 15,
                "NumberOfStringsInFrontRow": 0,
                "NumberOfStringsInBackRow": 6,
                "NumberOfStringsInRightRow": 0,
                "NumberOfStringsInLeftRow": 0,
                "NumberOfStringsInIsolatedRow": 0,
                "StringLength": 30,
                "DcOhmicConnectorLoss": 0.0,
                "ModuleMismatchLoss": 0.01,
                "TerrainAzimuth": 0.0,
                "TerrainSlope": 0.0
              }
            ],
            "AcWiringOhmicLoss": 0.0
          },

Note the InverterSpecID values should correspond with the filename of the .OND file that is used.
The ModuleSpecificationID should correspond with the filename of the .PAN file that is used.

ModuleSpecifications

This is a dictionary (keyed by a ModuleSpecificationID string, value of ModuleSpecification object) and is only required if you do not supply .PAN files for the module specifications.

InverterSpecifications

This is a dictionary (keyed by an inverterSpecID string, value of InverterSpecification object) and is only required if you do not supply .OND files for the inverter specifications.

MountingTypeSpecifications

These are required and define the fixed-tilt racks or trackers used in the plant.

It is a dictionary, keyed by the MountingTypeID (that is referred to in the Layout objects) and contains objects of type MountingTypeSpecification.

E.g. a fixed-tilt rack template, with 3 modules high (3 rows of modules running along the length of the rack), the modules are in landscape orientation. The modules are bifacial so the optional TransmissionFactor, BifacialShadeLossFactor and BifacialMismatchLossFactor properties are set.

    "MountingTypeSpecifications": {
      "Fixed-Tilt Rack Template 1": {
        "IsTracker": false,
        "NumberOfModulesHigh": 3,
        "ModulesAreLandscape": true,
        "RackHeight": 2.976,
        "YSpacingBetweenModules": 0.992,
        "FrameBottomWidth": 0.0,
        "ConstantHeatTransferCoefficient": 29.0,
        "ConvectiveHeatTransferCoefficient": 0.0,
        "MonthlySoilingLoss": [
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0,
          0.0
        ],
        "Tilt": 38.79,
        "HeightOfLowestEdgeFromGround": 1.0,
        "TransmissionFactor": 0.0,
        "BifacialShadeLossFactor": 0.02,
        "BifacialMismatchLossFactor": 0.005
      }
    },

TrackerSystems

These are only required for tracker plants. It can be left as null for fixed-tilt plants.

This is a dictionary (keyed by a trackerSystemID string, value of TrackerSystem object). The trackerSystemID key is the same one you set in the Layout object.

Each one defines a system for trackers (system plane tilt and azimuth, GCR, min/max tracker rotation, etc.)

Each Layout in a tracker plant must reference a tracker system.

An example:

    "TrackerSystems": {
      "Layout Region 1": {
        "SystemPlaneAzimuth": 204.25,
        "SystemPlaneTilt": 4.8,
        "TrackerAzimuth": 0.0,
        "EastWestGCR": 0.196,
        "RotationMinDeg": -60.0,
        "RotationMaxDeg": 60.0,
        "IsBacktracking": true
      }
    },

TransformerSpecifications

These are required for all plants.

This is a dictionary (keyed by a transformerSpecID string, value of a TransformerSpecification object).

E.g. a transformer with a simple loss of 0.5% :

    "TransformerSpecifications": {
      "Transformer Specification 1": {
        "ModelType": "SimpleLossFactor",
        "LossFactor": 0.005
      }
    }

Racks and Trackers

These are only used for 3D calculations and aren't required for 2D calculations. So can be ignored for 2D calculations.

MonthlyAlbedo

This is a list of monthly albedo values (each value between 0.0 and 1.0), starting at January and going through the year. It is required.

E.g. (setting 0.2 for all the monthly values)

  "MonthlyAlbedo": [
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2,
    0.2
  ],

MeteorologicalConditionsDataset

Set the contents of this if you don't supply a tmyFile entry in the files input to the endpoint. You must use a file or this property.

It is an object of type MeteorologicalConditionsDataset.

The SolarFarmer desktop application uses this way to specify meteorological conditions. It can be a bit more verbose supplying it this way, but this gives you full control of what you supply.

E.g. (the first couple of entries for yearly met data downloaded from PVGIS for Rome, Italy)

  "MeteorologicalConditionsDataset": {
    "Name": "PVGIS: lat=41.892 lon=12.496",
    "Latitude": 41.891784,
    "Longitude": 12.495867,
    "Elevation": 40.0,
    "OffsetFromUtc": 1.0,
    "TimeOffsetToStartOfFirstIntervalInMinutes": 0,
    "Data": [
      {
        "StartOfPeriod": "2017-09-20T00:00:00+01:00",
        "PeriodInMinutes": 60.0,
        "Hhi": 0.0,
        "Dhi": 0.0,
        "AirTemperature": 16.95,
        "WindSpeed": 0.51,
        "AirPressure": 1004.22,
        "RelativeHumidity": 76.27
      },
      {
        "StartOfPeriod": "2017-09-20T01:00:00+01:00",
        "PeriodInMinutes": 60.0,
        "Ghi": 0.0,
        "Dhi": 0.0,
        "AirTemperature": 16.8,
        "WindSpeed": 0.8,
        "AirPressure": 1004.39,
        "RelativeHumidity": 75.38
      },

      the remaining entries...

HorizonAzimuths

Set the contents of this if you don't supply a horFile entry in the files input to the endpoint and wish to define a horizon to be used in the calculation.

If IncludeHorizon is set to True in the EnergyCalculationOptions object, you must supply either a horFile or set the HorizonAzimuths and HorizonAngles.

This is a list of azimuth values (in degrees) and if this is set you should also set an equal number of values in the HorizonAngles property.

The azimuths should be between 0 and 359 and no matter which hemisphere the site is located: 0 = north, 90 = east, 180 = south, 270 = west.

E.g. (the first few values)

  "HorizonAzimuths": [
    0.0,
    1.0,
    2.0,
    3.0,
    4.0,
    5.0,
    6.0,

HorizonAngles

Set the contents of this if you don't supply a horFile entry in the files input to the endpoint and wish to define a horizon to be used in the calculation.

This is a list of elevation angle values (in degrees from the horizon) that correspond to the equivalent azimuth (with the same index) in the HorizonAzimuths property.

The azimuths should be between 0 and 359 and no matter which hemisphere the site is located: 0 = north, 90 = east, 180 = south, 270 = west.

E.g. (the first few values)

  "HorizonAngles": [
    1.01,
    1.01,
    0.78,
    0.77,
    0.95,
    0.74,

EnergyCalculationOptions

These are the main options for the calculation and is required. It is an object of type EnergyCalculationOptions.

Rather than go through the properties one by one here, see the entry for EnergyCalculationOptions in the reference documentation.

An example:

  "EnergyCalculationOptions": {
    "CalculationYear": 2017,
    "DefaultWindSpeed": 0.0,
    "CalculateDHI": false,
    "IncludeHorizon": false,
    "DiffuseModel": "Perez",
    "TreatCircumsolarAsDirect": false,
    "UseMostShadedCellForDiffuse": false,
    "ModelBackRowSeparately": true,
    "ApplyIAM": true,
    "ApplySpectralMismatchModifier": false,
    "IncludeModulePerformance": true,
    "IncludeCellTemperatureModel": true,
    "IncludeSoilingLossInTemperatureModel": true,
    "UseIAMForTemperatureModel": false,
    "IncludeArrayIV": true,
    "IncludeInverterModel": true,
    "IncludeACModel": true,
    "GridAvailabilityLoss": 0.017,
    "AddTareLossToInverterEfficiencyModel": true,
    "IgnoreLowPowerPointInEfficiencyData": false,
    "ReturnPvSystFormatTimeSeriesResults": true,
    "ReturnDetailedTimeSeriesResults": false,
    "ReturnLossTreeTimeSeriesResults": false
  },

RequestedResultsPVsystFormat

This is not yet used, so is ignored.

It will eventually be a list of variables to be included in the PVsyst format results file that is returned once the calculation has completed.

At the moment the columns in the PVsyst format results file are always the same (though not always in the same order!)

PanFileSupplements

This is a dictionary of values of type PanFileSupplements (indexed by the module specification key (the PAN filename without the .PAN extension)). If there is supplementary data associated with a .PAN file provided to the endpoint then it should be added here. It is not required, the .PAN file is sufficient without these additional data.

E.g.

  "PanFileSupplements": {
    "CanadianSolar_CS6U-330M_APP": {
      "ModelingCorrectionFactor": 1.0,
      "RecalculateModelingCorrectionFactor": false,
      "ModuleQualityFactor": 0.0
    }
  }

Outputs

On successful completion

If the calculation runs successfully an object of type ModelChainResponse will be returned. This has the following properties:

AnnualEnergyYieldResults

This is an list of AnnualEnergyYieldResults objects (one for each year of the meteorological data). Each item in the list contains the annual energy yield results for that year, including monthly break-downs and lists of effects.

This is probably the main object of interest as it has the annual power production and the list of effects.

E.g.

 "annualEnergyYieldResults": [
  {
   "year": 2017,
   "annualEffects": {
    "horizon": 1.322731180020713e-16,
    "nearShadingIrradiance": -0.02450307318212619,
    "soiling": 0,
    "angular": -0.03110260538391524,
    "spectral": 0,
    "backIrradianceGain": 0,
    "bifacialShading": 0,
    "bifacialTransmission": 0,
    "modeling": 0.00013619920151457455,
    "modelingCorrection": 0,
    "temperature": -0.024903375396777484,
    "irradiance": -0.013599987208819143,
    "bifacialityFactor": 0,
    "backIrradianceMismatch": 0,
    "powerBinning": 0.0037499999999999825,
    "lightInducedDegradation": -0.02999999999999973,
    "moduleQuality": 0,
    "moduleMismatch": -0.01000000000000037,
    "electricalMismatch": -0.0008801474407308385,
    "ohmicDc": 0,
    "inverterMinDcVoltage": 0,
    "inverterMaxDcCurrent": 0,
    "inverterMaxDcVoltage": 0,
    "inverterMinDcPower": 0,
    "inverterEfficiency": -0.027859325214977415,
    "inverterMaxAcPower": -0.002476363575977903,
    "inverterOverPowerShutdown": 0,
    "inverterTare": -0.0001878975286666794,
    "ohmicAc": 0.00018793284078301784,
    "transformer": -0.015000000000000523,
    "gridLimit": 0,
    "availability": -0.016999999999999568
   },
   "energyYieldResults": {
    "recordCount": 8841,
    "percentComplete": 99.99999999999983,
    "averageTemperature": 10.607920426907318,
    "ghi": 1192.7340000000002,
    "gi": 1373.3998258765305,
    "giWithHorizon": 1373.3998258765307,
    "gainOnTiltedPlane": 0.15147201796589194,
    "globalEffectiveIrradiance": 1298.0776775552474,
    "modulePower": 556298.973838618,
    "modulePowerAtSTC": 578372.3684781528,
    "nominalEnergy": 578293.605350863,
    "pdc": 535663.7904797235,
    "pac": 519353.412220547,
    "performanceRatio": 0.8220337560898727,
    "netEnergy": 502.9610432866548,
    "energyYield": 1128.9810174784616
   },
   "monthlyEnergyYieldResults": [
    {
     "month": 1,
     "monthlyEffects": {
      "horizon": 0,
      "nearShadingIrradiance": -0.02498524281495762,
      "soiling": 0,
      "angular": -0.024975123532528603,
      "spectral": 0,
      "backIrradianceGain": 0,
      "bifacialShading": 0,
      "bifacialTransmission": 0,
      "modeling": 0.00013619920151465199,
      "modelingCorrection": 0,
      "temperature": 0.03211282929247015,
      "irradiance": -0.020239579079594477,
      "bifacialityFactor": 0,
      "backIrradianceMismatch": 0,
      "powerBinning": 0.0037500000000003065,
      "lightInducedDegradation": -0.029999999999999874,
      "moduleQuality": 0,
      "moduleMismatch": -0.01000000000000012,
      "electricalMismatch": -0.003309308810491629,
      "ohmicDc": 0,
      "inverterMinDcVoltage": 0,
      "inverterMaxDcCurrent": 0,
      "inverterMaxDcVoltage": 0,
      "inverterMinDcPower": 0,
      "inverterEfficiency": -0.037535899644026725,
      "inverterMaxAcPower": 0,
      "inverterOverPowerShutdown": 0,
      "inverterTare": -0.00045586064924156463,
      "ohmicAc": 0.00045606855294821023,
      "transformer": -0.015000000000000995,
      "gridLimit": 0,
      "availability": -0.016999999999999117
     },

InputsDerivedFileContents

This contains some internal derived constants that are calculated from the inputs you provide. It is here just for interest and to aid troubleshooting, so not critical to look at and understand.

ResultsFile

This is time-series data for the calculation. It is text for a TSV file (Tab Separated Values) that contains values for each time-step along with various values used in the model chain calculation.

It will only be set if you set the ReturnDetailedTimeSeriesResults property in the EnergyCalculationOptions class to true, otherwise it will be an empty string.

Again, not crucial to look at but can be very interesting if you want a deeper look at the calculation results for certain time-steps.

PvSystFormatResultsFile

This is time-series data in the PVsyst format (semi-colon separated) that you may be familiar with. It contains several lines of headers before the column headers and the values. The column names are the standard columns that you get from running a calculation in PVsyst and saving the results.

It will only be set if you set the ReturnPvSystFormatTimeSeriesResults property in the EnergyCalculationOptions class to true, otherwise it will be an empty string.

Currently the columns may appear in any order, so be careful when opening and parsing the file.

The columns that appear are set in the calculation at the moment. Eventually you may be able to set the required columns you are interested in by using the RequestedResultsPVsystFormat property of the EnergyCalculationInputs object (which is currently ignored).

See Cloud Time-Series Results Files for a description of the output values.

LossTreeResults

This is time-series data containing loss tree results for each time-step. It is text for a TSV file (Tab Separated Values) that contain values for each time-step. Each value is an energy in kWh for a certain step in the model chain calculation.

It will only be set if you set the ReturnLossTreeTimeSeriesResults property in the EnergyCalculationOptions class to true, otherwise it will be an empty string.

Useful if you want a deep dive into what is going on in the calculation, but not critical to understand.

TotalModuleArea

The total active module area (in m²) of the site that was used in the calculation.

SystemAttributes

Details of some of the system attributes of the calculation that was run.

An example output for this property is:

{
  "location": {
    "longitude": -2.579543,
    "latitude": 51.452176,
    "altitude": 31.0
  },
  "acCapacityInMegawatts": 24.7,
  "dcCapacityInMegawatts": 30.096,
  "is3D": false,
  "mounting": "Single-axis trackers",
  "solarFarmerCoreVersion": "0.2.197.0",
  "solarFarmerApiVersion": "0.2.223"
}

The values for 'mounting' can be 'Single-axis trackers' or 'Fixed-tilt racks'.

On calculation failure

If the calculation fails, e.g. due to a validation error, or some other reason, then an object of type ProblemDetails will be returned.

The main properties of this class that will be useful are:

  • Detail which can contain an error message.
  • Errors which can contain one or more errors in a dictionary (key, and list of errors for that key)

If there is an issue with authentication or authorization, you may not get a ProblemDetails object back. In which case the text property of the Response object may contain some useful information.

Some example python code to handle and print these error possibilities is:

if (response.status_code >= 400):
    print(f"API request failed. Error status code: {response.status_code}")
    print(f"Reason: {response.reason}")

    try:
        # Try and convert the response to a JSON object, which it will be if a ProblemDetails
        # object has been returned (e.g. for validation errors)
        json_response = response.json()
        print(f"Title:  {json_response['title']}")
        if not (json_response.get('errors') is None):
            print("Errors: ")
            for errorKey, errors in json_response['errors'].items():
                for error in errors:
                    print(error)
        if not (json_response.get('detail') is None):
            print(f"Detail: {json_response['detail']}")
    except Exception:
        # couldn't get JSON from the response.  Just print out the text
        print(f"Message: {response.text}")