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 billingfiles
: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 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
Response2
(contains anid
- the instance ID, and an optionalerrorString
) - An object of type ProblemDetails if the request is unsuccessful. See On calculation failure for more details on this.
- 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 ProblemDetails if the request is unsuccessful. See On calculation failure for more details on this.
- 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.
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, ModuleIndexRanges,
The Transformers property is the same as for 2D sites.
However, each Inverter object (in the Inverters property of the Transformer class) 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.
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.