Skip to main content

SolarFarmer Python SDK

PyPI version Python versions License CI Documentation

The official Python SDK for SolarFarmer, a bankable solar PV design and energy yield assessment software from DNV. This SDK provides a typed Python interface that simplifies calling SolarFarmer APIs: build payloads, run 2D and 3D energy calculations, and process results programmatically.

Key Features

  • Data models that mirror the API schema. Pydantic classes with field validation catch payload errors locally before the API call. Field descriptions and type hints improve discoverability.
  • Two plant-building paths. Full control via EnergyCalculationInputs and component classes, or quick screening via PVSystem from high-level specs (DC and AC capacities, tilt, GCR)
  • Structured results. CalculationResults gives direct access to annual/monthly metrics, loss trees, and time series without parsing raw JSON.
  • Automatic endpoint handling. One function call runs 2D or 3D calculations. The SDK selects the right endpoint, polls async jobs, and supports cancellation via terminate_calculation().

Requirements

  • Python >= 3.11 (tested on 3.11, 3.12, 3.13)
  • A SolarFarmer API key (commercial licence required; see API Key)

For compatibility with Python 3.10, use version 0.7.0 or prior.

Installation

Install from PyPI:

pip install dnv-solarfarmer

The package is imported as solarfarmer regardless of the distribution name:

import solarfarmer as sf

Install with optional extras:

pip install "dnv-solarfarmer[notebooks]"  # JupyterLab and notebook support
pip install "dnv-solarfarmer[all]"        # full installation including pandas and matplotlib

For development and documentation extras (managed as dependency groups, requires uv):

uv sync --group dev    # linting and testing tools (for contributors)
uv sync --group docs   # documentation build tools

Install from source:

git clone https://github.com/dnv-opensource/solarfarmer-python-sdk
cd solarfarmer-python-sdk
pip install -e .

API Key

A SolarFarmer API key is required to run energy calculations. Obtain one from the SolarFarmer portal. For setup instructions, see the API key documentation.

Set your key as an environment variable (recommended):

export SF_API_KEY="your_api_key_here"

Alternatively, pass it directly as the api_key parameter to any function that calls the API.

Configuration

Environment Variable Default Description
SF_API_KEY (none; required for calculations) API authentication token
SF_API_URL https://solarfarmer.dnv.com/latest/api Override the base API URL for custom deployments

Optional Dependencies

The core SDK (pydantic, requests, tabulate) does not depend on pandas. Install the all extra for DataFrame-based features:

pip install "dnv-solarfarmer[all]"

This unlocks sf.from_dataframe() and sf.from_pvlib() for writing weather files from DataFrames, and enables CalculationResults to parse timeseries outputs into DataFrames. Without pandas, those functions raise ImportError or return None. All other SDK features work without it.

Getting Started

The SDK supports three workflows for different use cases:

Workflow Best for Entry point
1. Load existing files Users with pre-built API payloads from the SolarFarmer desktop app or a previous export sf.run_energy_calculation(inputs_folder_path=...)
2. PVSystem builder Quick screening from high-level specs (capacity, tilt, equipment files). The design is approximate: string sizing and inverter count are inferred, so DC/AC capacity may not match the target exactly. plant = sf.PVSystem(...) then plant.run_energy_calculation()
3. Custom integration Developers mapping internal databases or proprietary formats to the SolarFarmer API params = sf.EnergyCalculationInputs(...) then sf.run_energy_calculation(plant_builder=params)

See the Getting Started guide for full per-workflow walkthroughs, and the example notebooks for runnable end-to-end examples.

For broader use case demonstrations — including integrations with Solcast and Solar Resource Compass APIs — see the dnv-opensource/solarfarmer-sdk-examples repository.

Documentation

Full documentation (API reference, workflow guides, notebook tutorials):

https://dnv-opensource.github.io/solarfarmer-python-sdk/

To build and serve the documentation locally:

uv sync --group docs
zensical serve -o                          # build, serve, and open in browser (port 8000)
zensical serve -o -a localhost:8080        # use a different port

zensical serve builds the docs and starts a local server in one step. The -o flag opens the page automatically in your default browser.

Contributing

Fork the repository, create a branch, and submit a pull request to main. To set up a development environment:

git clone https://github.com/dnv-opensource/solarfarmer-python-sdk
cd solarfarmer-python-sdk
pip install -e .
uv sync --group dev
  • Linting and formatting: ruff check solarfarmer/ tests/ and ruff format solarfarmer/ tests/
  • Tests: pytest tests/ -v

All contributions should include tests for new functionality. For feature proposals or questions, contact solarfarmer@dnv.com. See CONTRIBUTING.md for full guidelines.

Getting Technical Support

License

Apache License, Version 2.0 — see LICENSE.

Changelog

See CHANGELOG.md for a full list of changes per release.

Metadata

Release files for dnv-solarfarmer 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dnv-solarfarmer 0.8.0
File Size Uploaded Provenance Actions
dnv_solarfarmer-0.8.0.tar.gz 191.0 kB With provenance Details for dnv_solarfarmer-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dnv-solarfarmer 0.8.0
File Interpreter ABI Platform Actions
dnv_solarfarmer-0.8.0-py3-none-any.whl Python 3 none any Details for dnv_solarfarmer-0.8.0-py3-none-any.whl

Total release size: 325.8 kB

Release files / dnv_solarfarmer-0.8.0.tar.gz

Download URL dnv_solarfarmer-0.8.0.tar.gz
Size 191.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2aa957a5f7245b2e32693071734bb3a7d85b20a14e30e372b9fdadf1dd85a85a
BLAKE2b-256 checksum
How to use checksums
3ae06d252808940b3c0cf39a235af6485fad832e351945514aa728874951bcba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / dnv_solarfarmer-0.8.0-py3-none-any.whl

Download URL dnv_solarfarmer-0.8.0-py3-none-any.whl
Size 134.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7d625078b6725896b31916321d5dd8e1c24059e979a32493b8f95a1cc8024c2
BLAKE2b-256 checksum
How to use checksums
b6eaa2cfe766434443b2a72e92bd6618e8ed05ef10c9b339be5bce0d321567c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for dnv-solarfarmer 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dnv_solarfarmer-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page