Skip to content

Releases

v0.6.0 — 100% Headless Grid + Stand-Alone Off-Grid PV+BESS+Genset

Choose a tag to compare

@Anonymousnake Anonymousnake released this 21 Nov 17:05

v0.6.0 — 100% Headless Grid + Stand-Alone Off-Grid Coverage

Every .VCx-writing capability in �0.6.0 has been live-verified on PVsystCLI 8.1.7 with 0 warnings, backed by 502 passing tests across Linux & Windows (Python 3.10 & 3.12).

Highlights

  • 100% Headless Architecture (Zero Win32 GUI Click-Bridge): Removed legacy
    ative/scene.py (-1,531 lines) and "gui" scene import mode; slimmed pvsyst_open_native_project (expert group) to a pure viewer launcher.
  • MV/HV Multi-Stage Transformers & AC Collection Network (pvsyst_configure_transformers): Supports MV-only, parallel MV, and cascaded MV+HV transformers (auto-populating PVsyst 8.1.7 required HV datasheet tags HVTrfDS*), ISO 60228 cable sections (10..1200 mm²), night disconnect, and VAR_GROUPS["transformers"] (EMVOhmL/EMVTrfL/EHVOhmL/EHVTrfL).
  • 3D Continuous Terrain DEM (pvShdGround) & Table Draping: Pure-Python Bowyer–Watson Delaunay TIN terrain generator from XYZ JSON/CSV + lon/lat ENU projection + optional [geo] extra (pip install "pvsyst-cli-mcp[geo]" for
    asterio GeoTIFF .tif), draping fixed sheds and single-axis trackers directly onto terrain elevations/slopes.
  • Special Loads & Deterministic Outage Generators: Added native HouseHold appliance schedules (yearly & seasonal 24-bit half-hour masks), deterministic Probability distribution sampling into native embedded hourly snapshots, WeakGrid mode="generated" deterministic outage schedules, and SystemUnavail mode="random" materialized UnavailPeriods.
  • Spectral Correction, Cross-Orientation Conversion (pvsyst_convert_orientation), & Native PDF Economics:
    • Native First Solar / precipitable-water spectral correction (UseSpectralCorr + SpectralCorrection, SiMono/SiPoly/CdTe/CIS/�Si/Custom).
    • In-place cross-orientation conversion ( ixed ↔ seasonal ↔ sheds ↔ racker_ns ↔ racker_2axis ↔ dome) with automatic stripping of incompatible 3D/result caches.
    • Native EconomicEval=TEcoEvaluation writer so official PVsystCLI PDF reports render econeval and inancialbalance pages directly.
  • Full Stand-Alone Off-Grid PV + BESS + Backup Genset (pvsyst_simulate_design(scope="stand_alone")): Zero-template SystemType=Battery synthesis with .PAN, .BTR, MPPT/direct .RLT controllers, existing or inline auto-synthesized .GEN backup generators, VAR_GROUPS["stand_alone"] (E_User/E_Solar/E_BkUp/E_Miss/EUnused/BkUp_ON/FuelBU/SOCmean/T_LOL), off-grid diagnostics (diagnose_standalone), and lifetime diesel-fuel + genset maintenance LCOE (evaluate_standalone_economics).
  • Quality & Correctness Fixes Merged (PRs #222–#231): Hardened BESS/TOU overnight charging & cycle discharge capping, strict CSV unit guards across economics/BESS/reports, scale-independent IRR convergence, 3V OND & BTR validation, and shared test fixture consolidation.
  • Strict MCP Tool Surface Budget: 48 default tools (+2: pvsyst_configure_transformers, pvsyst_convert_orientation) / 77 total tools (PVSYST_TOOL_GROUPS=all).

Verified PVsyst 8.1.7 Engine Boundary

  • Native pvGridStorage in PVsyst 8.1.7 charges from PV only (no native grid-to-battery charger). For TOU grid-charging arbitrage modeling, use pvsyst_optimize_bess_sizing with �llow_grid_charging=true.

Install / Upgrade

``powershell
pip install -U pvsyst-cli-mcp

Optional GeoTIFF (.tif) terrain DEM support:

pip install -U "pvsyst-cli-mcp[geo]"
``

v0.5.0

Choose a tag to compare

@github-actions github-actions released this 20 Nov 12:57

pvsyst-cli-mcp v0.5.0

C&I PV+BESS Economics & Sizing, Zero-Template Li-ion BTR & 3-Voltage OND Synthesis, One-Shot Feasibility Study, and CI/PyPI Readiness


Highlights

1. C&I PV+BESS Economics, TOU PowerShift Planner & Hybrid Sizing Optimizer

  • Two-part demand-charge tariffs (tariff.demand_charge): supports monthly maximum-demand billing (demand), transformer contract-capacity billing (capacity), and automatic side-by-side comparison (compare) with recommended billing mode, baseline vs. post-PV/BESS peak shaving, and annual demand-charge savings.
  • Mid-life battery replacement & sensitivity tornado: models mid-life BESS pack replacement (battery_replacement_year, battery_replacement_cost_ratio / battery_replacement_cost) and deterministic one-at-a-time sensitivity sweeps (tariff, capex, yield, degradation) sorted by NPV swing.
  • Interactive Plotly report upgrades (pvsyst_generate_report): adds monthly peak-demand shaving comparison, financial sensitivity tornado, and 2D BESS sizing NPV heatmap + Pareto frontier charts (in both Chinese and English).
  • TOU → PowerShift 48-slot planner (pvsyst_plan_tou_storage_schedule): converts arbitrary TOU tariff schedules into 1- or 2-cycle/day PVsyst PowerShift 48 half-hour slots with minimum arbitrage spread guard and usable-energy power capping, returning drop-in GridStorageUpdates.
  • Two-stage hybrid PV+BESS sizing optimizer (pvsyst_optimize_bess_sizing):
    • Stage 1: fast pure-Python grid sweep over bess_kwh × pcs_kw × strategy (self_consumption, tou_arbitrage, peak_shaving) producing ranked candidates, 2D NPV heatmap, and CAPEX-vs-NPV Pareto frontier.
    • Stage 2 (optional): reconciles the top-K candidates via real PVsystCLI 8760-hour simulations (verify_top_k, guarded by dry_run=True + confirm=True).

2. Zero-Template Li-ion .BTR, 3-Voltage .OND, and Optional .PAN Refit (Verified on PVsyst 8.1.7)

  • Zero-template Li-ion .BTR synthesis (pvsyst_build_sourced_component(component_type="BTR")): synthesizes LFP and NMC Li-ion battery definitions directly from datasheet parameters, enforcing PVsyst 8.1.7 per-cell voltage, internal resistance (≤ 40 mV/cell @ I10), AlphaSOC, and CapaCourant validation rules.
  • 3-voltage efficiency curve .OND synthesis & editing: supports Flags=$1560, VNomEff, EfficMaxV, EfficEuroV, and ProfilPIOV1..V3 in both zero-template synthesis and pvsyst_update_component curve updates (preserving full backward compatibility for single-voltage .OND files).
  • Optional .PAN single-diode auto-refit: passing refit_single_diode=True on pvsyst_update_component recomputes RShunt, Rp_0, Rp_Exp, RSerie, Gamma, and muGamma from updated STC specs (refit_single_diode=False default preserves 100% legacy behavior).

3. One-Shot Feasibility Study, Runtime Resilience & MCP Discovery

  • One-shot feasibility study orchestrator (pvsyst_run_feasibility_study): chains inline zero-template component synthesis, simulation or existing CSV reuse, loss diagnostics, TOU schedule generation, hybrid BESS sizing, two-part economics + sensitivity, and interactive Plotly HTML report generation in one guarded workflow (dry_run=True default, confirm=True required for execution).
  • PVsystCLI transient abort retry: automatically retries transient startup/mid-check aborts (PVSYST_CLI_TRANSIENT_RETRIES, default 1) while never retrying license, syntax, model, or timeout failures.
  • Dynamic MCP Resources & Prompts:
    • 3 new read-only workspace resources: pvsyst://workspace/projects, pvsyst://workspace/components, pvsyst://workspace/results (5 resources total).
    • 2 new workflow prompts: ci_bess_feasibility_study and optimize_bess_sizing (6 prompts total).

4. Upstream Hardening (PRs #194–#221) & CI / PyPI Readiness

  • Includes all reliability fixes from PRs #194–#221 (regular-cadence timestamp enforcement in economics/report, self-consumption yield alignment, primary scenario promotion, OND curve floor scaling, near-shading loss diagnostics, batch parameter wiring, asymmetric MPPT guards, and strict dry_run guidance).
  • Upgraded GitHub Actions CI to Node 24-native majors (actions/checkout@v7, actions/setup-python@v7, actions/upload-artifact@v7, actions/download-artifact@v8) and fixed tag release uploads to avoid duplicate drafts.
  • Added PyPI OIDC Trusted Publishing workflow (.github/workflows/publish-pypi.yml) and complete pyproject.toml package metadata.

Tool Surface & Verification

  • MCP surface: 46 default tools (43 → 46: +pvsyst_plan_tou_storage_schedule, +pvsyst_optimize_bess_sizing, +pvsyst_run_feasibility_study), 75 total tools (PVSYST_TOOL_GROUPS=all), 5 resources, 6 prompts.
  • Offline CI & unit tests: scripts/ci_checks.py 31/31 OK (0 skips) + scripts/run_tests.py --suite unit 447/447 OK (0 skips).
  • Live PVsystCLI 8.1.7 verification: 0 warnings across full 8760-hour runs covering refitted .PAN + edited 3-voltage .OND and zero-template LFP .BTR + TOU PowerShift 48-slot storage.

v0.4.0

Choose a tag to compare

@github-actions github-actions released this 19 Nov 14:16

Highlights

v0.4.0 expands pvsyst-cli-mcp from single-run simulation into a full engineering workflow covering financial modeling, zero-template commercial component synthesis, multi-provider weather acquisition, finite 3D ground layouts with obstacles & base slope, bounded closed-loop optimization, and interactive bilingual HTML engineering reports.

1. Financial & Economics Evaluation (pvsyst_evaluate_economics)

  • Pure-Python cashflow engine supporting fixed tariffs, time-of-use (TOU) schedules, and PV+BESS arbitrage directly from PVsyst hourly simulation CSVs or batch summary CSVs.
  • Computes LCOE, NPV, IRR, simple & discounted payback, and 25-year degraded cashflow projections.
  • Ranks multi-scenario batch runs with full financial KPIs.

2. Zero-Template Commercial .PAN / .OND Synthesis & Electrical Filtering

  • pvsyst_build_sourced_component now supports zero-template mode (template_name=None):
    • .PAN: 5-parameter single-diode STC solver (RShunt, Rp_0, RSerie, Gamma), temperature coefficients (muIsc, muVocSpec, muPmpReq), bifaciality (BifacialityFactor), and cell layout (NCelS, NCelP).
    • .OND: Mode-1 8-point ProfilPIO efficiency curve synthesis with VNomEff, NbMPPT, IDCMax, IMaxDC.
    • Verified live on PVsystCLI 8.1.7 with zero warnings.
  • pvsyst_list_components now supports electrical range filters (power, voltage, efficiency, bifaciality, MPPT count) backed by an mtime-invalidated metadata cache (.mcp-component-index.json).

3. Multi-Provider Weather Acquisition (PVGIS v5.3 TMY & NASA POWER)

  • Extended pvsyst_acquire_weather and pvsyst_simulate_design (weather.mode) with pvgis_tmy (PVGIS v5.3 8760-hour TMY) and nasa_power (NASA POWER hourly solar/meteorological data) alongside open_meteo (ERA5).
  • Added one-step prepare=True on pvsyst_acquire_weather to download and convert directly to .SIT/.MET + manifest.
  • Supported automatic aggregation of sub-hourly (15min/30min) observation CSVs.

4. Finite 3D Ground Polygon Layout, Obstacles & Base Slope

  • Added 2D site polygon clipping with perimeter setbacks, concave polygons, and arbitrary row azimuths (scene/ground.py).
  • Added 3D near-shading obstacles (building, wall, mesh, tree) and terrain base_slope_deg (BaseSlope synchronized across pvOrient and pvShdArrayTable, live-verified with recompute_shading=True on PVsystCLI 8.1.7 with zero warnings).

5. Bounded Closed-Loop Optimization (pvsyst_optimize_variant)

  • Implements a safe Diagnose -> Clone -> Patch -> Re-simulate optimization loop (max_iterations 1..5).
  • Defaults to dry_run=True with full parameter diff preview; requires explicit confirm=True to execute; never mutates the baseline variant.

6. Interactive Bilingual HTML Engineering Reports (pvsyst_generate_report)

  • Generates standalone print-friendly bilingual (zh / en) interactive Plotly HTML reports (plotly>=5.18,<7.0) for single or multi-scenario studies.
  • Includes monthly yield/PR charts, loss waterfall diagrams, typical 24h TOU/BESS dispatch profiles, 25-year cumulative cashflow curves, and engineering diagnostics tables.

Tool Surface & Documentation

  • Default MCP surface expanded to 43 default tools across 8 groups (72 total tools including admin and expert).
  • Refreshed README.md, README.zh-CN.md, docs/tool-reference.md, docs/architecture.md, docs/native-entry-map.md, docs/testing-and-release.md, docs/sourced-components.md, docs/weather-preparation.md, and docs/single-design-inputs.md.

Verification

  • python scripts/ci_checks.py: 31/31 passed (including wheel packaging & documented tool-surface parity checks)
  • python scripts/run_tests.py --suite all: 429/429 passed
  • Live PVsystCLI 8.1.7 end-to-end probe for zero-template 620W bifacial .PAN + 110kW 9-MPPT .OND + BaseSlope=5.0° 3D shading recomputation: 0 warnings

v0.3.0

Choose a tag to compare

@Anonymousnake Anonymousnake released this 19 Nov 11:50

Highlights

v0.3.0 turns pvsyst-cli-mcp into an end-to-end AI-autonomous PV engineering MCP server paired with PVsystCLI 8.1.7, spanning zero-template bifacial utility design, deterministic string/inverter sizing, physics anomaly diagnostics, parametric batch sweeps, and 5/10/15/30-minute sub-hourly simulations.

1. Bifacial & Zero-Template Utility 3D Ground Layouts

  • Full pvBiFacial serialization and readback (pvsyst_auto.project.bifacial) with .PAN bit-23 ($00800000) preflight verification.
  • Zero-template ground_sheds (Sheds) and ground_tracker (UnlimTracking / TrackHorizNSAxis) synthesis and execution via pvsyst_simulate_design.

2. AI Autonomy & Guidance Layer

  • New pvsyst_suggest_sizing tool (pvsyst_auto.engineering.suggest) computing deterministic Voc/Vmp temperature bounds, string length (NModSerie), string count (NStringCh), inverter count, and DC/AC ratio from real .PAN + .OND electrical parameters.
  • sizing_mode="auto_from_components" in pvsyst_simulate_design for autonomous sizing directly from selected components.
  • Built-in MCP server instructions, 4 reusable workflow prompts (design_rooftop_pv, design_utility_bifacial, diagnose_and_optimize, parametric_sensitivity_sweep), and 2 reference resources (pvsyst://guides/workflow-overview, pvsyst://guides/parameters-reference).
  • Promoted pvsyst_license_info, pvsyst_project_handoff, and pvsyst_export_engineering_delivery into default tool groups (40 default tools / 69 total with PVSYST_TOOL_GROUPS=all).

3. Physics Result Diagnostics (pvsyst_diagnose_results)

  • Single-pass streaming anomaly detector (pvsyst_auto.engineering.diagnostics) covering PR integrity (monofacial & bifacial ranges), inverter clipping/overvoltage/undervoltage/current/threshold losses, near & electrical shading, soiling, curtailment, storage SOC/unmet load, nighttime export, high-irradiance zero output, and irradiance-vs-output phase lag.
  • Automatic compact diagnostic summaries embedded into pvsyst_simulate_design, pvsyst_run_house_task, and pvsyst_run_simulation.

4. Parametric Batch Sweeps & Sub-Hourly Pipeline

  • New pvsyst_run_batch_sweep tool (pvsyst_auto.workflows.batch) executing multi-axis native BatchParams.CSV sweeps (tilt, pitch, azimuth, albedo, soiling, tracker limits) with automatic Pareto/optimal ranking.
  • End-to-end 5 / 10 / 15 / 30 / 60 min sub-hourly weather preparation, .MEF/.MET conversion, build_sfi(..., time_step="subhour"), and annual energy aggregation.

5. Pre-Release Bug Fixes (#191, #192, #193)

  • #191: Refused house-task simulation attempts now mark runs[].status = "failed" in both the returned payload and saved checkpoint manifest; quiet batch runs (log_level 0, 1, or 2) now forward redacted native CLI refusal output on missing summary CSV.
  • #192: Diagnostics calibrated against PVsystCLI 8.1.7 output — apparent (kVA) grid limits compute and report active_dispatch_cap_kw = PLimGrid * cos(phi) without flagging EApGrid > PLimGrid; variants embedding PVObject_UserNeeds=pvLoad with root pvVCalcul.Flags bit 19 ($00080000) clear now emit LOAD_NOT_ENABLED; added detect_native_refusal helper and _DEMO_Tracking.VC3 clipping calibration test.
  • #193: update_project_sources now preserves distinct .MET headers (SiteM, SiteMet, DateDebF, DateFinF, PasAccum, etc.) instead of copying .SIT into SiteMet; headless house tasks now reject non-zero orientations[].base_slope_deg / BaseSlope in dry_run=True preflight before writing any files.

Verification

  • Offline CI checks (scripts/ci_checks.py): 31 / 31 OK
  • Offline unit & integration suite (scripts/run_tests.py --suite all): 412 / 412 OK (1 skipped)
  • Real stdio MCP + PVsystCLI 8.1.7 E2E (tests.e2e.test_mcp_full_workflows_e2e): 4 / 4 OK

v0.2.0

Choose a tag to compare

@Anonymousnake Anonymousnake released this 18 Nov 07:20

Release v0.2.0: Zero-Template Synthesis, Bifacial, Utility 3D, Batch Sweeps, Sub-Hourly & Tool Surface Consolidation.

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 18 Nov 01:08

What's Changed

  • Merge retained maintenance branches into main by @Anonymousnake in #101
  • Fix correctness defects found in the code review by @Anonymousnake in #100
  • Fix the remaining correctness defects from the code review by @Anonymousnake in #102
  • Unify object parsing and atomic file writes by @Anonymousnake in #103
  • docs: rewrite documentation in clear, practical engineering style by @Anonymousnake in #104
  • Add native PV-system outage removal and recovery by @Anonymousnake in #105
  • Add native module layout electrical shading by @Anonymousnake in #106
  • feat(native): headless house PV scene import (method=native) by @Anonymousnake in #107
  • feat(native): optional native scene import for house task by @Anonymousnake in #108
  • feat(native): support bounded single-orientation linear tables by @Anonymousnake in #109
  • feat(native): bounded single-orientation two-table/two-string fine layout by @Anonymousnake in #110
  • feat(native): isolate original CLI calls on private non-input desktop (Windows) by @Anonymousnake in #111
  • feat(native): deny window creation on plain-CSV runs; resolve current window station by @Anonymousnake in #112
  • feat(native): explicit per-cell string_layout binding + windowless native import by @Anonymousnake in #113
  • feat(simulation): reject invalid run-simulation requests before any native launch by @Anonymousnake in #114
  • native: multi-subarray explicit per-cell string_layout binding (two fixed planes) by @Anonymousnake in #115
  • feat(house): optional report_pdf CSV-only selector for native house delivery by @Anonymousnake in #116
  • feat(native): bind sparse two-subarray SubArrayId by source structure by @Anonymousnake in #117
  • test(sourced-house): CSV-only native full-chain boundary + completed resume by @Anonymousnake in #118
  • feat(native): grouped per-orientation multi-table string_layout binding by @Anonymousnake in #119
  • feat(native): support indexed batch summary filenames in public reader by @Anonymousnake in #120
  • feat(native): detect indexed batch summary in completion scan + opt-in gate by @Anonymousnake in #121
  • feat(native): general homogeneous fixed-orientation authoring + 8.1.7 saved-variant recovery by @Anonymousnake in #122
  • feat(native): BOM-mark rebuilt variant bodies that carry non-ASCII text by @Anonymousnake in #123
  • fix(editor): read/write PVsyst 8.1.7 #N-indexed shading-factor tables by @Anonymousnake in #124
  • feat(editor): write existing per-MPPT PNomAC_InMPPT declaration by @Anonymousnake in #125
  • fix(editor): refuse PNomAC_InMPPT values that serialize to 0.00 by @Anonymousnake in #126
  • feat(readback): expose stored per-subarray inverter_state in get_variant_parameters by @Anonymousnake in #127
  • feat(scene): author grouped house scenes with per-subarray inherited OND by @Anonymousnake in #128
  • feat(native): explicit per-request window-creation policy selector by @Anonymousnake in #129
  • feat(native): per-source PAN geometry with high-level inherited geometry handoff by @Anonymousnake in #130
  • fix(native): thread per-call allow_window_creation through sourced prepare by @Anonymousnake in #131
  • feat(native): opt-in readback of the saved native result cache by @Anonymousnake in #132
  • feat(native): opt-in preserve-source-hardware mode for sourced house tasks by @Anonymousnake in #133
  • feat(components): add REV (Sellers pvAddress) text component support by @Anonymousnake in #134
  • feat(native): explicit source subarray owner for same-orientation multi-table house by @Anonymousnake in #135
  • feat(native): wind-loss UV parameter edit and economic input readback by @Anonymousnake in #136
  • Native Shared Topology Readback by @Anonymousnake in #137
  • feat(native): read legacy DC-grid declarations without widening edit support by @Anonymousnake in #138
  • fix(ci): repair stale CLI test adapters and add portable contract gates by @Anonymousnake in #140
  • feat(acceptance): add budgeted native runner and independent artifact validation by @Anonymousnake in #141
  • fix(engineering): carry native house CSV runs through bound comparison and delivery by @Anonymousnake in #142
  • Remove disclaimer contracts, prune excessive tests, and split test suites by @Anonymousnake in #143

Full Changelog: https://github.com/Anonymousnake/pvsyst-cli-mcp/commits/v0.1.0