{"id":50666079,"url":"https://github.com/dnv-opensource/solarfarmer-python-sdk","last_synced_at":"2026-06-08T06:30:45.498Z","repository":{"id":347167720,"uuid":"1166775379","full_name":"dnv-opensource/solarfarmer-python-sdk","owner":"dnv-opensource","description":"A Python SDK for the SolarFarmer web API","archived":false,"fork":false,"pushed_at":"2026-05-27T07:00:39.000Z","size":2408,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T09:04:22.092Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnv-opensource.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-25T15:40:58.000Z","updated_at":"2026-05-27T07:05:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"934e4cef-bee6-4ab0-bed5-4c1f5eae4abc","html_url":"https://github.com/dnv-opensource/solarfarmer-python-sdk","commit_stats":null,"previous_names":["dnv-opensource/solarfarmer-python-sdk"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/dnv-opensource/solarfarmer-python-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnv-opensource%2Fsolarfarmer-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnv-opensource%2Fsolarfarmer-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnv-opensource%2Fsolarfarmer-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnv-opensource%2Fsolarfarmer-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnv-opensource","download_url":"https://codeload.github.com/dnv-opensource/solarfarmer-python-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnv-opensource%2Fsolarfarmer-python-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34051768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T06:30:39.397Z","updated_at":"2026-06-08T06:30:45.493Z","avatar_url":"https://github.com/dnv-opensource.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SolarFarmer Python SDK\n\n[![PyPI version](https://img.shields.io/pypi/v/dnv-solarfarmer)](https://pypi.org/project/dnv-solarfarmer/)\n[![Python versions](https://img.shields.io/pypi/pyversions/dnv-solarfarmer)](https://pypi.org/project/dnv-solarfarmer/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![CI](https://github.com/dnv-opensource/solarfarmer-python-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/dnv-opensource/solarfarmer-python-sdk/actions/workflows/test.yml)\n[![Documentation](https://img.shields.io/badge/docs-online-teal)](https://dnv-opensource.github.io/solarfarmer-python-sdk/)\n\nThe official Python SDK for [SolarFarmer](https://www.dnv.com/software/services/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.\n\n## Key Features\n\n- **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.\n- **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)\n- **Structured results.** `CalculationResults` gives direct access to annual/monthly metrics, loss trees, and time series without parsing raw JSON.\n- **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()`.\n\n## Requirements\n\n- Python \u003e= 3.10 (tested on 3.10, 3.11, 3.12, 3.13)\n- A SolarFarmer API key (commercial licence required; see [API Key](#api-key))\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install dnv-solarfarmer\n```\n\nThe package is imported as `solarfarmer` regardless of the distribution name:\n\n```python\nimport solarfarmer as sf\n```\n\nInstall with optional extras:\n\n```bash\npip install \"dnv-solarfarmer[notebooks]\"  # JupyterLab and notebook support\npip install \"dnv-solarfarmer[all]\"        # full installation including pandas and matplotlib\n```\n\nFor development and documentation extras (managed as dependency groups, requires `uv`):\n\n```bash\nuv sync --group dev    # linting and testing tools (for contributors)\nuv sync --group docs   # documentation build tools\n```\n\nInstall from source:\n\n```bash\ngit clone https://github.com/dnv-opensource/solarfarmer-python-sdk\ncd solarfarmer-python-sdk\npip install -e .\n```\n\n## API Key\n\nA SolarFarmer API key is required to run energy calculations. Obtain one from the [SolarFarmer portal](https://solarfarmer.dnv.com/). For setup instructions, see the [API key documentation](https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/WebApi/Introduction/ApiKey.html).\n\nSet your key as an environment variable (recommended):\n\n```bash\nexport SF_API_KEY=\"your_api_key_here\"\n```\n\nAlternatively, pass it directly as the `api_key` parameter to any function that calls the API.\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---|---|---|\n| `SF_API_KEY` | *(none; required for calculations)* | API authentication token |\n| `SF_API_URL` | `https://solarfarmer.dnv.com/latest/api` | Override the base API URL for custom deployments |\n\n## Optional Dependencies\n\nThe core SDK (`pydantic`, `requests`, `tabulate`) does not depend on `pandas`.\nInstall the `all` extra for DataFrame-based features:\n\n```bash\npip install \"dnv-solarfarmer[all]\"\n```\n\nThis 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.\n\n## Getting Started\n\nThe SDK supports three workflows for different use cases:\n\n| Workflow | Best for | Entry point |\n|---|---|---|\n| 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=...)` |\n| 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()` |\n| 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)` |\n\nSee the [Getting Started guide](https://dnv-opensource.github.io/solarfarmer-python-sdk/getting-started/) for full per-workflow walkthroughs, and the [example notebooks](https://dnv-opensource.github.io/solarfarmer-python-sdk/notebooks/Example_EnergyCalculations/) for runnable end-to-end examples.\n\n## Documentation\n\nFull documentation (API reference, workflow guides, notebook tutorials):\n\n**https://dnv-opensource.github.io/solarfarmer-python-sdk/**\n\nTo build and serve the documentation locally:\n\n```bash\nuv sync --group docs\nzensical serve -o                          # build, serve, and open in browser (port 8000)\nzensical serve -o -a localhost:8080        # use a different port\n```\n\n`zensical serve` builds the docs and starts a local server in one step. The `-o` flag opens the page automatically in your default browser.\n\n## Contributing\n\nFork the repository, create a branch, and submit a pull request to `main`. To set up a development environment:\n\n```bash\ngit clone https://github.com/dnv-opensource/solarfarmer-python-sdk\ncd solarfarmer-python-sdk\npip install -e .\nuv sync --group dev\n```\n\n- **Linting and formatting:** `ruff check solarfarmer/ tests/` and `ruff format solarfarmer/ tests/`\n- **Tests:** `pytest tests/ -v`\n\nAll contributions should include tests for new functionality. For feature proposals or questions, contact [solarfarmer@dnv.com](mailto:solarfarmer@dnv.com). See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.\n\n## Getting Technical Support\n\n- **SDK documentation:** https://dnv-opensource.github.io/solarfarmer-python-sdk/\n- **SolarFarmer API documentation:** https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/WebApi/Introduction/introduction.html\n- **Issue tracker:** https://github.com/dnv-opensource/solarfarmer-python-sdk/issues\n- **Email:** [solarfarmer@dnv.com](mailto:solarfarmer@dnv.com)\n\n## License\n\nApache License, Version 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnv-opensource%2Fsolarfarmer-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnv-opensource%2Fsolarfarmer-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnv-opensource%2Fsolarfarmer-python-sdk/lists"}