Skip to content

index.md

Latest commit

 

History

History
140 lines (111 loc) · 5.8 KB

index.md

File metadata and controls

140 lines (111 loc) · 5.8 KB
Raw

Overview

Module Map

Module Description Key Exports
esfex Top-level package load_config(), ESFEXConfig, __version__
esfex.config.schema Pydantic configuration models ESFEXConfig, SystemConfig, GeneratorConfig, BatteryConfig
esfex.config.loader YAML configuration loading load_config(), load_yaml(), load_system_config()
esfex.runner Simulation orchestrator Orchestrator, SimulationState, YearResults
esfex.bridge.adapters Julia optimization model wrappers PowerSystemAdapter, MasterProblemAdapter, MGAAdapter
esfex.bridge.julia_setup Julia runtime initialization initialize_julia(), get_julia(), get_esfex_module()
esfex.io.demand Demand data loading load_demand_data(), create_sectoral_demand(), DemandDataManager
esfex.io.exporter Results export (HDF5/CSV/Excel/JSON) ResultsExporter, export_system_results()
esfex.models.ev EV fleet modeling generate_ev_profiles(), generate_v2g_availability(), aggregate_ev_profiles()
esfex.models.ev_adoption EV adoption modeling run_ev_logistic_adoption(), run_ev_bass_diffusion(), run_ev_tco_parity(), run_ev_policy_driven()
esfex.models.ev_analysis V2G & grid impact analysis generate_charging_profiles(), compute_v2g_potential(), compute_battery_degradation(), assess_grid_impact()
esfex.models.solar_rooftop Rooftop solar model generate_rooftop_solar_profiles(), integrate_rooftop_solar(), calculate_rooftop_potential()
esfex.models.financial_analysis Post-optimization financial analysis compute_system_financials(), compute_technology_financials(), run_sensitivity_analysis(), run_monte_carlo()
esfex.utils Helpers and temporal utilities BoundaryConditions, calculate_rolling_horizon_windows()
esfex.sensitivity Sobol sensitivity analysis SensitivityEngine, SensitivityParameter, SobolResult

Julia Backend

Module Description Reference
ESFEX.jl Core optimization models Julia API
power_system.jl Operational dispatch (LP/MIP) Julia API - Power System
master_problem.jl Capacity expansion planning Julia API - Master Problem
transmission_dc.jl DC power flow constraints Julia API - Transmission DC
mga.jl MGA/SPORES near-optimal alternatives Julia API - Utility

Architecture Overview

YAML Config
    |
    v
load_config() ──> ESFEXConfig (Pydantic validated)
    |
    v
Orchestrator
    |
    ├── MasterProblemAdapter ──> master_problem.jl  (capacity expansion, all years)
    |       |
    |       └── MGAAdapter ──> mga.jl  (near-optimal alternatives)
    |
    └── Per-year loop:
            |
            ├── PowerSystemAdapter ──> power_system.jl  (operational dispatch)
            |       |
            |       └── TransmissionDCAdapter ──> transmission_dc.jl  (DC power flow)
            |
            ├── PrimaryEnergyAdapter ──> primary_energy.jl  (fuel supply chain)
            |
            └── ResultsExporter ──> HDF5 / CSV / Excel / JSON

Quick Start

from esfex import load_config
from esfex.runner import Orchestrator

# Load and validate configuration
config = load_config("isla_juventud.yaml")

# Create orchestrator and run simulation
orchestrator = Orchestrator(config, output_dir="./results", config_path="isla_juventud.yaml")
results = orchestrator.run(years=25, start_year=2025)

# Access per-year results
for yr in results:
    print(f"Year {yr.year}: cost=${yr.objective:,.0f}, "
          f"RE={yr.re_penetration:.1%}, "
          f"load shed={yr.load_shed:.1f} MWh")

Post-Processing

from esfex.io.exporter import ResultsExporter

exporter = ResultsExporter("results/results_isla_juventud.h5")
exporter.to_csv("results/csv/")
exporter.to_excel("results/report.xlsx")

Financial Analysis

from esfex.models.financial_analysis import (
    FinancialAssumptions,
    compute_system_financials,
    compute_technology_financials,
    run_sensitivity_analysis,
)

assumptions = FinancialAssumptions(discount_rate=0.08, tax_rate=0.25)
financials = compute_system_financials("results/results_isla_juventud.h5", assumptions)

print(f"System NPV:  ${financials.npv_total:,.0f}")
print(f"Project IRR: {financials.project_irr:.1%}")
print(f"System LCOE: ${financials.lcoe_system:.1f}/MWh")
print(f"WACC:        {financials.wacc:.1%}")

# Per-technology breakdown
techs = compute_technology_financials("results/results_isla_juventud.h5", assumptions)
for name, tf in techs.items():
    print(f"  {name}: LCOE=${tf.lcoe:.1f}/MWh, CF={tf.capacity_factor:.1%}")

Sensitivity Analysis

from esfex.sensitivity.engine import SensitivityEngine, SensitivityParameter

params = [
    SensitivityParameter(name="Fuel Cost", key="fuel_cost", lower_bound=0.5, upper_bound=3.0),
    SensitivityParameter(name="RE Invest", key="invest_cost_renewables", lower_bound=0.5, upper_bound=2.0),
]
engine = SensitivityEngine(mode="config", parameters=params, n_base_samples=128)
result = engine.run_config_analysis("config.yaml", "output/")
result.to_csv("sobol_indices.csv")

Julia API

See the Julia API page for all exported types and functions from ESFEX.jl.