From 577b18da147dc99778c2bf367ceb5c14e8d21b11 Mon Sep 17 00:00:00 2001 From: Ian Tse Date: Tue, 24 Mar 2026 10:18:45 -0700 Subject: [PATCH] Better document PVSystem's use of approximations --- docs/api.md | 2 +- docs/getting-started/index.md | 2 ++ docs/getting-started/workflow-2-pvplant-builder.md | 3 +++ docs/notebooks/Example_PVSystem.ipynb | 8 ++++++++ solarfarmer/models/pvsystem/pvsystem.py | 6 ++++++ 5 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index 46d8ea8..6c26e39 100644 --- a/docs/api.md +++ b/docs/api.md @@ -72,7 +72,7 @@ These are the primary functions for interacting with the SolarFarmer API. The core classes handle the complete workflow from plant design to results analysis: -- [**PVSystem**](#pvsystem): Main class for defining and configuring PV plant designs with all technical specifications +- [**PVSystem**](#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**](#energycalculationinputs): Root Pydantic model composing all inputs for a calculation run - [**PVPlant**](#pvplant): Pydantic model describing the PV plant structure (transformers, mounting specs, etc.) - [**ModelChainResponse**](#modelchainresponse): Container for raw API response data from energy calculations diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index aa51fb0..9bea46d 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -54,6 +54,8 @@ The SolarFarmer SDK supports three distinct user workflows. Choose the one that Specify your plant: location (lat/lon), DC and AC capacities, inverter type, mounting configuration. `PVSystem` handles the payload construction and you run the calculation. +Results from `PVSystem` are approximations based on simplified layout assumptions — see [FAQ](../faq.md) for details. + --- ### [Workflow 3: Advanced Integration and Custom Data Models](workflow-3-plantbuilder-advanced.md) diff --git a/docs/getting-started/workflow-2-pvplant-builder.md b/docs/getting-started/workflow-2-pvplant-builder.md index 9087cd4..8da6f9f 100644 --- a/docs/getting-started/workflow-2-pvplant-builder.md +++ b/docs/getting-started/workflow-2-pvplant-builder.md @@ -13,6 +13,9 @@ description: Create plant configurations and automatically build API payloads ## Overview +!!! info "Approximated Design" + `PVSystem` constructs a plant layout from high-level inputs (location, capacity, equipment files) using simplified assumptions — including uniform mid-row shading for all strings and inferred string sizing. This is well-suited for early-stage yield screening and scenario comparison. For full design fidelity, use [Workflow 1](workflow-1-existing-api-files.md) with a SolarFarmer Desktop–exported payload or [Workflow 3](workflow-3-plantbuilder-advanced.md) for direct data model mapping. + This workflow involves four steps: 1. **Design** your plant using the `PVSystem` class diff --git a/docs/notebooks/Example_PVSystem.ipynb b/docs/notebooks/Example_PVSystem.ipynb index 6d5aab0..183a87d 100644 --- a/docs/notebooks/Example_PVSystem.ipynb +++ b/docs/notebooks/Example_PVSystem.ipynb @@ -17,6 +17,14 @@ "- [API output results](https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/WebApi/Endpoints/ModelChainEndpoint.html#outputs)" ] }, + { + "cell_type": "markdown", + "id": "f93f9dec", + "metadata": {}, + "source": [ + "> **Note:** `PVSystem` generates an approximated plant design by inferring layout geometry, string sizing, and losses from high-level inputs. Results are intended for early-stage yield screening and comparative analysis. For full design fidelity, export a detailed payload from SolarFarmer Desktop or use Workflow 3." + ] + }, { "cell_type": "markdown", "id": "89464306", diff --git a/solarfarmer/models/pvsystem/pvsystem.py b/solarfarmer/models/pvsystem/pvsystem.py index dd2a29d..aba179d 100644 --- a/solarfarmer/models/pvsystem/pvsystem.py +++ b/solarfarmer/models/pvsystem/pvsystem.py @@ -74,6 +74,12 @@ class PVSystem: 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