SolarFarmer Web API Release Notes
These are the different releases of the SolarFarmer web API and notes (breaking changes, web API class changes, enhancements, bug fixes).
The web API is usually released at the same time as a new release of the SolarFarmer desktop application, but may not always be.
API 0.2.249 (22 November 2022)
[SF-Core 0.2.215.0]
Added support for shading objects and POA-only met data in the 3D API
Calculation
Calculation features
- Added support for shading objects in 3D API (when provided)
- Shading regions and 3D shading objects are now used for beam and diffuse shading for 3D racks
- Shading regions and 3D shading objects are now used for diffuse shading for 3D trackers (only row-to-row shading is currently used for beam shading for trackers (like the local calculation))
- Added support for POA-only (Plane Of Array) solar resources
- API handles met data transfer files (compressed files currently sent from the desktop app)
Calculation bugs fixed
- Fixed issue when requesting detailed time series results for 3D calculations
- Module Quality Factor validation range too strict (lower end now changed to -40%)
Website
Website features
- None of significance
Website bugs fixed
- Can't cancel regenerate token dialog on home page
Breaking changes
Layout
class (used in 2D calculations with theModelChain
endpoint)- 3 properties (
TransmissionFactor
,BifacialShadeLossFactor
, andBifacialMismatchLossFactor
) relating to bifacial modules have now been marked as Obsolete. They have been commented as 'deprecated' for the last few releases. - These 3 properties will still work in the calculation, but you should now use the equivalent properties in the
MountingTypeSpecification
class instead. - These 3 properties will be removed from the
Layout
class in the next release of the API in early 2023, so change any code now to use the equivalents in theMountingTypeSpecification
instead.
- 3 properties (
Web API class changes
PVPlant
class- Addition of
ShadingObjects
andSimpleTerrain
properties
- Addition of
IndexedObject3D
class added to describe a 3D shading objectSimpleTerrainDto
,MiniSimpleTerrainDto
,TerrainRowDto
andTerrainRowStartEndColumnsDto
classes added to describe a simple terrain object used for shadingMeteorologicalCondition
classGhi
property is now optional (if not set,Poa
property must be set)Poa
optional property added
EnergyCalculationOptions
classSolarMeasurementPlaneAzimuth
andSolarMeasurementPlaneTilt
properties added. Used to define the solar measurement plane used when POA met data is used.
Layout
class (used in 2D calculations with theModelChain
endpoint)- As explained in the Breaking changes section above, 3 properties (
TransmissionFactor
,BifacialShadeLossFactor
, andBifacialMismatchLossFactor
) relating to bifacial modules have now been marked as Obsolete. They have been commented as 'deprecated' for the last few releases. - These 3 properties will still work in the calculation, but you should now use the equivalent properties in the
MountingTypeSpecification
class instead. - These 3 properties will be removed from the
Layout
class in the next release of the API in early 2023, so change any code now to use the equivalents in theMountingTypeSpecification
instead.
- As explained in the Breaking changes section above, 3 properties (
API 0.2.242 (28 July 2022)
[SF-Core 0.2.208.0]
3D API private preview ready for use!
The ModelChainAsync
endpoint (that is used to run 3D calculations) is now available for users in private preview.
- See ModelChainAsync Endpoint for details on the endpoint
- See ModelChainAsync Endpoint Tutorial for a tutorial on how to use it
- See Generating API input files from the SolarFarmer desktop application for how to generate some input files from the SolarFarmer desktop application to use with the endpoint
The TerminateModelChainAsync
endpoint is also available to terminate unwanted ModelChainAsync
calculations
- See TerminateModelChainAsync Endpoint for details on this endpoint
- See TerminateModelChainAsync Endpoint Tutorial for a tutorial on how to use it
Calculation
Calculation features
- Improved efficiency of 3D tracker calculation with multiple layout regions
Renaming of some variables in the PVsyst output file to avoid confusion between existing PVsyst variable names and similar (but different) SolarFarmer variables (see the whole list in Cloud Time-Series Results Files):
Old header New header GlobIAM GlobHrzIAM GlobSlg GlobHrzSlg ShdLoss ShdLossTotal ShdDLss ShdDLssTotal ShdALss ShdALssTotal ShdBLss ShdBLssTotal GlobShd GlobShdTotal GlobEff GlobEffTotal GlobGnd GlobGndShd
Calculation bugs fixed
- Unexpected record count reported
- Air pressure validation is too strict
- PVsyst calculation output variable names are confusing
- "BackShd" in PVsyst output file is incorrect
- Incorrect tracker rotation causing shading when forcing to horizontal in 2D calculation
- Tracker min/max rotation not correctly considered for sites with side slope
- Including tare loss in efficiency model causes problems for some inverters
- Problem with solar resource data with just night values in one month
- Transformer no-load losses not included in PVsyst output
Website
Security enhancements
- General tightening up of security around the API and website
- Allow users to regenerate their own API tokens
- Multi Factor Authentication added to the website for added security
- API tokens now not shown in the Web UI - only allow them to be copied to the clipboard
- Improved website experience if your API token has expired or your account is disabled
Website features
- Add pagination and filtering to model chain runs table
- Add 'Calculation Status' column to model chain runs table
Website bugs fixed
- Blank Name and Email columns in Model chain run table for non-admin users
- Website holds onto local cache even after logging out
Breaking changes
- The renaming of some of the variables in the PVsyst output file - see above for details.
- The
saveDetails
parameter has been removed from theModelChain
andModelChainAsync
endpoints so calculation inputs and outputs can no longer be stored (and then accessed via the website). We need to think through how users' data is stored and for how long (and if it is still useful) before this is enabled again.
Web API class changes
None of significance.
API 0.2.223 (3 March 2022)
[SF-Core 0.2.197.0]
2D model chain calculation bug fixes. Ongoing preparation for 3D calculations.
Breaking changes
ProjectID
(a string) is now used as a parameter to the ModelChain endpoint instead ofProjectNumber
(which was an integer) If you continue to useProjectNumber
it will be ignored and theProjectId
value will be empty
Enhancements
saveDetails
property (boolean) has been added to theModelChain
endpoint. Set totrue
to save the inputs and outputs of the calculation in the cloud.- New options for requesting the time-series results when running calculations in the cloud (the
returnPvSystFormatTimeSeriesResults
,returnDetailedTimeSeriesResults
andreturnLossTreeTimeSeriesResults
properties in theEnergyCalculationOptions
class. - Separate ability to run 2D and 3D calculations in the cloud and provide UI and support for managing this
- Provide system attributes file from cloud calculations (location, AC and DC capacity, is 3D, racks/trackers, library versions)
- Improved UI in web API website - order tables by values in columns, clearer home page
- General speed up improvements
Bug fixes
- User-defined module parameters are not considered in cloud calculation
- Cloud time-series files are saved even when empty
- 'RackHeight' in cloud JSON doesn't take frame into account
- API always generates selected time-series files even when not asked
- Cloud status not correct when not successful
- Website being cached and not showing latest version
- DC ohmic losses are different in 2D and 3D calculations
- Electrical mismatch effects are reported incorrectly
- Grid Energy does not consider night-time tare losses
- Beam shading for trackers in cloud differs from local calculation
- Cloud calculation failing when used with irregular met data
- Unexpected overpower shutdown losses
- ShdLoss is given in W instead of W/m² in PVsyst time-series results when run in cloud
Web API class changes
These changes relate to 2D calculations.
You may notice a few classes and properties relating to 3D calculations. These are for internal use only at the moment and are for developing the 3D calculation (coming soon!). So please ignore them for now.
ModuleSpecification class
NameplatePower
property added- The nameplate power (nominal power) of the module measured at STC and corresponds to the PNom property in the PAN file. In Watts.
EnergyCalculationOptions class
ReturnPvSystFormatTimeSeriesResults
property added- Generate and return PVsyst-format time-series results (defaults to true)
ReturnDetailedTimeSeriesResults
property added- Generate and return detailed time-series results (defaults to false)
ReturnLossTreeTimeSeriesResults
property added- Generate and return detailed loss tree time-series results (defaults to false)
ModelChainResponse class
TotalModuleArea
property added- The total active module area (in m²) considered by the energy calculation.
SystemAttributes
property added- Of type
SystemAttributes
- details some of the system attributes (e.g. location, AC capacity, DC capacity, is 3D, mounting type, SF-Core and SF-API versions used)
- Of type
LossTree
property added- A list of
LossTreeResultForMonth
objects. Additional loss tree objects (for each month). Mainly used for more in-depth studies.
- A list of
API 0.2.64 (23 August 2021)
[SF-Core 0.2.172.0]
2D model chain calculation improvements. Ongoing preparation for 3D calculations.
Breaking changes
No breaking changes
Enhancements
- Support slopes in 2D. No longer fixed to be horizontal only.
- Automatically used when calling from the SolarFarmer desktop application
- Set the slope using the new
TerrainAzimuth
andTerrainSlope
properties of theLayout
class
- Web API documentation added to the online SolarFarmer documentation (https://dnvgldocs.azureedge.net/SolarFarmer_Latest/index.html), including some tutorials to help get you started.
- Allow user to configure resolution of IV curve
- Output the irradiance on the ground
- Breakup ground into shade and unshaded regions
- Add SF-Core version to PVsyst formatted CSV output
- Add option flag to use diffuse on most shaded cell
Bug fixes
- Results from 2D tracker sites slightly different each time you run it
- Calculation fails 'Voltage requested was not within known IV curve range'
- Bad .hor file doesn't lead to useful error message
- Time series .tsv file entries in wrong columns sometimes
Web API class changes
These changes relate to 2D calculations.
You may notice a few classes and properties relating to 3D calculations. These are for internal use only at the moment and are for developing the 3D calculation (coming soon!). So please ignore them for now.
EnergyCalculationInputs class
SolarPositions
property added (optional)- Allows you to specify your own solar positions. Usually left empty so that the calculation automatically calculates them.
PVPlant class
TrackerSystems
property added (required now for tracker plants)Important
This is the new way to define tracker systems and should be used going forward. Please change any existing code you have and start to use TrackerSystems for tracker plants.
Layout class
TransmissionFactor
,BifacialShadeLossFactor
,BifacialMismatchLossFactor
deprecated properties- These will be deprecated from the
Layout
class. - They have been moved to the
MountingTypeSpecification
class. - Please change code to use them there.
- For this release they are in both places (the
MountingTypeSpecification
property, if set, will take precedence), but in future releases they will only be present in theMountingTypeSpecification
class.
- These will be deprecated from the
TrackerSystemID
property added (required for tracker plants)- Used to reference the
TrackerSystem
to use (if trackers) for theLayout
- Please use this property for tracker plants from now on
- Used to reference the
TerrainAzimuth
andTerrainSlope
properties added (both optional and default to 0)- Defining these you can set the slope of the layout. Set them both to 0 for a horizontal layout.
TrackerSystem class
- New class! Please use this now to define tracker systems.
- Add them to the
PVPlant.TrackerSystems
dictionary (keyed by the trackerSystemID). Then reference them using theLayout.TrackerSystemID
property.
MountingTypeSpecification class
IsBackTracking
,MinRotation
,MaxRotation
deprecated properties- These will be deprecated from the
MountingTypeSpecification
class. - They have been moved to the
TrackerSystem
class. - Please change code to use them there.
- For this release they are usable in both places (the
TrackerSystem
property, if set, will take precedence), but in future releases they will only be present in theTrackerSystem
class.
- These will be deprecated from the
HeightOfTrackerCenterFromGround
property added (optional)- Use to set the height of the tracker center from the ground (if specifying a tracker)
TransmissionFactor
,BifacialShadeLossFactor
,BifacialMismatchLossFactor
properties added- These have been moved from the
Layout
class
- These have been moved from the
EnergyCalculationOptions class
ModelBackRowSeparately
property added (relevant for bifacial plants only) (defaults to true)- If set to true, the back-irradiance for bifacial of the back row of the array will be treated separately. There will be no near-shading loss applied to the back-irradiance of the back row.
- If set to false, the back row will get the same back-irradiance as any other row in the array.
ModuleMismatchBinWidth
property added (optional: defaults to 0.000001)- The bin width to use for module mismatch (defaults to 0.000001)
ConnectorResistanceBinWidth
property added (optional)- The bin width to use for the connector resistance (optional: defaults to 0.000001)
- This is required because the connector resistance is defined per layout, so if we are considering whether two modules from different layout are in-fact in equivalent operating conditions we need to compare the connector resistance.
IrradianceBinWidth
property added (optional: defaults to 1 W/m²)- The bin width to use for irradiance
TemperatureBinWidth
property added (optional: defaults to 0.1°C)- The bin width to use for temperature
IvCurveSize
property added (optional: defaults to 500)- The number of points in the IV curve that is calculated
SolarPositions class
- New class. Use with the
EnergyCalculationInputs.SolarPositions
property if you want to specify your own solar positions for the timestamps. Usually letting the calculation calculate the solar position is recommended, unless you wish to try alternative algorithms.
EnumTechnology enum
HIT
option added (Panasonic Heterojunction with Intrinsic Thin-layer technology)
API 0.2.51 (2 June 2021)
[SF-Core 0.2.148.0]
The first release of the web API! Support for 2D energy calculations.
The SolarFarmer desktop application can use the ModelChain endpoint of the web API to run 2D calculations for sites.
The ModelChain endpoint is available to be used from other applications and scripts too.