The source combines a hybrid adequacy screen, storage MILP, research studies, and an interactive learning workbench. The companion starts with a small synthetic daily power balance.
Native-source lesson guide · Offline interactive lab · Lesson configuration · Configuration schema
Open the previous-animation gallery · Local gallery
Earlier animated artwork, waveform demos, and original interactive experiences are linked alongside the current animations.
- Download or clone this repository and open
docs/index.htmlin a modern browser. - Select Module 1, apply its preset, and compare the declared checkpoint with the plotted result.
- Change one slider, inspect the model assumptions, then export the configuration or telemetry for your notes.
The browser lab runs offline with no packages, accounts, or live data feeds. Its numbers are deterministic teaching simulations. Each checkpoint states its model time and tolerance; passing it demonstrates agreement with that model, not field calibration or production readiness.
| Module | Investigation | Approximate time |
|---|---|---|
| 1. Follow a single-bus balance | Identify which sources serve demand and where a simple screen stops. | 12 min |
| 2. Test a resource sensitivity | Quantify the effect of a smaller solar resource without changing demand. | 15 min |
| 3. Separate adequacy from optimization | Explain the different questions answered by a dispatch policy and a cost-minimizing storage model. | 18 min |
| 4. Prepare a reproducible native follow-up | Carry a transparent screening question into the source workbench without inflating the claim. | 18 min |
Who this is for: Energy researchers, engineering educators, and developers inspecting hybrid-resource assumptions.
- README.md
- START_HERE.md
- apps/api/pyproject.toml
- apps/web/package.json
- apps/api/helioforge/engines/hybrid.py
- apps/api/helioforge/engines/storage.py
- docs/HYBRID_METHODOLOGY.md
Node.js >=22 for the standalone preview command; Python 3.11+ for the API package (launcher guide lists 3.11–3.13).
node scripts/preview-demo.mjs
python -m pip install -e "apps/api[dev]"
python -m pytest apps/api/tests
python launch.py --no-browserThese commands come from the audited source revision. Runtime requirements and the project's own validation limits are documented below; the standalone browser lab does not execute these commands.
The detailed project guide below remains the source for installation, supported features, licences, and scientific limits. The browser equations and laboratory settings do not change the original application or numerical engine.
Project documentation, installation, attribution, and existing validation
Open the public browser preview · Purpose, usage and limits · Methodology · Help · Model registry · Build and deployment guide
· MIT license · Verification and limits
Interactive hybrid-energy research and learning workbench with auditable numerical screens and a local Python API.
The full-spectrum roadmap includes 59 named study models across all 12 workspaces, advanced model visuals, local evidence imports and optional provider/device connectors. See the per-view completion and external-dependency ledger, historical verification record, and connector setup. The public preview shows generated examples; its Terminal is a separate browser calculation. New advanced-study runs and optimization require the local Python API.
The four delivery modes are shared with the generated overview, About, Methodology, Help, and app.json capability facts. The current contract is CAPABILITIES.md; its generated inventory is MODEL_REGISTRY.md and MODEL_REGISTRY.json.
The hosted dashboard loads content-addressed example JSON on demand and verifies its SHA-256 before display. A failed download retains the configuration and offers retry. The separate HelioForge-Preview.html download contains every example for offline use; edited advanced studies still require the local Python API. The hosted build uses pinned esbuild only during compilation, with no added browser runtime package. Publish the shell, data manifest, all referenced chunks and matching CSP together.
New numerical records include a versioned model provenance envelope. Historical records without that envelope remain explicitly unknown. Workspace v1 records are migrated to v2 only after preview and confirmation, with an exact backup and migration receipt. See the local acceptance evidence and publication verification method. Remote CI and deployment evidence are recorded separately in immutable release receipts. Provider, native-device, field and participant acceptance remain separate gates.
- Bundled synthetic examples: Bundled synthetic examples are precomputed outputs; the public browser edition does not calculate new study-model results from edited inputs.
- Bounded browser Terminal: The Terminal runs new deterministic, bounded 24-hour energy-balance cases in the browser; it uses a greedy policy and is not an optimizer.
- Advanced local Python: The separate local Python application runs new calculations for the advanced study models and optimization.
- Opt-in local external providers: Optional local external providers are separate, opt-in integrations; credentials and explicit consent are required where applicable. The public static preview makes no provider calls.
Start with one task: Explore a bundled example. Open the public preview and inspect a labeled synthetic result. Calculate a bounded Terminal case. Open Scenario compare and use the Parametric energy workbench. Set up advanced local calculations. Use the source setup guide to run the Python application on your machine.
The registry keeps application, catalogue, data and model versions separate. The 59-study catalogue and its current bundled default examples have content digests but no independent named versions; the study result envelope does not declare a separate schema_version. Each per-study card lists its current model version, declared numeric units and bounds, input fields, equations, Python implementation, test file, default fixture digests, executed source-bound software checks, remaining untested conditions, and limits. Software checks do not establish scientific validation; deployment identity belongs to the release receipt.
If HelioForge Energy Lab helps you study this workflow, a star helps other energy researchers and engineering educators find it.
Open the hosted synthetic demo or run the identical standalone artifact locally:
Prerequisite: Node.js 22 or later; tested here with Node.js 24. This runs locally with synthetic examples. It does not connect to a live provider or publish user input.
git clone https://github.com/mohammadrezwankhan/helioforge-energy-lab.git
cd helioforge-energy-lab
node scripts/preview-demo.mjsOpen http://127.0.0.1:4173. Stop the server with Ctrl+C. The first screen is a demonstration, not verified current information. Keep private or real-world records out of this evaluation. The standalone preview does not run new local-Python study calculations; the Terminal separately calculates bounded cases in the browser. Use the source guide below for advanced local Python calculations.
HelioForge connects a browsable energy-learning interface to an optional local Python calculation API. The standalone preview preserves a reproducible starting point and includes the separate deterministic Terminal calculator. Advanced numerical runs use the backend and its explicit scenario assumptions.
Read the engineering walkthrough and adjacent-tool comparison, or follow the source map.
- Current verification and limits
- Architecture and source map
- Contribution guide and small contribution tasks
- Security reporting, support, and roadmap
Install the Python project with its development extras in an isolated environment; follow the original guide below. HelioForge also has a separately locked web workspace.
python -m pytest apps/api/tests
python -m ruff check apps/api
npm --prefix apps/web ci
npm --prefix apps/web run build
npm --prefix apps/web testPrior reports under docs/ describe the supplied candidate. They do not replace the current quality report. Passing software checks is not clinical, educational, financial, safety, or production-service validation.
First-party source is available under MIT. Bundled dependencies retain their upstream notices; trademarks and third-party content are not relicensed.
Supplied engineering guide, product boundaries, and detailed usage
An interactive hybrid-energy laboratory, learning studio and auditable research workspace.
36 architectures · 24 scenarios · 36 lessons · 12 workspaces · 8 + 1 review roles
Start here · Explore the preview · Coverage · Model limits · Champion verification
Named setups, actual saved-run reopening, a keyboard command palette, a guided first experiment, validated workspace recovery and a clearer local-first toolbar. Invalid in-progress hybrid inputs no longer leave stale numerical results visible. Other-model drafts survive navigation, same-market reconnection preserves completed calculations, and a new host allow-list hardens the local boundary. The numerical engines and 36/24/36 catalogue remain unchanged.
Download/extract → run the platform starter → open the local app. Prebuilt browser assets are included. See START_HERE.md, verified changes, and release limitations. “Champion” is the edition name and design ambition, not an award or certification.
Configure an off-grid renewable microgrid, compare a hospital's normal operation with a grid outage, or investigate the model requirements of a hydrogen hub. Rotate the 3D scene, inspect individual assets, edit capacities, run an hourly energy screen and export the exact inputs and results. Then use a guided lesson to explain the outcome—not just admire a chart.
Scope is visible in the interface: 19 architectures have runnable electricity-balance screens; 17 advanced architectures are explicitly study-only. There are 20 numerical scenario presets and four dynamic/control study presets. Applicability filtering yields 285 runnable architecture–scenario combinations, not an indiscriminate 36 × 24 claim. All combinations have energy/SOC invariant tests.
This is an educational and research release. It is not a plant controller, an accredited course, a calibrated digital twin, investment advice or a dynamic-stability simulator. The initial battery state is explicit and terminal SOC is unconstrained. A cheaper run that serves less load is not declared the winner.
| Workspace | Working capability |
|---|---|
| Hybrid systems lab | Search 36 architectures; inspect original 3D meshes; configure capacities, control assumptions and grid limits; apply scenarios; calculate and export hourly results. |
| Learning studio | 36 architecture-linked activities with objectives, experiment steps, evidence requirements and explained two-question self-checks. Local progress, confirmation before reset and exportable lesson plans. |
| Scenario compare | Pin up to three completed runs; inspect demand service, imports, curtailment, cost and initial/terminal battery energy. JSON export; no misleading automatic ranking. |
| Command centre | Synthetic portfolio search, country filters, overview and evidence export. |
| Storage & flexibility | Existing short-horizon SciPy/HiGHS battery MILP with direction and SOC constraints. This is separate from the new greedy hybrid screen. |
| PV economics / Investment desk | Existing PV, project-finance and acquisition screens, including debt-free/null states. |
| Research pillars / Forecast studio | Existing drift, reliability, lifecycle-carbon and seeded illustrative price calculations. |
| Market intelligence / Construction & pilots | Source register, synthetic pilot workflow and persisted evidence events—not live legal or field validation. |
| Agent council | Eight deterministic review roles and a critic-style synthesis; local mode is not independently executed agents. Deterministic local mode by default; opt-in OpenAI adapter can review an explicitly selected saved hybrid run. |
Original low-poly 3D geometry is transformed by a real orthographic camera and rendered in Canvas2D. Drag to orbit, use keyboard or camera buttons, and select assets for text descriptions. This is software 3D, not WebGL. Solar, wind, battery, water, hydrogen and other asset categories have distinct colors and named labels. Links animate conceptually; they are not solved branch flows.
The interface includes responsive containers, searchable technology synonyms (PV, BESS, H2), explained tags, smooth view transitions, a reduced-motion switch and system-preference support. A small achievement animation follows a newly passed self-check only; it never implies an engineering approval. New Python calculations remain disabled in disconnected preview mode; the separate Terminal calculator remains available in-browser.
 |  |
Open HelioForge-Preview.html from the extracted repository. It contains the entire interface, original graphics and bundled Python-generated example results with no external font or JavaScript CDN. File-browser policies vary; the locally served application below is the preferred way to use calculations. A GitHub file view shows source rather than running HTML; use the included manual Pages deployment workflow to host a public preview only.
Python 3.11–3.13 is the declared support range; this release was tested here with Python 3.13.5. Prebuilt browser assets are included, so Node is not required just to run them.
python -m venv .venv
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell instead:
# .venv\Scripts\Activate.ps1
python -m pip install -e apps/api
python launch.pyOpen http://127.0.0.1:8000. The server binds to loopback. On Windows, start-windows.cmd creates a virtual environment, installs missing pinned runtime dependencies and launches the same local application. It downloads Python dependencies on first use; it does not install Python itself.
Try a useful first experiment: select Hospital islanding microgrid, run the baseline, pin it, apply Four-hour outage, run again and pin. Open Scenario compare; inspect critical shortfall and terminal battery energy before comparing cost. Names in the versioned catalogue are the source of truth.
Node 22 is used by the build configuration. From the repository root:
cd apps/web
npm ci
npm run typecheck
npm run build
npm test
cd ../..
python -m pytest apps/api/testsAfter editing the canonical catalogue:
python scripts/generate-hybrid-assets.py
cd apps/web && npm run buildThis regenerates browser data from apps/api/helioforge/data/hybrid_catalog.json; do not hand-edit hybrid-data.ts. To regenerate the original numerical overview snapshot, run python scripts/generate-snapshot.py before the web build.
Docker and Compose configuration are retained. They were not executed during this build; use the loopback instructions as the verified path. Do not expose this local API publicly without the security hardening in SECURITY.md.
The atlas spans grid-connected and off-grid PV/wind/battery systems; remote, residential, community, telecom, hospital, data-centre and industrial sites; hydro, mobility, floating PV, agrivoltaics and electrical desalination loads. Advanced study configurations include hydrogen, CHP, geothermal, thermal storage, heat pumps, V2G, pumped hydro, flywheels, supercapacitors, marine systems, nuclear–hydrogen and coordinated networks. Specialized carrier/network physics are not implemented merely because the architecture is shown.
Scenario presets cover weather shortfalls, demand peaks, outages, grid limits, tariffs, battery aging/trips, reserve levels, generator outages and reduced river availability. Black start, reconnection, weak grids and ramp-limit design are marked study-only. The source archive's five cases are mapped in REFERENCE_MAPPING.md, including separate AC/DC utility-PV entries.
Read HYBRID_METHODOLOGY.md, the full architecture/scenario matrix, and the lesson-authoring contract before adding a model.
Local mode is a deterministic checklist—no LLM is called. The optional OpenAI Agents SDK adapter runs eight specialists concurrently and then a critic, using structured output, cancellation on error, bounded turns/tokens and a timeout. Set an API model actually available in your own project; product nicknames are not hard-coded as API model identifiers.
External execution is disabled by default and requires server-side credentials, a local admin key and explicit consent. It may incur API charges. Live provider execution was not tested here; control flow and failure handling were tested with a fake SDK. See AI_SETUP.md and the next-build goal prompt.
The historical v0.3.0 results, failed-attempt history and coverage limitations are in docs/champion/VERIFICATION.md. The source changes, local launcher, human-UAT script, recovery notes and file hashes are included. Current responsive release evidence is in docs/FULL_AUDIT_REPORT.md; the Terminal verification records the earlier release.
404 Python tests · 65 frontend tests · 32 browser checks passed in this environment. Python statement coverage is recorded in docs/coverage.json; coverage measures exercised code, not scientific validity. The hybrid matrix includes 285 applicable runnable combinations plus 100 seeded capacity/input perturbations. All twelve views passed 390px and 320px page-overflow checks after layout fixes.
Browser tests exercised Chromium DOM/canvas and real API calculations through a host HTTP bridge because direct browser localhost access was restricted. They do not certify direct-browser networking, CSP enforcement, file navigation, screen-reader compatibility or field engineering. Read the complete validation record and final audit.
A good contribution adds a reproducible experiment, not just another attractive card. Start with a hand-checkable benchmark, an original lesson, accessible interaction improvements or a clearly licensed time-series fixture. Every new architecture needs a capability declaration; every new numerical claim needs tests and stated units.
Contributing · Good first issues · Security · Code of conduct · MIT license
5,000 stars is a community ambition, not a delivered result. The open-source launch plan defines usefulness and contribution milestones. No fabricated stars, awards, affiliations, testimonials or adoption statistics are included.
The local workbench now contains 59 distinct experimental studies across all twelve views, with source-backed limits, result exports, visual editors and signed local evidence. See delivery and audit, the experiment index, and verification. The standalone edition contains generated examples; edited numerical runs require Python.
