Helionyx

Helionyx

Size hybrid energy systems by talking to your AI assistant. Helionyx is an open-source Model Context Protocol (MCP) server that sizes solar PV, wind, battery storage, diesel generator and grid-connected systems. It runs the classic techno-economic workflow:

1. simulate every candidate design hour by hour for a full year;
2. discard designs that break your constraints;
3. rank the rest by net present cost (NPC), with payback, LCOE, bills and emissions.

The assistant never invents numbers. It asks scoping questions, calls deterministic tools and explains the results; every figure comes from a solver run with a run ID that anyone can reproduce. Use it for pre-feasibility studies, client proposals, rural electrification planning, teaching and cross-checking other tools.

Why Helionyx

• Grounded answers: the solver produces every number; the assistant only explains them.
• Complete method: hourly dispatch (load following, cycle charging, TOU grid strategy), life-cycle economics, tariffs with TOU, demand charges and export schemes, grid outages.
• Beyond a single answer: sensitivity grids, Pareto trade-offs between cost, CO₂ and reliability, multi-year load growth with staged expansion.
• Cross-checked: compare against REopt, MicroGridsPy and SAMA from the same scenario.
• Open and local: Apache-2.0, runs on your machine, works offline with bundled data, exports HOMER-ready time series and Excel reports.

Get started

Pick the way you use AI tools. Each one takes about a minute.

Then ask, for example:

Size a PV and battery system for a 60-room hotel in Negombo on the CEB hotel tariff. We have

about 1,200 m² of usable roof.

The quickstart walks through a first study in under ten minutes.

Where to find Helionyx

Data and accuracy

Helionyx ships with a Sri Lankan country pack (lk): CEB and LECO tariff structures and export schemes, weather alignment to Asia/Colombo time, grid outage patterns and load archetypes for Sri Lankan buildings. The engine itself is country-agnostic; new countries are added as data packs (data-pack guide).

**The tariff rates, component costs, fuel price, discount rates and emission factors in the

lk pack are unverified placeholders.** Use results to learn the tool and to compare

options, not for real decisions, until the data is verified. validate_scenario raises

warning HNX-W001 for every unverified tariff. See the disclaimer.

Releases and changes are listed in the changelog. Hosted mode with Microsoft Entra ID sign-in and OpenTelemetry monitoring are in development for 1.0.

Architecture

flowchart LR

U([User]) <--> C["MCP client Claude Code · Claude Desktop Copilot Studio · custom agent"] C <-->|"stdio or Streamable HTTP"| S

subgraph H["Helionyx (local-first, deterministic)"] S["MCP server 22 tools · 9 resources · 6 prompts"] S --> SV["Services scenario · run · sensitivity · results · export"] SV --> K["Engine Numba dispatch kernel · pvlib · economics · billing"] SV --> ST[("SQLite metadata Parquet artefacts")] SV --> P["Country packs tariffs · components · archetypes"] end

SV -.->|"HTTPS, cached"| W["NASA POWER · PVGIS"] SV -.->|"cross-check"| R["REopt v3 API"] SV -.->|"JSON subprocess"| X["helionyx-microgridspy (EUPL) helionyx-sama (AGPL)"]

The server never calls an LLM. Copyleft solvers run as separate processes, so the core stays Apache-2.0.

A sizing conversation

sequenceDiagram

autonumber actor User participant AI as AI assistant participant HX as Helionyx tools User->>AI: "Size PV and a battery for my 60-room hotel in Negombo" AI->>HX: create_site, fetch_resource, synthesize_load AI->>HX: list_tariffs, compute_bill (baseline) AI->>HX: create_scenario, validate_scenario HX-->>AI: assumptions and warnings AI->>User: confirm assumptions? User->>AI: yes AI->>HX: run_optimization → get_job_status AI->>HX: get_results, explain_run, get_monthly_summary HX-->>AI: ranked designs, NPC, bills, run ID AI->>User: top three designs, every number cited to the run

Solvers

compare_runs puts the results side by side. Multi-year scenarios run on native and heuristic only.

Multi-year analysis

Add multi_year to a scenario to grow the load and search a staged investment:

multi_year:

load_growth_rate: 0.03 # year y load = year-1 load × 1.03^(y−1) sample_every_years: 5 # plus each stage boundary and the last year expansion:

• year: 10 pv_add_kwp: [0, 50, 100] bess_add_kwh: [0, 150]

The expansion sizes become extra search axes. Stage capital enters the cash flow in its year, with its own replacements and salvage, and reliability constraints must hold in every sampled year. Each candidate reports its sampled years under multi_year.years. See the methodology (decision D20).

Features

• Resource data: hourly GHI, temperature and wind from NASA POWER (and PVGIS where covered), CSV import, on-disk caching, offline mode, UTC → local civil time alignment, leap-day removal and gap filling. NASA POWER 2023 data for three Sri Lankan sites is bundled, so the reference cases run offline.
• Load profiles: 11 synthetic archetypes, random variability with a seed, calibration to 12 monthly bills, composite loads and measured-load import (15/30/60-minute).
• Tariffs and bills: versioned YAML tariffs with flat, block and TOU energy charges, fixed, demand and minimum charges, levies, and the net metering, net accounting and net plus export schemes.
• Scenario builder: defaults from the country pack, a full assumption audit (origin, source and date for every value), validation rules, SHA-256 scenario hashes, versioning and YAML round-trips. Scheduled and random grid outages.
• Simulation and optimisation: an 8,760-hour dispatch kernel in Numba (PV via pvlib, wind power curves, idealised battery, diesel genset with load-following or cycle-charging, grid-connected TOU strategy), parallel enumerative search, HOMER-style economics (NPC, LCOE, replacements, salvage, payback, IRR) and emissions.
• Search: full enumeration, or a seeded heuristic pattern search for spaces of up to 50 million candidates; Pareto front of NPC, CO₂ and capacity shortage.
• Multi-year analysis: annual load growth and up to three capacity-expansion stages, searched together with the initial system and costed year by year.
• Sensitivity: one-variable sweeps and two-variable grids with re-optimisation, optimal architecture per case and NPC elasticities.
• Grounded explanations: structured cost breakdowns, cost drivers, binding constraints, dispatch statistics and comparisons, with provenance and a disclaimer on every result.
• Exports: HOMER-importable series plus a parameter sheet, Markdown and Excel reports, hourly time series and scenario YAML.
• Cross-check solvers compared with compare_runs: REopt v3 (API key), and MicroGridsPy and SAMA as separately licensed add-on packages (see docs/adapters.md).
• HOMER parity kit: protocol, results template and helionyx parity compare.
• Claude skill and MCP prompts for guided workflows, plus a grounding checker.

Install from source

For development (Python 3.11–3.13):

git clone https://github.com/Jayzilva/helionyx.git

cd helionyx uv venv uv pip install -e ".[dev]" # or: python -m venv .venv, then pip install -e ".[dev]"

See CONTRIBUTING for the checks to run before a pull request.

Command-line quickstart

Run a reference case from the command line (works offline):

helionyx run reference_cases