API Reference¶

The SolarFarmer Python SDK is the official Python client for the SolarFarmer energy calculation service. This page documents all publicly exported functions and classes.

Overview¶

The SolarFarmer SDK is organized into the following main categories:

Core Functions & Classes¶

Endpoint Functions: Core functions for making API calls
Main Classes: Key data models for calculations and plant design

Configuration & Design¶

Plant Configuration Classes: Location, layout, and inverter specifications
Module and Equipment Specifications: Mounting types, trackers, and component files

Advanced Options¶

Advanced System Configuration: Transformers, grid limits, and auxiliary losses
Additional Configuration Classes: Albedo and other environmental factors

Endpoint Functions¶

These are the primary functions for interacting with the SolarFarmer API.

`run_energy_calculation()`¶

Runs the energy calculation by making a call to SolarFarmer ModelChain or ModelChainAsync endpoints. These endpoints perform the energy calculation of the SolarFarmer model. The ModelChain endpoint is used for 2D (simple shading model) calculations, while the ModelChainAsync endpoint is generally used for multi-year 2D calculations and 3D (full shading model) calculations.

Parameters:

Name	Type	Description	Default
`inputs_folder_path`	`str or Path`	Path to a folder containing all required inputs. If provided, the function may resolve inputs (e.g., OND, PAN, horizon file, meteorological file, and calculation inputs) from this folder.	`None`
`project_id`	`str`	Identifier for the project, used to group related runs and for billing	`None`
`energy_calculation_inputs_file_path`	`str`	Path to an `EnergyCalculationInputs.json` file (as exported from the SolarFarmer desktop application)	`None`
`meteorological_data_file_path`	`str`	Path to a solar resource file. Accepts Meteonorm `.dat`, TSV, a SolarFarmer desktop export (e.g., `MeteorologicalConditionsDatasetDto_Protobuf.gz`), or PVsyst standard format `.csv` files	`None`
`horizon_file_path`	`str`	Path to a horizon file	`None`
`ond_file_paths`	`list of str`	One or more paths to OND inverter files. At least one OND file is required if not provided via `modelchain_payload` or `folder_path`	`None`
`pan_file_paths`	`list of str`	One or more paths to PAN module specification files. At least one PAN file is required if not provided via `modelchain_payload` or `folder_path`	`None`
`print_summary`	`bool`	If True, it will print out the summary of the energy calculation results. Default is True	`True`
`outputs_folder_path`	`str or Path`	Path to a folder that will contain all the requested outputs from the energy calculation. If the path does not exist, it will be created. If the path is not provided, an output folder named `sf_outputs_<TIMESTAMP>` will be created in the same directory than `inputs_folder_path` or `energy_calculation_inputs_file_path`	`None`
`save_outputs`	`bool`	If True, it will save the results from the API call in the `outputs_folder_path` or in a newly created folder `sf_outputs_<TIMESTAMP>`. Default is True	`True`
`api_version`	`str or None`	API version selector. Accepted values: - None : returns `base_url` as-is - 'latest' : uses the 'latest' version path - 'vX' : where X is a positive integer, e.g., 'v6' Default is 'latest'	`'latest'`
`force_async_call`	`bool`	If True, forces the use of the asynchronous ModelChain endpoint even when the synchronous endpoint could be used. Default is False	`False`
`plant_builder`	`str or SolarFarmerBaseModel`	The API payload. Accepts a `SolarFarmerBaseModel` instance (e.g. `EnergyCalculationInputs`) or a pre-serialized JSON string	`None`
`api_key`	`str`	SolarFarmer API key. If not provided, the `SF_API_KEY` environment variable is used	`None`
`api_url`	`str or None`	If provided, this URL will be used as the base URL for the API call, overriding the default URL. When `api_url` is provided, `api_version` is ignored. This is a per-call override of the `SF_API_URL` environment variable (see `config.BASE_API_URL`). Must be a valid `http` or `https` URL.	`None`
`time_out`	`int`	Request timeout in seconds, overriding the endpoint default	`None`
`async_poll_time`	`float`	Polling interval in seconds between status checks for asynchronous calculations. Defaults to `MODELCHAIN_ASYNC_POLL_TIME`	`None`
`**kwargs`	`Any`	Additional query parameters forwarded verbatim to the API request	`{}`

Returns:

Type	Description
`CalculationResults or None`	An instance of CalculationResults with the API results for the project, or None if the calculation failed or was terminated

`about()`¶

Makes a call to SolarFarmer About endpoint. This endpoint requests the versions of the libraries used by the current SolarFarmer Web API server.

Parameters:

Name	Type	Description	Default
`version`	`str`	SolarFarmer API version selector. Accepted values: - None : it will use the latest version available - 'latest' : uses the 'latest' version path - 'vX' : where X is a positive integer, e.g., 'v5'	`None`
`**kwargs`		Additional keyword arguments.	`{}`

`service()`¶

Makes a call to SolarFarmer Service endpoint. This endpoint requests the services (their names as strings) available to the user whose API token is being used.

`terminate_calculation()`¶

Use the TerminateModelChainAsync endpoint to terminate a running calculation that was initiated with a call to the ModelChainAsync endpoint.

Parameters

instance_id : str The instance ID returned from the POST request to the ModelChainAsync endpoint that you wish to terminate. reason : str, optional Reason for terminating the calculation.

api_version : str, default="latest" API version selector. Accepted values: - None : returns base_url as-is - 'latest' : uses the 'latest' version path - 'vX' : where X is a positive integer, e.g., 'v5'

Main Classes¶

The core classes handle the complete workflow from plant design to results analysis:

PVSystem: Main class for constructing approximated PV plant designs from high-level specifications (location, capacity, equipment). Infers layout geometry and losses using simplified assumptions; results are suitable for screening, not detailed design
EnergyCalculationInputs: Root Pydantic model composing all inputs for a calculation run
PVPlant: Pydantic model describing the PV plant structure (transformers, mounting specs, etc.)
ModelChainResponse: Container for raw API response data from energy calculations
CalculationResults: Analysis tools for exploring and visualizing energy yield results

PVSystem¶

This is the main class to define a PV System using basic metadata and design characteristics. It is also a calculation entrypoint for the defined plant. It has multiple properties that can be set or left as default, depending on the level of detail available to the user. The class is designed to be flexible and user-friendly, with sensible defaults and validation to ensure that the provided data is consistent and complete for the API calculation.

.. note:: PVSystem generates an approximated plant design from high-level specifications. It infers layout geometry, string sizing, and loss parameters using simplified assumptions (e.g., uniform mid-row shading). Results are suitable for early-stage energy yield screening but do not represent a fully detailed design.

Basic Metadata

name: str | None Name of the plant/project. Optional.

Location Metadata

latitude : float | None Plant latitude in degrees (-90 .. 90). longitude : float | None Plant longitude in degrees (-180 .. 180). altitude : float | 0.0 Plant altitude in meters above sea level. timezone : str IANA timezone name (e.g., 'UTC', 'Europe/Amsterdam'). Default is 'UTC'.

Plant Definition

dc_capacity_MW : float Plant DC capacity in MW (default 10.0). ac_capacity_MW : float Plant AC capacity in MW (default 10.0). grid_limit_MW : float Grid capacity limit for the plant connection in MW (default 10.0). gcr : float Ground coverage ratio (default 0.5). Define either gcr or pitch, not both. pitch : float Array pitch in meters (default 10.0). Define either gcr or pitch, not both. tilt : float Array tilt in degrees. For fixed-tilt mounting, the default is the latitude rounded to degrees. For trackers, this is the used as the maximum rotation angle (60 degrees if not specified). azimuth : float Array azimuth in degrees (default 180, i.e., south-facing). mounting: str Mounting configuration: 'Fixed' for fixed-tilt or 'Tracker' for single-axis trackers. flush_mount : bool If True, indicates flush-mounted arrays (default is False). bifacial: bool If True, indicates bifacial modules (default is False). inverter_type: str Inverter type: 'Central' or 'String' (default is 'Central'). Affects the default DC and AC ohmic losses used, which can be overridden via dc_ohmic_loss and ac_ohmic_loss. transformer_stages: int Number of transformer stages. 0 for ideal behaviour or 1 for one stage (default is 1).

Auxiliary Files

pan_files : dict[str, Path] Mapping of module names to PAN file paths. ond_files : dict[str, Path] Mapping of inverter names to OND file paths. weather_file : Path | None Path to a weather file (string or Path accepted via property). horizon_file : Path | None Path to a horizon file (string or Path accepted via property).

Other Effects and Settings

mounting_height: Optional[float] = None Mounting height in meters. It refers to the minimum height from ground for fixed-tilt and axis-tube height for single-axis trackers (default is 1.5 m). modules_across: Optional[int] = None Number of modules across in the mounting configuration (default is 1 for both trackers and fixed-tilt). string_length: Optional[int] = None Number of modules in series per string (default is calculated from the module and inverter provided). dc_ohmic_loss: Optional[float] = None DC ohmic loss (per unit) (default depends on inverter type). ac_ohmic_loss: Optional[float] = None AC ohmic loss (per unit) (default depends on inverter type). module_mismatch: Optional[float] = None Module mismatch loss (per unit) (default is 0.005). module_quality_factor: Optional[float] = None Module quality factor (per unit) (default is 0.0, i.e., no quality loss). lid_loss: Optional[float] = None Loss due to light-induced degradation (LID) (per unit) (default is 0.0, i.e., no LID loss). module_iam_model_override: Optional[IAMModelTypeForOverride] = None Override for the module IAM model used in the calculation (default is None, which will use the values from the module's PAN file). constant_heat_coefficient : Optional[float] = None Constant heat transfer coefficient (Uc). convective_heat_coefficient : Optional[float] = None Convective heat transfer coefficient (Uv). soiling_loss : Optional[List[float]] = None Monthly soiling loss (per unit), 12 values in [0,1]. If set with 1 value, it's expanded to 12. albedo: Optional[List[float]] = None Monthly albedo (per unit), 12 values in [0,1]. If set with 1 value, it's expanded to 12. transformer_fixed_loss : Optional[float] = None Transformer fixed loss (per unit). transformer_variable_loss : Optional[float] = None Transformer variable loss (per unit). bifacial_transmission : Optional[float] = None Bifacial transmission gain (per unit). Applicable only if bifacial is True. bifacial_shade_loss : Optional[float] = None Bifacial shade loss (per unit). Applicable only if bifacial is True. bifacial_mismatch_loss : Optional[float] = None Bifacial mismatch loss (per unit). Applicable only if bifacial is True. aux_loss_fixed_factor: Optional[float] = None Simple loss as a fraction of AC output (per unit). aux_loss_power: Optional[float] = None Constant power loss in Watts. aux_loss_apply_at_night: Optional[bool] = None Whether to apply the simple loss factor during night hours (True or False). horizon_elevation_angles : Optional[List[float]] = None List of horizon elevation angles (degrees). horizon_azimuth_angles : Optional[List[float]] = None List of horizon azimuth angles (degrees) with the convention 0 to 359 degrees, clockwise from North (North (0°), East (90°), South (180°), West (270°)). generate_pvsyst_format_timeseries : bool If True, generates PVsyst format timeseries output (default is True). generate_loss_tree_timeseries : bool If True, generates loss tree timeseries output (default is True). enable_spectral_modeling : bool If True, enables spectral modeling in the calculation (default is False).

Methods:

Name	Description
`- horizon`
`- run_energy_calculation`
`- describe`
`- to_file`
`- from_file`
`- make_copy`
`- payload_to_file`

Notes

All setters accept str or Path for paths; stored internally as Path.

albedo `property` `writable` ¶

albedo

Monthly albedo (per unit), 12 values in [0,1]. If set with 1 value, it's expanded to 12.

ond_file_map `property` ¶

ond_file_map

A (shallow) copy of inverter -> OND file mapping.

ond_files `property` `writable` ¶

ond_files

Mapping of inverter names to OND file paths.

pan_file_map `property` ¶

pan_file_map

A (shallow) copy of module -> PAN file mapping.

pan_files `property` `writable` ¶

pan_files

Mapping of module names to PAN file paths.

soiling_loss `property` `writable` ¶

soiling_loss

Monthly soiling loss (per unit), 12 values in [0,1].

__post_init__ ¶

__post_init__()

Post-initialization processing and validation.

add_ond_files ¶

add_ond_files(mapping)

Add OND files without clearing existing mappings (supports method chaining).

Parameters:

Name	Type	Description	Default
`mapping`	`dict[str, str \| Path]`	Mapping 'Name of Inverter' -> file path (string or Path).	required

Returns:

Name	Type	Description
`self`	`PVSystem`

add_pan_files ¶

add_pan_files(mapping)

Add PAN files without clearing existing mappings (supports method chaining).

Parameters:

Name	Type	Description	Default
`mapping`	`dict[str, str \| Path]`	Mapping 'Name of Module' -> file path (string or Path).	required

Returns:

Name	Type	Description
`self`	`PVSystem`

describe ¶

describe(verbose=False)

Print a comprehensive summary of all PV plant configuration properties.

Displays all settings organized by category: metadata, location, capacity, array configuration, mounting, inverter/transformer, losses, and files.

from_file `classmethod` ¶

from_file(file_path)

Load PVSystem configuration from a JSON file and create a PVSystem instance.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path`	Path to the input JSON file containing the PVSystem configuration.	required

Returns:

Type	Description
`PVSystem`	A new PVSystem instance initialized with the configuration loaded from the file.

Notes

The input JSON file should contain all necessary configuration properties for the PVSystem.
The method reads the JSON file, converts it to a dictionary, and then initializes a new PVSystem instance.
If the JSON file is missing required fields or contains invalid data, an error may be raised during initialization.

horizon ¶

horizon(elevation_angles=None, azimuth_angles=None)

Set horizon angles.

Parameters:

Name	Type	Description	Default
`elevation_angles`	`Sequence[float] \| None`	Elevation angles (deg). If None, leaves unchanged.	`None`
`azimuth_angles`	`Sequence[float] \| None`	Azimuth angles (deg). If None, leaves unchanged.	`None`

Returns:

Name	Type	Description
`self`	`PVSystem (enables method-chaining)`

make_copy ¶

make_copy()

Create a deep copy of the PVSystem instance with results cleared.

Creates a new PVSystem instance with all fields copied from the current instance. The results field is explicitly set to None, and the name is prefixed with "Copy of". This ensures a clean state for new calculations and distinguishes the copy.

Returns:

Type	Description
`PVSystem`	A new PVSystem instance with identical configuration, results = None, and name prefixed with "Copy of".

Examples:

>>> original_plant = PVSystem(name="Plant1", dc_capacity_MW=5.0)
>>> original_plant.results = some_calculation_results
>>> copy_plant = original_plant.make_copy()
>>> copy_plant.results is None
True
>>> copy_plant.name
'Copy of Plant1'

payload_to_file ¶

payload_to_file(file_path)

Save the constructed payload (EnergyCalculationInputs JSON) to a file.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path`	Path to the output JSON file where the payload will be saved.	required

Returns:

Type	Description
`None`	The method saves the payload to the specified file and does not return anything.

Notes

This method constructs the payload using the current PVSystem configuration and saves it as JSON.
The payload is what is sent to the SolarFarmer API for energy calculation.
If the payload has already been constructed and stored in self.payload, it will save that instead of reconstructing.

produce_payload ¶

produce_payload()

Construct and return the payload dictionary for the SolarFarmer API based on the current PVSystem configuration.

Returns:

Type	Description
`dict[str, Any]`	A dictionary representing the payload to be sent to the SolarFarmer API for energy calculation.

Notes

This method constructs the payload using the current configuration of the PVSystem instance.
The payload includes all necessary information about the plant design, location, losses, and other parameters required by the API.
If the payload has already been constructed and stored in self.payload, it will return that instead of reconstructing.

run_energy_calculation ¶

run_energy_calculation(project_id=None, print_summary=True, outputs_folder_path=None, save_outputs=True, force_async_call=False, api_version='latest', **kwargs)

Runs the SolarFArmer API calculation for the defined PV plant.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	Identifier for the project, used to group related runs and for billing.	`None`
`print_summary`		If True, it will print out the summary of the energy calculation results.	`True`
`outputs_folder_path`		Path to a folder that will contain all the requested outputs from the energy calculation. If the path does not exist, it will be created. If the path is not provided, an output folder named `sf_outputs_<TIMESTAMP>` will be created in the same directory than `inputs_folder_path` or `energy_calculation_inputs_file_path`.	`None`
`save_outputs`		If True, it will save the results from the API call in the `outputs_folder_path` or in a newly created folder `sf_outputs_<TIMESTAMP>`.	`True`
`api_version`	`str`	API version selector. Accepted values: - None : returns `base_url` as-is - 'latest' : uses the 'latest' version path - 'vX' : where X is a positive integer, e.g., 'v6'	`"latest"`
`force_async_call`	`bool`	If True, forces the use of the asynchronous ModelChain endpoint even when the synchronous endpoint could be used.	`False`
`**kwargs`	`dict`	Additional keyword arguments passed to the underlying request logic (e.g., `api_key`, `time_out`, `async_poll_time`, or other metadata).	`{}`

Returns:

Name	Type	Description
`CalculationResults`	`None`	An instance of CalculationResults with the 2D API results for the PV plant.

to_file ¶

to_file(file_path)

Save the PVSystem configuration to a JSON file.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path`	Path to the output JSON file where the PVSystem configuration will be saved.	required

Returns:

Type	Description
`None`	The method saves the configuration to the specified file and does not return anything.

Notes

The output JSON file will contain all the configuration properties of the PVSystem instance, including metadata, location, plant definition, effects, and auxiliary files.
The results field is not included in the saved configuration, as it is typically generated after running the energy calculation and may contain complex data structures.

EnergyCalculationInputs¶

Bases: SolarFarmerBaseModel

Complete input specification for a SolarFarmer energy calculation.

Compose all sub-models here and serialize with model_dump(by_alias=True) to produce the energyCalculationInputs JSON payload.

Attributes:

Name	Type	Description
`location`	`Location`	Geographic location of the plant
`pv_plant`	`PVPlant`	Electrical topology of the PV plant
`monthly_albedo`	`MonthlyAlbedo`	Twelve monthly albedo values (Jan-Dec), each within [0, 1]
`energy_calculation_options`	`EnergyCalculationOptions`	Model chain configuration options
`horizon_azimuths`	`list[float] or None`	Horizon profile azimuth angles in degrees
`horizon_angles`	`list[float] or None`	Horizon profile elevation angles in degrees
`pan_file_supplements`	`dict[str, PanFileSupplements] or None`	PAN file overrides keyed by module spec ID
`ond_file_supplements`	`dict[str, OndFileSupplements] or None`	OND file overrides keyed by inverter spec ID

PVPlant¶

Bases: SolarFarmerBaseModel

Electrical topology of a photovoltaic plant.

Composes transformers, inverters, layouts, and their associated specifications into the pvPlant section of the API payload.

Attributes:

Name	Type	Description
`transformers`	`list[Transformer]`	Transformers in the plant. At least one is required
`mounting_type_specifications`	`dict[str, MountingTypeSpecification]`	Mounting type specs keyed by ID
`grid_connection_limit`	`float or None`	Maximum power that can be exported from the transformers in MW
`tracker_systems`	`dict[str, TrackerSystem] or None`	Tracker system specs keyed by ID. Required when layouts use trackers
`transformer_specifications`	`dict[str, TransformerSpecification] or None`	Transformer specs keyed by ID
`auxiliary_losses`	`AuxiliaryLosses or None`	Plant-level auxiliary losses

ModelChainResponse¶

Container for ModelChain and ModelChainAsync API results.

This class provides methods to parse and validate raw JSON responses from the SolarFarmer API energy calculation endpoints.

Attributes:

Name	Type	Description
`Name`	`str \| None`	The name or identifier of the project for this calculation. Typically provided by the user via the `project_id` parameter. None if no project identifier was specified.
`AnnualEnergyYieldResults`	`list[dict[str, Any]] \| None`	List of annual energy yield results and loss effects, one entry per simulated year. Each dict contains 'year', 'energyYieldResults', 'annualEffects', and 'monthlyEnergyYieldResults'. None if not returned by the API.
`InputsDerivedFileContents`	`dict[str, Any] \| None`	Parsed JSON object containing derived input data and metadata used during the energy calculation. Includes processed system parameters, site info, etc. None if not returned by the API.
`LossTree`	`dict[str, Any] \| None`	Hierarchical loss tree structure showing the calculation chain and loss categories. None if not requested or returned by the API.
`LossTreeResults`	`str \| None`	Tab-separated values (TSV) text containing timestamped loss tree results. Aggregated energy values (kWh) for the whole site at each calculation timestamp. None if not returned by the API.
`PvSystFormatResultsFile`	`str \| None`	Comma-separated values (CSV) text in PVsyst-compatible format containing timeseries results for the whole site. None if not returned by the API.
`ResultsFile`	`str \| None`	Tab-separated values (TSV) text containing detailed timeseries results. Additional intermediate modeling data useful for debugging and analysis. None if not returned by the API.
`SystemAttributes`	`dict[str, Any] \| None`	System-level attributes and metadata about the PV plant configuration used in the calculation (e.g., total DC capacity, inverter count). None if not returned by the API.
`TotalModuleArea`	`float \| None`	Total PV module area in square meters (m²) for the entire plant. None if not returned by the API.

repr ¶

__repr__()

Developer-friendly string representation for debugging.

Returns:

Type	Description
`str`	A detailed representation showing which fields are populated.

from_dict `classmethod` ¶

from_dict(data, project_id=None)

Build ModelChainResponse from a parsed JSON dictionary.

This method extracts known fields from the API response and applies defensive parsing to avoid crashes from missing or malformed data.

Parameters:

Name	Type	Description	Default
`data`	`dict`	Parsed JSON dictionary containing energy calculation results.	required
`project_id`	`str \| None`	The project ID or name to associate with this response.	`None`

Returns:

Type	Description
`ModelChainResponse`	Populated response container. Missing fields default to None.

Notes

All fields are optional; missing keys result in None values.
The inputsDerivedFileContents field is expected to be a JSON string and is automatically parsed. If parsing fails or the field is missing, it defaults to None with a warning.
Field names match the exact API response keys (camelCase).

Examples:

>>> data = {"annualEnergyYieldResults": [...], "systemAttributes": {...}}
>>> response = ModelChainResponse.from_dict(data, "MyProject")

from_response `classmethod` ¶

from_response(data, project_id=None)

Build ModelChainResponse from a parsed API JSON response.

This method validates the input and delegates to from_dict() for field extraction. It does NOT handle async-specific unwrapping (e.g., extracting 'output' from async responses) - that logic is handled separately in the endpoint layer.

Parameters:

Name	Type	Description	Default
`data`	`dict`	Parsed JSON dictionary returned by the SolarFarmer API. Must be a dict at the top level.	required
`project_id`	`str \| None`	The project ID or name to associate with this response. If None, the Name field will be None.	`None`

Returns:

Type	Description
`ModelChainResponse`	Populated response container with validated fields.

Raises:

Type	Description
`ValueError`	If `data` is not a dictionary (e.g., list or string at top level).

Examples:

>>> data = api_client.post(endpoint="/ModelChain", ...)
>>> response = ModelChainResponse.from_response(data, project_id="MyProject")

CalculationResults¶

Container for ModelChain and ModelChainAsync API results.

Attributes:

Name	Type	Description
`ModelChainResponse`	`ModelChainResponse`	The API ModelChainResponse object
`AnnualData`	`dictionary`	Annual energy yield performance and effects.
`MonthlyData`	`dictionary`	Monthly energy yield performance and effects.
`CalculationAttributes`	`dictionary`	Several system attributes and metadata from the energy calculation.
`LossTreeTimeseries`	`DataFrame or None`	The loss tree timeseries results. Aggregated energy values (kWh) for the whole site in each timestamp using the modeling chain of the SolarFarmer performance model.
`PVsystTimeseries`	`DataFrame or None`	The PVsyst-style timeseries results. For the whole site in each timestamp of the energy calculation.
`DetailedTimeseries`	`DataFrame or None`	The detailed timeseries results. Additional data from the modeling chain of SolarFarmer performance model. Useful for debugging.
`Name`	`str or None`	Name of project. It is populated with the `project_id` property if availabe.

repr ¶

__repr__()

Return a concise string representation of the CalculationResults.

calculation_attributes ¶

calculation_attributes()

Return calculation attributes and derived system data.

Returns:

Type	Description
`dict[str, Any] \| None`	Metadata and derived inputs used during the energy calculation, or None if not available.

describe ¶

describe(project_year=1)

Print project summary and key energy performance metrics.

Parameters:

Name	Type	Description	Default
`project_year`	`int`	The project year to display the key energy performance metrics.	`1`

detailed_timeseries ¶

detailed_timeseries()

Return the detailed timeseries results.

Returns:

Type	Description
`DataFrame \| None`	Secondary timeseries containing additional intermediate calculation steps, useful for diagnostics, or None if not available.

from_folder `classmethod` ¶

from_folder(output_folder_path)

Load CalculationResults from JSON files in a directory.

Reads API energy calculation results from multiple JSON files in the specified output directory.

Parameters:

Name	Type	Description	Default
`output_folder_path`	`str`	The path of the output folder, where the results will be read from.	required

Returns:

Type	Description
`CalculationResults`	Populated results container in ready-to-use formats (e.g, DataFrames and dictionaries).

from_modelchain_response `classmethod` ¶

from_modelchain_response(modelchain_response, outputs_folder_path, save_outputs, print_summary)

Build a CalculationResults instance from a ModelChainResponse.

Parameters:

Name	Type	Description	Default
`modelchain_response`	`ModelChainResponse`	The ModelChainResponse object from the API call.	required
`outputs_folder_path`	`str`	The path of the output folder, where the results will be written.	required
`save_outputs`	`bool`	If True, it will save the results from the API call in the 'outputs_folder_path'.	required
`print_summary`	`bool`	If True, it will print out the summary of the energy calculation results.	required

Returns:

Type	Description
`CalculationResults`	Populated results container in ready-to-use formats.

get_annual_results_table ¶

get_annual_results_table(include_energy_results=True, include_effects=True, project_years=None)

Returns annual energy yield results and/or annual effects as structured data.

Parameters:

Name	Type	Description	Default
`include_energy_results`	`bool`	If True, includes energy yield results in the output. Default is True.	`True`
`include_effects`	`bool`	If True, includes annual effects in the output. Default is True.	`True`
`project_years`	`list[int]`	List of project years to include (1-based indices) or actual calendar years. If None, includes all years. Examples: [1, 3] or [1994, 1996].	`None`

Returns:

Type	Description
`dict[str, list[dict[str, int \| float]]]`	Dictionary with keys 'energy_results' and/or 'effects'. Each value is a list of dictionaries, one per year.

Examples:

>>> data = results.get_annual_results_table(project_years=[1, 2, 3])
>>> import pandas as pd
>>> energy_df = pd.DataFrame(data['energy_results'])
>>> effects_df = pd.DataFrame(data['effects'])
>>> # Export to Excel
>>> with pd.ExcelWriter('results.xlsx') as writer:
...     energy_df.to_excel(writer, sheet_name='Energy')
...     effects_df.to_excel(writer, sheet_name='Effects')

get_info ¶

get_info()

Returns metadata about what data is available in this results instance.

Returns:

Type Description

dict[str, bool | str]

Dictionary with keys: - 'name': Project name - 'has_annual_data': Whether annual data is available - 'has_monthly_data': Whether monthly data is available - 'has_calculation_attributes': Whether calculation attributes are available - 'has_loss_tree_timeseries': Whether loss tree timeseries is available - 'has_pvsyst_timeseries': Whether PVsyst timeseries is available - 'has_detailed_timeseries': Whether detailed timeseries is available

Examples:

>>> info = results.get_info()
>>> if info['has_monthly_data']:
...     monthly_data = results.get_monthly_results_table()

get_monthly_results_table ¶

get_monthly_results_table(include_energy_results=True, include_effects=True, project_years=None)

Returns monthly energy yield results and/or monthly effects as structured data.

Parameters:

Name	Type	Description	Default
`include_energy_results`	`bool`	If True, includes energy yield results in the output. Default is True.	`True`
`include_effects`	`bool`	If True, includes monthly effects in the output. Default is True.	`True`
`project_years`	`list[int]`	List of project years to include (1-based indices) or actual calendar years. If None, includes all years. Examples: [1, 3] or [1994, 1996].	`None`

Returns:

Type	Description
`dict[str, list[dict[str, int \| float \| str]]]`	Dictionary with keys 'energy_results' and/or 'effects'. Each value is a flat list of dictionaries (one per month across all years). Total rows = num_years * 12.

Examples:

>>> data = results.get_monthly_results_table(project_years=[1, 2])
>>> import pandas as pd
>>> monthly_df = pd.DataFrame(data['energy_results'])
>>> # Filter summer months
>>> summer = monthly_df[monthly_df['month'].isin([6, 7, 8])]
>>> # Group by month across years
>>> monthly_df.groupby('month')['energy_yield'].mean()

get_performance ¶

get_performance(project_year=1)

Returns key energy performance metrics for the specified project year.

Parameters:

Name	Type	Description	Default
`project_year`	`int`	The project year (1-based index). Default is 1.	`1`

Returns:

Type Description

dict[str, int | float]

Dictionary with keys: - 'project_year': The project year (1-based) - 'calendar_year': The calendar year - 'average_temperature': Average annual temperature (°C) - 'horizontal_irradiation': Global horizontal irradiation (kWh/m²) - 'irradiation_on_tilted_plane': Irradiation on tilted plane (kWh/m²) - 'effective_irradiation': Effective irradiation on tilted plane (kWh/m²) - 'energy_yield': Specific energy yield (kWh/kWp) - 'net_energy': Net energy production (MWh/year) - 'performance_ratio': Performance ratio (0-1)

Examples:

>>> perf = results.get_performance(project_year=1)
>>> print(f"Net energy: {perf['net_energy']:.2f} MWh/year")
>>> # Multi-year comparison
>>> import pandas as pd
>>> df = pd.DataFrame([results.get_performance(y) for y in range(1, 11)])
>>> df.plot(x='calendar_year', y='energy_yield')

info ¶

info()

Print the available data attributes in this results instance.

loss_tree_timeseries ¶

loss_tree_timeseries()

Return the loss tree timeseries results.

Returns:

Type	Description
`DataFrame \| None`	Main native SolarFarmer results timeseries, or None if not available.

performance ¶

performance(project_year=1)

Print key energy performance metrics for the specified project year.

Parameters:

Name	Type	Description	Default
`project_year`	`int`	The project year to display the key energy performance metrics (starts in 1).	`1`

print_annual_results ¶

print_annual_results(show_energy_results=True, show_effects=True, project_years=None, years_per_table=5)

Displays the annual energy yield results in a tabular format, one column for each year of results. Also displays the annual effects in a tabular format, one column for each year of results.

Parameters:

Name	Type	Description	Default
`show_energy_results`	`bool`	If `True`, it will display the annual energy yield results.	`True`
`show_effects`	`bool`	If `True`, it will display the annual effects.	`True`
`project_years`	`list[int] \| None`	List of project years to display. If None, it will display all the years available in the results. The project years start with index 1 (e.g., project_years=[1, 3] will display the results for the first and third year of the project). Alternatively you can also specify the actual year (e.g., 1994, 1995, etc.) if you prefer (e.g., project_years=[1994, 1996] will display the results for the years 1994 and 1996).	`None`
`years_per_table`	`int`	Number of years to display per table (one column per year). If there are more years in the results than the specified number of years per table, it will display multiple tables until all the years are displayed.	`5`

print_monthly_results ¶

print_monthly_results(show_energy_results=True, show_effects=True, project_years=None)

Displays the monthly energy yield results in a tabular format, one column for each month of results. Also displays the monthly effects in a tabular format, one column for each month of results.

Parameters:

Name	Type	Description	Default
`show_energy_results`	`bool`	If `True`, it will display the annual energy yield results.	`True`
`show_effects`	`bool`	If `True`, it will display the annual effects.	`True`
`project_years`	`list[int] \| None`	List of project years to display. If None, it will display all the years available in the results. The project years start with index 1 (e.g., project_years=[1, 3] will display the results for the first and third year of the project). Alternatively you can also specify the actual year (e.g., 1994, 1995, etc.) if you prefer (e.g., project_years=[1994, 1996] will display the results for the years 1994 and 1996).	`None`

pvsyst_timeseries ¶

pvsyst_timeseries()

Return the PVsyst-style timeseries results.

Returns:

Type	Description
`DataFrame \| None`	Timeseries formatted similarly to PVsyst, or None if not available.

to_folder ¶

to_folder(output_folder_path)

Write energy calculation results to files in a directory.

Writes the energy calculation results to multiple files (.json, .csv, *.tsv) in the specified output directory.

Parameters:

Name	Type	Description	Default
`output_folder_path`	`str`	The path of the output folder, where the results will be written.	required

Plant Configuration Classes¶

Module and Equipment Specifications¶

MountingTypeSpecification¶

View in SolarFarmer API Reference

TrackerSystem¶

View in SolarFarmer API Reference

PanFileSupplements¶

View in SolarFarmer API Reference

OndFileSupplements¶

View in SolarFarmer API Reference

Advanced System Configuration¶

Transformer¶

View in SolarFarmer API Reference

TransformerSpecification¶

View in SolarFarmer API Reference

TransformerLossModelTypes¶

View in SolarFarmer API Reference

AuxiliaryLosses¶

View in SolarFarmer API Reference

Additional Configuration Classes¶

MonthlyAlbedo¶

View in SolarFarmer API Reference

Version Information¶

Dynamic version information from package metadata and git.

This module provides version information with the following fallback chain: - version: Package metadata → pyproject.toml → "unknown" - released: Most recent git tag date → "unreleased" (development)

Configuration¶

The SDK can be configured using environment variables:

SF_API_KEY: Your SolarFarmer API authentication key (imported from environment)
SF_API_URL: Override the default SolarFarmer API URL

You can also pass these values directly as keyword arguments to the endpoint functions.

API Reference¶

Overview¶

Core Functions & Classes¶

Configuration & Design¶

Advanced Options¶

Endpoint Functions¶

run_energy_calculation()¶

about()¶

service()¶

terminate_calculation()¶

Main Classes¶

PVSystem¶

albedo property writable ¶

ond_file_map property ¶

ond_files property writable ¶

pan_file_map property ¶

pan_files property writable ¶

soiling_loss property writable ¶

__post_init__ ¶

add_ond_files ¶

add_pan_files ¶

describe ¶

from_file classmethod ¶

horizon ¶

make_copy ¶

payload_to_file ¶

produce_payload ¶

run_energy_calculation ¶

to_file ¶

EnergyCalculationInputs¶

PVPlant¶

ModelChainResponse¶

__repr__ ¶

from_dict classmethod ¶

from_response classmethod ¶

CalculationResults¶

__repr__ ¶

calculation_attributes ¶

describe ¶

detailed_timeseries ¶

from_folder classmethod ¶

from_modelchain_response classmethod ¶

get_annual_results_table ¶

get_info ¶

get_monthly_results_table ¶

get_performance ¶

info ¶

loss_tree_timeseries ¶

performance ¶

print_annual_results ¶

print_monthly_results ¶

pvsyst_timeseries ¶

to_folder ¶

Plant Configuration Classes¶

Location¶

Layout¶

Inverter¶

EnergyCalculationOptions¶

Module and Equipment Specifications¶

MountingTypeSpecification¶

TrackerSystem¶

PanFileSupplements¶

OndFileSupplements¶

Advanced System Configuration¶

Transformer¶

TransformerSpecification¶

TransformerLossModelTypes¶

AuxiliaryLosses¶

Additional Configuration Classes¶

MonthlyAlbedo¶

Version Information¶

Configuration¶

`run_energy_calculation()`¶

`about()`¶

`service()`¶

`terminate_calculation()`¶

albedo `property` `writable` ¶

ond_file_map `property` ¶

ond_files `property` `writable` ¶

pan_file_map `property` ¶

pan_files `property` `writable` ¶

soiling_loss `property` `writable` ¶

from_file `classmethod` ¶

repr ¶

from_dict `classmethod` ¶

from_response `classmethod` ¶

repr ¶

from_folder `classmethod` ¶

from_modelchain_response `classmethod` ¶