Getting Started

Prerequisites

• Python 3.12+
• Docker (optional, for containerized deployment)

Installation

Docker (recommended)

docker-compose up -d

The API will be available at http://localhost:8000.

Local Development

# Install dependencies
pip install -r requirements.txt

# Start the API server
uvicorn api:app --host 0.0.0.0 --port 8000 --reload

Your First Simulation

The following sequence shows what happens when you run a simulation:

1. Check the API is running

curl http://localhost:8000/health

2. Upload a scenario

Scenarios contain market price data. Upload a ZIP file with CSV price data:

curl -X POST http://localhost:8000/scenarios/upload \
  -F "file=@market_data.zip" \
  -F "name=NL 2024" \
  -F "country=NL" \
  -F "description=Dutch market data 2024"

The response includes the scenario_id you'll need for simulations.

3. Run a simulation

curl -X POST http://localhost:8000/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "title": "My First Simulation",
      "description": "10 MWh battery test",
      "startProject": "2024-01-01",
      "projectLifeYears": 25,
      "bessCapacity": 10.0,
      "bessPower": 5.0,
      "bessMaximumSOC": 90,
      "bessMinimumSOC": 10,
      "bessRoundTripEfficiency": 90,
      "bessLifetimeCycles": 8000,
      "gridChargingCapacity": 10.0,
      "gridDischargingCapacity": 10.0,
      "gridTarif": "HT/LT",
      "gridStandingChargeTransport": 5000,
      "gridTransportedEnergy": 50,
      "economicsInflation": 0.02,
      "economicsDiscountRate": 0.05
    },
    "run": {
      "scenario_id": 1,
      "simulation_years": 1,
      "strategy": "rolling_lp",
      "enabled_markets": ["day_ahead"],
      "foresight_days": 3
    }
  }'

4. Read the results

The response contains:

{
  "status": "success",
  "summary": {
    "financial": {          
      "total_revenue_eur": 85000,
      "net_revenue_eur": 42000,
      "npv_eur": 95000,     // Net present value
      "roi_percent": 3.5,   // Return on investment
      "irr_percent": 8.2    // Internal rate of return
    },                      
    "operational": {        
      "total_charge_mwh": 1700,
      "total_discharge_mwh": 1640,
      "total_cycles": 370,
      "final_soh_percent": 98.2,
      "capacity_utilization_percent": 45.2
    }                       
  },
  "simulation_time_seconds": 2.8
}

Add ?include_timeseries=true to get the full 15-minute resolution schedule.

Example Configuration

Get a complete example configuration from the API:

curl http://localhost:8000/example-config

Interactive API Docs

The API includes built-in documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Environment Variables

Variable	Default	Description
DB_PATH	scenarios.db	Scenario metadata database path
PROFILE_DB_PATH	derived from DB_PATH	Profile metadata database path
DEFAULT_SCENARIO_DIR	default_scenario	Default scenario ZIP location
CUTOUT_DIR	profile_generator/data	ERA5 weather data directory
SIMULATION_WORKERS	CPU count	Max parallel simulation workers

Next Steps

• Learn about the supported Markets
• Explore all Parameters
• See the full API Reference