Skip to content

End-to-End Examples

These examples provide detailed explorations of specific API features and workflows. Use them to deepen your understanding of SolarFarmer capabilities beyond the Quick Start Examples.

Quick Reference

Example Purpose Workflow Audience
Using the About and Service Endpoints Understand API capabilities and system information All Everyone
Running 2D and 3D Calculations Learn the functionality when working with synchronous and asynchronous energy calculations Workflow 1 Loading and working with existing calculations
Creating Plants with PVSystem Master plant design with the PVSystem class Workflow 2 Designing new plants
Creating Plants with EnergyCalculationInputs Build flexible plant configurations with Pydantic model payloads Workflow 3 Advanced integration and batch processing
Terminating Asynchronous Calculations Manage long-running 3D calculations Workflow 3 Advanced integration and async 3D workflows

Using the About and Service Endpoints

Notebook: Example_About_Service_endpoints.ipynb

Topics Covered:

  • Querying API capabilities and version information
  • Understanding service status, typical API key errors and SolarFarmer features

Use this when: You need to verify API compatibility, check available features, or understand system capabilities before running calculations.

Running 2D and 3D Calculations

Notebook: Example_EnergyCalculations.ipynb

Topics Covered:

  • 2D synchronous calculations with the ModelChain endpoint
  • 3D asynchronous calculations with the ModelChainAsync endpoint
  • Accessing and comparing results between approaches
  • Handling calculation responses and error cases

Use this when: You're working with Workflow 1 (existing API files) and want to understand different calculation methods and their results in detail.

Creating Plants with PVSystem

Notebook: Example_PVSystem.ipynb

Topics Covered:

  • Building plant designs from scratch
  • Configuring modules, inverters, and mounting systems
  • Setting up weather data and location information
  • Advanced plant parameters (bifacial modules, trackers, soiling patterns)

Use this when: You're following Workflow 2 (PVSystem design) and need detailed guidance on plant configuration options and best practices.

Creating Plants with EnergyCalculationInputs

Notebook: Example_Compose_Plant.ipynb

Topics Covered:

  • Building structured JSON payloads with EnergyCalculationInputs and PVPlant
  • Flexible plant configuration through composable Pydantic models
  • Integrating with custom databases and data models
  • Preparing payloads for batch processing

Use this when: You're following Workflow 3 (advanced integration) and integrating SolarFarmer with your own systems or processing multiple projects.

Terminating Asynchronous Calculations

Notebook: Example_TerminateAsync_endpoint.ipynb

Topics Covered:

  • Managing long-running 3D calculations
  • Cancelling asynchronous jobs safely
  • Monitoring calculation status

Use this when: You're following Workflow 3 (advanced integration) and need to manage multiple asynchronous calculations or cancel long-running jobs.

Learning Path

Foundation (Optional but Recommended):

Review Using the About and Service Endpoints to understand API capabilities

Then Choose Your Workflow:

Workflow 1:
Existing Files		 Workflow 2:
Design Plants		 Workflow 3:
Advanced Integration
Start with Quick Start Example 1

Deepen with Running 2D and 3D Calculations

Explore Workflow 1 Docs		 Start with Quick Start Examples 2-5

Master design with Creating Plants with PVSystem

Explore Workflow 2 Docs		 Start with Quick Start Example 6

Build payloads with Creating Plants with EnergyCalculationInputs

Manage async with Terminating Async Calculations

Explore Workflow 3 Docs

Back to Quick Start

If you prefer a hands-on approach with complete workflows, see the Quick Start Examples for ready-to-run code covering real-world scenarios.

Next Steps