Skip to main content

Changelog

All notable changes to MangoGridStudio are documented here.

Format: grouped by sprint batch. Each entry identifies what shipped, what changed at the API level, and whether there are breaking changes.

[Batch 4] — 2026-05-21 — Public Documentation Site​

New​

Documentation site — docs.spenergy.solutions

  • Getting Started — 8-step walkthrough from account setup to your first solved dispatch result, with sample request/response
  • API Reference — complete REST endpoint documentation covering the solver API, AI Analyst, ISO data feeds, model builder, and power flow endpoints; request/response schemas with field-level descriptions
  • Unit Commitment Concepts — plain-language explainer of the day-ahead and real-time commitment problem; how MangoGridStudio solves it; the startup-cost/ramp-rate/reserve distinction that separates it from simple economic dispatch
  • LMP Decomposition — three-component formula (energy + congestion + loss), worked two-city example, intuition for why LMPs diverge across nodes
  • Glossary — 80+ terms across power systems, ISO/market, and platform-specific vocabulary
  • Changelog — this page
  • Full-text local search — Cmd+K / Ctrl+K instant search across all docs pages; no external dependency; Algolia DocSearch application in progress for post-launch upgrade
  • Dark mode, mobile-responsive layout, WCAG 2.1 AA accessible

Infrastructure​

  • Cloudflare Pages deployment pipeline for docs.spenergy.solutions; PR preview deployments on every docs pull request
  • OpenAPI sync CI: automatic drift detection between FastAPI schema and the published API reference on every route change

Breaking Changes​

None.

[Batch 3] — 2026-03-15 — Experiment Engine, PCM Polish, Docs​

New Features​

Experiment Engine (P5)

  • POST /experiments/submit — submit parametric scenario batch with grid, Latin hypercube, Monte Carlo, Sobol, or custom sampling
  • GET /experiments/{id}/status — poll experiment progress with per-scenario tracking
  • GET /experiments/{id}/results — aggregated statistics (min/max/mean/std per output metric)
  • GET /experiments/{id}/results/download — download results as CSV, JSON, or Parquet
  • POST /experiments/{id}/cancel — cancel a running experiment (returns 409 on terminal-state experiments)
  • WS /ws/experiments/{id}/stream — real-time scenario-level progress events (6 message types, 15s heartbeat)
  • Five scenario matrix sampling strategies: grid, Latin hypercube, Monte Carlo, Sobol, custom
  • Nine network mutation operators including PJM M28 marginal cost recalculation and carbon pricing
  • Thread-safe Julia batch runner with per-scenario timeout and parallel execution
  • Thread-safety hardening for daily pipeline LMP and module cache state

PCM Framework Polish (P7)

  • Accessibility hooks: useChartKeyboardNav, useChartA11y, useReducedMotion, useFocusTrap, useFocusOnRouteChange
  • Dark mode + high-contrast theme: ThemeMode extended to 'high-contrast', useThemeAwareChart with MutationObserver
  • Chart export utilities: ExportableChart HOC, chartExport.ts (SVG, CSV, PNG, PDF export)
  • Performance: useCanvasFallback (500-element threshold), selective D3 sub-module imports, LazyMapLibre, Vite manualChunks
  • Keyboard navigation: useGlobalShortcuts, ShortcutHelpDialog, useChartKeyboardPatterns
  • Responsive: useResizeObserver with 100ms debounce

Documentation

  • docs/dev/API_REFERENCE.md — full REST + Julia API reference with request/response schemas and curl examples
  • docs/dev/DEVELOPER_QUICKSTART.md — 20-minute quickstart: clone → first UC solve → first experiment → AI Analyst
  • docs/dev/ARCHITECTURE_OVERVIEW.md — Mermaid system diagram, component descriptions, data flow, directory layout
  • docs/dev/DEPLOYMENT_GUIDE.md — Docker Compose + Kubernetes + SSL + monitoring + backup
  • CHANGELOG.md — this file

Bug Fixes​

  • Daily result record: fixed field count mismatch (24 → 29 fields). All fields now populated including infeasible_hours, binding_constraints_detail, and curtailment_mw from ED results.
  • Experiment runner: per-scenario timeout correctly cancels stalled Julia tasks.
  • ThemeToggle.tsx three-way cycle (light → dark → high-contrast → light) corrected.

Internal​

  • 21 contract tests for experiment API payloads
  • 20 testsets for constraint validation equivalence
  • Validation metrics enriched with constraint tier classification and message formatting
  • Debug mode: writes structured JSON dispatch/slack/dual tables to test results
  • Trace mode: solver trace log points for regression analysis
  • CI pipeline: Python contract tests, Julia solver tests, E2E benchmarks, stress tests, skip/broken detection, formulation artifact validation

[Batch 2] — 2026-03-14 — PCM Framework, Education, DSL Validation​

New Features​

Scenario Comparison and Education UI (P3)

  • Education store (educationStore.ts) with Zustand + immer, localStorage persistence, 5 learning paths
  • UCDeepDiveLessons.tsx, LearningPathSelector.tsx, 6 learn routes
  • ConstraintSatisfactionAnimator and WhatIfSliderPanel components
  • 6 Jupyter notebooks: UC quickstart, LMP decomposition, sensitivity sweep, tuning workflow, constraint explorer, warm start speedup
  • Notebook references PJM M11 §6.4 and M28 §4 numeric examples throughout

Calibration Pipeline (P6.1–P6.4)

  • Calibration pipeline — auto-calibrates UC model parameters via grid search + scipy.optimize, with out-of-sample validation
  • 49 calibration tests, all passing
  • Formulation artifact validation: validates formulation file existence and required section presence (MODEL SIZE, OBJECTIVE FUNCTION, DECISION VARIABLES, CONSTRAINTS)

Constraint Validation

  • 25 new testsets covering constraint registry completeness, variable indexing, and PJM M28 objective formulation
  • Formulation artifact output enforced in CI: pipeline fails if formulation files are missing required sections

Onboarding and Training Materials (P8)

  • docs/published/ONBOARDING_CURRICULUM.md — 4-hour new user curriculum (4 modules)
  • docs/published/training/TRAINING_DECK_TEMPLATE.md — 48-slide trainer deck outline
  • docs/published/ADMIN_SETUP_GUIDE.md — 10-section IT admin deployment guide
  • docs/published/GETTING_STARTED.md — 8-step no-terminal user walkthrough
  • docs/published/UNDERSTANDING_RESULTS.md — 6 chart types explained for operators
  • docs/published/WHAT_IF_STUDIES.md — 4 concrete what-if study examples
  • docs/published/MODEL_HEALTH_GUIDE.md — 5 quality check tiers with action steps
  • docs/published/FAQ.md — 30 questions across 6 categories
  • docs/GLOSSARY.md — 80+ terms: power systems, software/math, ISO/regulatory, MangoGridStudio-specific

Breaking Changes​

None.

Bug Fixes​

  • Formulation utilities: write_formulation_files now enforces all 4 required section headers.
  • Calibration: BaselineSelector correctly handles scenarios with no historical reference (returns 0.0 deviation rather than raising).

Internal​

  • Constraint catalog auto-generated from model documentation generator
  • Variable dictionary — 25 decision variables with dimensions, units, bounds
  • Constraint diagram — Mermaid relationship map
  • CI fails on stale generated docs
  • Onboarding materials complete: 18/18 tasks

[Batch 1] — 2026-03-13 — Core Solver, Analyst Module, Constraint System​

New Features​

Enhanced UC Solver (P1)

  • Julia enhanced UC module: full DA-UC MILP formulation
  • 17 constraint categories registered in Python constraint registry and enforced in the Julia solver
  • LP relaxation warm start: reduces MILP solve time by >15% on repeat runs
  • Post-solve improvement pass for solution quality refinement
  • Prior solution injection for sequential multi-day studies
  • Stochastic unit commitment: scenario tree formulation
  • N-1 contingency cuts added lazily during branch-and-bound
  • Multi-zone decomposition using ADMM (Alternating Direction Method of Multipliers)
  • Lagrangian relaxation with subgradient-based step size adaptation

Analyst Module (P1–P2)

  • ID validation and canonical ID resolution (/modules/analyst/ids/)
  • Scenario provenance storage and retrieval (/modules/analyst/provenance/)
  • Baseline computation (/modules/analyst/baseline/compute) with rate limiting
  • Result ingestion: constraints, injections, dispatches, LMP, PTDF (/modules/analyst/results/)
  • Explain artifact generation: PTDF × ΔP drivers, unit drivers, relief candidates, LMP decomposition (/modules/analyst/explain/{id}/generate)
  • AI Analyst chat (/modules/analyst/chat) with 5 tool-calling tools backed by Claude API
  • 291 analyst module tests passing

Julia Solver HTTP API

  • Async job queue with configurable worker threads
  • SHA-256 input deduplication + LRU result cache
  • X-Cache: HIT/MISS header on solve responses
  • Per-route rate limiting
  • ArtifactStore: Parquet+zstd columnar compression, S3/MinIO upload, SHA-256 checksum headers
  • PTDF / LODF sensitivity analysis
  • Full OpenAPI 3.1 spec at backend/julia_api/openapi.yaml

Authentication

  • JWT-based authentication: access tokens + refresh tokens with configurable TTLs
  • Token rotation (/auth/rotate-secret) with instant invalidation of all existing tokens
  • Per-user API keys for programmatic access (/api/users/me/api-keys)
  • AUTH_BYPASS_ENABLED flag for development

ISO Market Data Fetchers

  • 7 ISO fetchers: PJM (Data Miner 2), CAISO (OASIS), MISO, ERCOT, ISO-NE, NYISO, SPP
  • gridstatus integration
  • S3 cache layer for fetched data
  • PJM benchmark builder: PSS/E v30 RAW file parser, PUDL generator enrichment, offer curve enrichment, CEMS dispatch pipeline

Breaking Changes​

None — this was the initial release.

Known Issues​

  • Stochastic UC requires validation tests before production use.
  • Twin, Graph, Discovery, and Congestion forecasting endpoints are specification-level only (return 404).
  • Prometheus metrics endpoint for the FastAPI backend is not yet implemented (/metrics returns 404 on port 58000). Julia API metrics are available on the solver service port (configured in .env).

Version history summary​

BatchDateHighlights
Batch 32026-03-15Experiment engine, PCM accessibility/export polish, developer docs
Batch 22026-03-14Education UI, calibration pipeline, onboarding and user guides
Batch 12026-03-13Enhanced UC solver, Analyst module, Julia HTTP API, ISO data fetchers

See GitHub releases for full history.