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 billingfiles
: 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 fileondFiles
- set all OND inverter files with this first valuepanFiles
- 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:
- An object of type ModelChainResponse if the request is successful.
- An object of type ProblemDetails if the request is unsuccessful. See On calculation failure for more details on this.
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
- in the SolarFarmerApi.Client reference page
- in the Schemas section of the Web API website here: https://solarfarmer.dnv.com/docs.
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:
- The
tmyFile
property (as described above), or - The
metDataTransferFile
property (as described above), or - 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 yearMM
= 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 timehh
= a zero-padded hour (00 through 23)mm
= a zero-padded minute (00 through 59)+
or-
= if the following offset needs adding or subtractingOO: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}")