diff --git a/docs/getting-started/end-to-end-examples.md b/docs/getting-started/end-to-end-examples.md index 0bfec19..1c1408b 100644 --- a/docs/getting-started/end-to-end-examples.md +++ b/docs/getting-started/end-to-end-examples.md @@ -21,7 +21,7 @@ These examples provide detailed explorations of specific API features and workfl ## Using the About and Service Endpoints -**Notebook:** [Example_About_Service_endpoints.ipynb](../notebooks/Example_About_Service_endpoints.ipynb){ target="_blank" .external } +**Notebook:** [Example_About_Service_endpoints.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_About_Service_endpoints.ipynb){ target="_blank" .external } **Topics Covered:** @@ -34,7 +34,7 @@ These examples provide detailed explorations of specific API features and workfl ## Running 2D and 3D Calculations -**Notebook:** [Example_EnergyCalculations.ipynb](../notebooks/Example_EnergyCalculations.ipynb){ target="_blank" .external } +**Notebook:** [Example_EnergyCalculations.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_EnergyCalculations.ipynb){ target="_blank" .external } **Topics Covered:** @@ -49,7 +49,7 @@ These examples provide detailed explorations of specific API features and workfl ## Creating Plants with PVSystem -**Notebook:** [Example_PVSystem.ipynb](../notebooks/Example_PVSystem.ipynb){ target="_blank" .external } +**Notebook:** [Example_PVSystem.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_PVSystem.ipynb){ target="_blank" .external } **Topics Covered:** @@ -64,7 +64,7 @@ These examples provide detailed explorations of specific API features and workfl ## Creating Plants with EnergyCalculationInputs -**Notebook:** [Example_Compose_Plant.ipynb](../notebooks/Example_Compose_Plant.ipynb){ target="_blank" .external } +**Notebook:** [Example_Compose_Plant.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_Compose_Plant.ipynb){ target="_blank" .external } **Topics Covered:** @@ -79,7 +79,7 @@ These examples provide detailed explorations of specific API features and workfl ## Terminating Asynchronous Calculations -**Notebook:** [Example_TerminateAsync_endpoint.ipynb](../notebooks/Example_TerminateAsync_endpoint.ipynb){ target="_blank" .external } +**Notebook:** [Example_TerminateAsync_endpoint.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_TerminateAsync_endpoint.ipynb){ target="_blank" .external } **Topics Covered:** diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 9bea46d..1930904 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -19,9 +19,9 @@ The SolarFarmer SDK supports three distinct user workflows. Choose the one that ### [Workflow 1: Load and Execute Existing API Files](workflow-1-existing-api-files.md) -**For:** Solar data analysts and engineers with existing SolarFarmer API JSON files. +**For:** Solar data analysts and engineers with existing SolarFarmer API JSON files -**Goal:** Run energy calculations using available pre-configured payloads. +**Goal:** Run energy calculations using available pre-configured payloads **Key Classes and Functions:** @@ -39,9 +39,9 @@ The SolarFarmer SDK supports three distinct user workflows. Choose the one that ### [Workflow 2: Design Plants with PVSystem](workflow-2-pvplant-builder.md) -**For:** Solar engineers and designers creating new plant configurations. +**For:** Solar engineers and designers creating new plant configurations -**Goal:** Define high-level plant specifications and automatically construct API payloads. +**Goal:** Define high-level plant specifications and automatically construct API payloads **Key Classes:** @@ -60,16 +60,16 @@ Results from `PVSystem` are approximations based on simplified layout assumption ### [Workflow 3: Advanced Integration and Custom Data Models](workflow-3-plantbuilder-advanced.md) -**For:** Software developers integrating SolarFarmer into custom applications. +**For:** Software developers integrating SolarFarmer into custom applications -**Goal:** Manually build and customize API payloads for complex workflows. +**Goal:** Manually build and customize API payloads for complex workflows **Key Classes:** - `EnergyCalculationInputs` - Compose and serialize the complete API payload - `PVPlant` - Describe the PV plant structure - Component classes (`Inverter`, `Layout`, `Transformer`, etc.) -- Custom data model mapping and workflow orchestration +- Data model mapping and workflow orchestration **Prerequisites:** Familiarity with SolarFarmer's API structure and data model. diff --git a/docs/getting-started/quick-start-examples.md b/docs/getting-started/quick-start-examples.md index ffa82b2..28ef4bb 100644 --- a/docs/getting-started/quick-start-examples.md +++ b/docs/getting-started/quick-start-examples.md @@ -5,7 +5,7 @@ description: Real-world examples showing how classes interact in complete workfl # Quick Start Examples -Below are complete, runnable examples demonstrating real-world use cases. Each example shows how the core classes work together. +Below are real-world example patterns showing how classes interact in complete workflows. Each serves as a template for your own implementation. Adapt these examples with your data files and API credentials to get started. ## Quick Reference diff --git a/docs/getting-started/workflow-3-plantbuilder-advanced.md b/docs/getting-started/workflow-3-plantbuilder-advanced.md index 1738b1e..5033169 100644 --- a/docs/getting-started/workflow-3-plantbuilder-advanced.md +++ b/docs/getting-started/workflow-3-plantbuilder-advanced.md @@ -1,13 +1,13 @@ --- title: Workflow 3 - Advanced Integration with EnergyCalculationInputs -description: Manually construct API payloads for custom workflows and data model integration +description: Manually construct API payloads for specific workflows and data model integration --- -# Workflow 3: Advanced Integration and Custom Data Models +# Workflow 3: Advanced Integration -**Best for:** Software developers, system integrators, and advanced users with custom workflows. +**Best for:** Software developers, system integrators, and advanced users with specific workflows. -**Scenario:** You're building a software system that needs to integrate SolarFarmer calculations. You want full control over payload construction, custom data model mapping, or complex multi-step workflows. +**Scenario:** You're building a software system that needs to integrate SolarFarmer calculations. You want full control over payload construction, data model mapping, or complex multi-step workflows. --- @@ -17,7 +17,7 @@ This workflow gives you complete control over API object construction: 1. **Understand** SolarFarmer's API data model 2. **Manually construct** API objects using `EnergyCalculationInputs`, `PVPlant`, and component classes -3. **Map** your custom data models to SolarFarmer objects +3. **Map** your data models to SolarFarmer objects 4. **Integrate** calculations into your larger workflow
@@ -25,7 +25,7 @@ This workflow gives you complete control over API object construction: ```mermaid graph TB A["🗄️ Your Data Model
(database, file, API, etc.)"] - B["Custom Mapper/Builder"] + B["Mapper/Builder"] C["EnergyCalculationInputs + PVPlant
+ Component Classes
(Inverter, Layout, Location, etc.)"] D["SolarFarmer API"] E["CalculationResults"] @@ -92,13 +92,13 @@ from solarfarmer.models import ( ## Step 1: Map Your Data Model -Create a mapping layer between your custom objects and SolarFarmer objects: +Create a mapping layer between your objects and SolarFarmer objects: ```python from dataclasses import dataclass -from typing import List +from solarfarmer import Location -# Your custom data model +# Your data model @dataclass class SolarProject: name: str @@ -110,13 +110,12 @@ class SolarProject: annual_irradiance: float class ProjectMapper: - """Maps your custom project to SolarFarmer SDK objects""" + """Maps your project to SolarFarmer SDK objects""" def __init__(self, project: SolarProject): self.project = project - def to_location(self) -> "Location": - from solarfarmer import Location + def to_location(self) -> Location: return Location( latitude=self.project.latitude, longitude=self.project.longitude, @@ -146,7 +145,7 @@ from solarfarmer import ( DiffuseModel, MonthlyAlbedo, ) -def build_custom_payload(project_mapper: ProjectMapper) -> str: +def build_my_payload(project_mapper: ProjectMapper) -> str: """Manually construct SolarFarmer API payload as a JSON string""" # 1. Build location @@ -175,7 +174,7 @@ def build_custom_payload(project_mapper: ProjectMapper) -> str: return inputs.model_dump_json(by_alias=True, exclude_none=True) def _build_pv_plant(mapper: ProjectMapper) -> PVPlant: - """Construct the pvPlant section with custom logic""" + """Construct the PVPlant section with your logic""" # Create layouts (DC combiner boxes) layouts = [ @@ -230,18 +229,18 @@ def _build_pv_plant(mapper: ProjectMapper) -> PVPlant: ```python import solarfarmer as sf -# Create your custom payload (returns a JSON string) +# Create your customized payload (returns a JSON string) mapper = ProjectMapper(your_project) -payload_json = build_custom_payload(mapper) +payload_json = build_my_payload(mapper) # Option 1: Save to file and run via Workflow 1 -with open('custom_payload.json', 'w') as f: +with open('my_payload.json', 'w') as f: f.write(payload_json) # Option 2: Pass the JSON string directly to run_energy_calculation() results = sf.run_energy_calculation( plant_builder=payload_json, - project_id="custom_project", + project_id="my_project", api_key=api_key, ) ``` @@ -294,14 +293,15 @@ payload_json = inputs.model_dump_json(by_alias=True, exclude_none=True) ### Batch Processing Multiple Projects ```python -def batch_calculate(projects: List[dict], api_key: str): - """Process multiple custom projects efficiently""" +def batch_calculate(projects: list[dict], api_key: str): + """Process multiple projects efficiently""" results = [] for project_data in projects: - mapper = ProjectMapper(project_data) - payload_json = build_custom_payload(mapper) + project = SolarProject(**project_data) + mapper = ProjectMapper(project) + payload_json = build_my_payload(mapper) # Save payload (optional) payload_file = f"payloads/{project_data['id']}_payload.json" @@ -326,14 +326,14 @@ def batch_calculate(projects: List[dict], api_key: str): return results ``` -### Custom Workflow Orchestration +### Workflow Orchestration !!! info For production workflows involving multiple API calls, consider using asynchronous functions (async/await) or concurrent programming patterns to improve performance. The example below is synchronous and illustrative; your implementation should handle concurrent requests and network timeouts appropriately. ```python class SolarDesignWorkflow: - """Custom workflow orchestrating multiple steps""" + """Multi-step workflow orchestration""" def __init__(self, api_key: str): self.api_key = api_key @@ -363,7 +363,6 @@ class SolarDesignWorkflow: return results def _build_inputs(self, config: dict) -> EnergyCalculationInputs: - # Your custom inputs building pass def _submit(self, inputs: EnergyCalculationInputs, project_id: str): diff --git a/docs/index.md b/docs/index.md index 8eeeca9..5e5c01f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,44 +8,43 @@ A Python SDK that wraps the [DNV SolarFarmer API](https://mysoftware.dnv.com/dow [New to SolarFarmer? Discover it here!](https://www.dnv.com/software/services/solarfarmer/){ .md-button .md-button-primary target="_blank" .external } -Embed SolarFarmer's API into your workflow, typical use-cases of the package include: +Embed SolarFarmer's API into your workflow. Typical use-cases of the package include: -* Building SolarFarmer API JSON payloads for 2D energy calculations. -* Running 2D and 3D energy calculations from existing API payload files. -* Managing and visualizing simulation results. -* Iterating over API payloads to explore design variations and optimization scenarios. - -!!! note - This package is periodically updated to remain compatible with the latest SolarFarmer API releases. +* Build SolarFarmer API JSON payloads for 2D energy calculations +* Run 2D and 3D energy calculations from existing API payload files +* Manage and visualize simulation results +* Iterate over API payloads to explore design variations and optimization scenarios ## Install -From the directory run the following command: + +Install from PyPI using your favorite package manager, for example: + ```bash -pip install solarfarmer +pip install dnv-solarfarmer ``` + !!! tip + For full functionality install **all**: `pip install "dnv-solarfarmer[all]"` - For full functionality install **all**: `pip install --user solarfarmer[all]` +!!! note + This package is periodically updated to remain compatible with the latest SolarFarmer API releases. +## Getting Started -## Usage !!! warning - A commercial API key is required to run calculations with SolarFarmer's cloud energy yield engine. Start by [acquiring your SolarFarmer web API token](https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/WebApi/Introduction/ApiKey.html){ target="_blank" .external }. For more details, see the [SolarFarmer web API introduction page](https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/WebApi/Introduction/introduction.html){ target="_blank" .external }. Once you have your API key, provide it to the SDK using either the **SF_API_KEY** environment variable or pass it directly as the `api_key` argument when calling the energy calculation function or other endpoints. +Choose your workflow: load existing API files, build plant configurations from scratch, or integrate custom data models to run the SolarFarmer energy calculation in the cloud. For example, Calling the energy calculation model with all the API inputs in a folder: ```py import solarfarmer as sf -# A project id (optional) -project_id="calculation example" - # API key (optional, it could be an environment variable 'SF_API_KEY') api_key = "Your SolarFarmer API key here" @@ -58,30 +57,16 @@ results = sf.run_energy_calculation(inputs_folder_path=folder_with_inputs, api_key=api_key) ``` -## Getting Started - -Choose your workflow: load existing API files, build plant configurations from scratch, or integrate custom data models to run the SolarFarmer energy calculation in the cloud. - [Explore Getting Started Guide](getting-started/index.md){ .md-button .md-button-primary target="_blank" .external } !!! tip - The package comes with sample files for both the 2D and 3D energy calculations, which are used in the tutorials. Alternatively, you can get additional sample files from the [API step-by-step tutorials](https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/UserGuide/Tutorials/Tutorials.html) or export your own from [SolarFarmer's desktop application](https://mysoftware.dnv.com/download/public/renewables/solarfarmer/manuals/latest/UserGuide/HintsAndTips/APIJSON/ImportFromAPIJSON.html). - - -## Docs -To build the documentation, run from the directory the commands: -```bash -zensical build -zensical serve -``` -In a browser navigate to `localhost:8000` to see the documentation. - ## Contributing & License -Suggestions and code contributions are welcome — please open a PR or Issue. + +Suggestions and code contributions are welcome on [GitHub](https://github.com/dnv-opensource/solarfarmer-python-sdk). This repository is licensed under the Apache License, Version 2.0 (see [LICENSE](license.md)). For technical support, contact [solarfarmer@dnv.com](mailto:solarfarmer@dnv.com). diff --git a/mkdocs.yml b/mkdocs.yml index 237656e..ecc5624 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,7 +79,6 @@ plugins: extra: line_by_line: false show_bases: false - - mkdocs-jupyter nav: - Home: index.md @@ -90,11 +89,6 @@ nav: - Workflow 3 - Advanced Integration: getting-started/workflow-3-plantbuilder-advanced.md - Quick Start Examples: getting-started/quick-start-examples.md - End-to-End Examples: getting-started/end-to-end-examples.md -- Example Notebooks: - - 'Using the About and Service Endpoints': 'notebooks/Example_About_Service_endpoints.ipynb' - - 'Running 2D and 3D Calculations': 'notebooks/Example_EnergyCalculations.ipynb' - - 'Creating Plants with PVSystem (using metadata)': 'notebooks/Example_PVSystem.ipynb' - - 'Terminating Asynchronous Calculations': 'notebooks/Example_TerminateAsync_endpoint.ipynb' - API Reference: api.md - External Resources: - Endpoint definitions: diff --git a/pyproject.toml b/pyproject.toml index e2ff3f5..9081d5d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,7 +39,6 @@ dependencies = [ docs = [ "zensical>=0.0.20", "mkdocstrings[python]>=0.26.1", - "mkdocs-jupyter>=0.24", ] test = [