The 'ModelChain' Endpoint
Definition
The ModelChain
endpoint runs the energy calculation. This will probably be the principal endpoint that you
use with the web API.
- API endpoint:
https://solarfarmer.dnvgl.com/api/ModelChain
- It is a HTTP POST request
- Inputs:
- projectNumber: (int) - a number for the project - used to group related runs and for billing
- files
- tmyFile - either a Meteonorm .dat file or TSV file
- horFile - a horizon file
- ondFile1 - 1st OND inverter file
- ondFile2 - 2nd OND inverter file
- ondFile3 - 3rd OND inverter file
- panFile1 - 1st PAN module specification file
- panFile2 - 2nd PAN module specification file
- panFile3 - 3rd PAN module specification file
- request - an object of type
EnergyCalculationInputs
- Outputs:
- An object of type
ModelChainResponse
- An object of type
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 Schemas section of https://solarfarmer.dnvgl.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
The tmyFile
property in the files
dictionary supplied to the endpoint refers to the solar resource file
to be used by the calculation. Currently this can be one of 2 formats:
A Meteonorm PVsyst Hourly TMY (
.dat
) fileThis should be a TMY (Typical Meteorological Year) containing hourly values (8760 values).
Just a note, if you are synthesizing this yourself, the time reference value (the offset in minutes) should always be set to -30.
A TSV file (Tab Separated Variable)
Column headers that are supported:
Header Property Expected Range Date
orTime
Date time stamp (YYYY-MM-DD hh:mm:ss) GHI
orSolarTotal
orGlob
GHI (W/m²) 0 - 2000 DHI
orDIF
orDiffuse
DHI (W/m²) 0 - 2000 TAmb
Ambient temperature (°C) -60 - 60 WS
orWind
orSpeed
Wind speed (m/s) 0 - 100 PW
orWater
Precipitable water (cm) 0 - 100 Pressure
orAP
Air pressure (mbar) 900 - 1100 Humidity
orRH
Relative Humidity (%) 0 - 100 You always need the following columns: Date time stamp, GHI, Ambient temperature.
The other columns will be used if provided, otherwise defaults will be used.
Note: POA (Plane Of Array) data is not yet supported by the SolarFarmer API.
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).See the Solar Resources section in the User Guide for a bit more information on this, including formatting the date format.
Alternatively you may wish to define your own solar data and set this in the optional meteorologicalConditionsDataset
property
(of type MeteorologicalConditionsDataset
) of the EnergyCalculationInputs
object.
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
The files
dictionary supplied to the endpoint contains 3 properties where you can specify up to 3 .OND
inverter
files to be used in the calculation: ondFile1
, ondFile2
, and ondFile3
(use these in order).
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
The files
dictionary supplied to the endpoint contains 3 properties where you can specify up to 3 .PAN
module specification
files to be used in the calculation: panFile1
, panFile2
, and panFile3
(use these in order).
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 will be added to the documentation once they are supported by the API.
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
},
See the class descriptions in the Schemas section of https://solarfarmer.dnvgl.com/docs for more details on what each of the properties mean.
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 the upcoming 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,
"ghi": 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 Schemas
section of https://solarfarmer.dnvgl.com/docs for more details on each property.
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
},
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
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.
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.
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).
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.
Useful if you want a deep dive into what is going on in the calculation, but not critical to understand.