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

  1. 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: 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:
      • An object of type Response2 (contains an id - the instance ID, and an optional errorString)
      • An object of type ProblemDetails if the request is unsuccessful. See On calculation failure for more details on this.

  2. This POST request immediately returns, returning an Instance ID value that uniquely identifies this calculation run.

  3. 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:
    • This GET request immediately returns and the output includes a runtime status
    • The runtime status will change from Pending, Running to eventually Completed
    • 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

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.