Skip to content

Getting Started with the SolarFarmer Python SDK

The SolarFarmer SDK supports three distinct user workflows. Choose the one that matches your use case and expertise level.

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. For more details, see the SolarFarmer web API introduction page.

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.

Choose Your Path

Workflow 1: Load and Execute Existing API Files

For: Solar data analysts and engineers with existing SolarFarmer API JSON files.

Goal: Run energy calculations using available pre-configured payloads.

Key Classes and Functions:

  • run_energy_calculation() - Execute the calculation with existing files
  • CalculationResults - Access and analyze results (returned directly by run_energy_calculation())

Time to First Result: 5 minutes

Example

You have a folder with EnergyCalcInputs.json, module.PAN, inverter.OND, and weather data.

Load them and run a calculation immediately.

Workflow 2: Design Plants with PVSystem

For: Solar engineers and designers creating new plant configurations.

Goal: Define high-level plant specifications and automatically construct API payloads.

Key Classes:

  • PVSystem - Define plant configuration (location, capacity, equipment, etc.)
  • CalculationResults - Access and analyze results (available via plant.results after calculation)

Time to First Result: 10-15 minutes

Example

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 for details.

Workflow 3: Advanced Integration and Custom Data Models

For: Software developers integrating SolarFarmer into custom applications.

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

Prerequisites: Familiarity with SolarFarmer's API structure and data model.

Time to First Result: 30+ minutes (depends on workflow complexity)

Example

Map your proprietary plant database to SolarFarmer objects, build custom workflows, or integrate with other simulation tools.

Integrated Class Examples

Once you know your workflow, see how the classes work together in real-world scenarios.

View Quick Start Examples

Need Help Deciding?

I want to... Go to Workflow
Run calculations on existing API files Workflow 1
Design a new plant from scratch Workflow 2
Integrate SolarFarmer into my software Workflow 3
See real code examples Example Notebooks

Next Steps

  1. Select your workflow from the list above
  2. Follow the guide step-by-step
  3. Explore the examples to see classes in action
  4. Look into the End-to-End Examples to dive deeper into the classes
  5. Refer to API documentation for detailed class references