The ModelChainAsync
Endpoint
Definition
The ModelChainAsync
endpoint runs the energy calculation in an asynchronous way. It takes longer, but is more powerful and is
intended to be used for very complex 2D calculations and all 3D calculations.
- API endpoint:
https://solarfarmer.dnv.com/api/ModelChainAsync
Send a POST request to the
ModelChainAsync
endpoint to start the calculation- Inputs:
projectId
: (string) - an identifier for the project - used to group related runs and for billing- files
tmyFile
- either a Meteonorm .dat file or TSV filehorFile
- a horizon fileondFile1
- 1st OND inverter fileondFile2
- 2nd OND inverter fileondFile3
- 3rd OND inverter filepanFile1
- 1st PAN module specification filepanFile2
- 2nd PAN module specification filepanFile3
- 3rd PAN module specification file
request
- an object of typeEnergyCalculationInputs
(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
Response2
(contains anid
- the instance ID, and an optionalerrorString
)
- An object of type
- Inputs:
This POST request immediately returns, returning an Instance ID value that uniquely identifies this calculation run.
In a loop, send a polling GET request to the
ModelChainAsync
endpoint every few seconds, providing the Instance ID returned above.- Inputs:
instanceId
: (string) - the instance ID returned from the POST request above
- Output:
- An object of type
ModelChainAsyncQueryResponse
- An object of type
- This GET request immediately returns and the output includes a runtime status
- The runtime status will change from
Pending
,Running
to eventuallyCompleted
- The custom status in the output is set with some useful progress reporting so you can monitor how the calculation is progressing
- Then you can retrieve the calculation results from the output object once its runtime status is
Completed
- Inputs:
See the ModelChainAsync Endpoint Tutorial to learn how to use this endpoint.
Input files
See the Input Files section of the ModelChain
endpoint
for more details on the input files.
Outputs
See the Outputs section of the ModelChain
endpoint for more
details on the outputs.
Important
There is currently a bug if you choose to output the detailed results file with 3D calculations.
If you set the ReturnDetailedTimeSeriesResults
property to be true
in the EnergyCalculationOptions
there
is a high chance of it failing.
This is a known issue and will be fixed in the next release. So please make sure you set this property to false
for now.
It is mainly used for internal testing so hopefully won't be too big of a problem.
The EnergyCalculationInputs
object
See the EnergyCalculationInputs section
of the ModelChain
endpoint for more details on the EnergyCalculationInputs
object.
This object is the same class as the one used in the ModelChain
endpoint. However, there are some differences as to
how it is populated for the definition of 3D sites, rather than 2D sites.
location
This is the same as for 2D sites
pvPlant
This varies the most, as described below:
transformers, inverters, inverterInputs, moduleStrings, moduleIndexRange
The transformers
property is the same as for 2D sites.
However, each Inverter
object (in the inverters
property of the transformers
property) has an empty layouts
property. The layouts are only used for 2D sites.
Instead, the inverterInputs
property contains one or more InverterInput
objects.
Each InverterInput
contains, among other things, the moduleStrings
property, which is a list of ModuleString
objects
describing the strings of modules attached to the inverter input. These are described by a list of ModuleIndexRange
objects,
which defines how the strings are laid out on the racks/trackers.
An example of a 3D plant, with a transformer, an inverter, and some module strings on the inverter:
"pvPlant": {
"transformers": [
{
"transformerSpecID": "Transformer Specification 1",
"transformerCount": 1,
"inverters": [
{
"name": "PV Powered PVP 260KW_NIST",
"inverterSpecID": "PVP 260KW_NIST",
"inverterCount": 1,
"layouts": [],
"inverterInputs": [
{
"moduleSpecificationID": "CanadianSolar_CS6U-330M_APP",
"moduleStrings": [
{
"moduleIndexRanges": [
{
"mountingID": 11137,
"startX": 11,
"endX": 0,
"y": 0
}
]
},
{
"moduleIndexRanges": [
{
"mountingID": 11137,
"startX": 11,
"endX": 0,
"y": 1
}
]
},
racks and trackers
Also, as part of the PVPlant
object the racks
or trackers
properties should be populated (depending on the type
of site layout). These define the 3D positions of the racks or trackers in the layout.
Here's an example of a Rack
object defining a single rack. The id
is referenced in the moduleStrings
above.
The order of the points should be anti-clockwise around the rack.
"racks": [
{
"id": 11133,
"mountingTypeID": "Fixed-Tilt Rack Template 1",
"quad": {
"p1": {
"x": 633616.55525403516,
"y": 4502376.1064225091,
"z": 308.44455607951465
},
"p2": {
"x": 633616.60684414359,
"y": 4502378.5736383246,
"z": 310.10791430261804
},
"p3": {
"x": 633640.11553953763,
"y": 4502378.5736383246,
"z": 309.37877723037911
},
"p4": {
"x": 633640.0639494292,
"y": 4502376.1064225091,
"z": 307.71541900727573
}
},
"pitchToFront": 10.0
},
Here's an example of a Tracker
object (in the trackers
list of the pvPlant
) defining a single tracker. Again,
the id
is referenced in the moduleStrings
above.
Just 2 points are required, the northPoint
and southPoint
which are the points at the centre of the north and south edges of
each tracker.
"trackers": [
{
"id": 42367,
"mountingTypeID": "Tracker Template Specification 3",
"trackerSystemID": "Layout Region 1",
"northPoint": {
"x": 375600.23539992177,
"y": 5194354.8559622234,
"z": 685.273056633745
},
"southPoint": {
"x": 375600.23539992177,
"y": 5194336.0213979082,
"z": 685.98459797451073
},
"pitchToRight": 10.0
},
Apart from the simplest of sites, these are going to be challenging for you to generate manually (or through your
own scripts). To get a feel of how they are put together it will be worth playing with simple 3D sites in the
SolarFarmer desktop application and generating the EnergyCalculationInputs
object from there (see Generating API input files from the SolarFarmer desktop application).
You can then see the equivalent layout in the desktop tool, which will help with your understanding of the classes and how they are used.
Note
All classes (including descriptions of classes and their properties) referred to below can be found in the Schemas section of https://solarfarmer.dnv.com/docs.
Why calculation times may vary
When using the ModelChainAsync
endpoint (or running a 3D calculation from the SolarFarmer desktop application in the cloud)
you may notice that the calculation times can sometimes vary dramatically.
This is due to the way it is currently implemented. The calculation is broken into smaller sub-calculations (both for the shading calculation and the main energy calculation). These sub-calculations can be run in parallel on different nodes in the cloud, and it can take some time to spin-up multiple nodes to run them on. If there aren't already multiple nodes up and running this spin-up time can add to the calculation time.
If there are already many nodes available then calculations can be much quicker.