Repository navigation
Releases
v0.6.0 — 100% Headless Grid + Stand-Alone Off-Grid PV+BESS+Genset
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
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 →
PowerShift48-slot planner (pvsyst_plan_tou_storage_schedule): converts arbitrary TOU tariff schedules into 1- or 2-cycle/day PVsystPowerShift48 half-hour slots with minimum arbitrage spread guard and usable-energy power capping, returning drop-inGridStorageUpdates. - 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
PVsystCLI8760-hour simulations (verify_top_k, guarded bydry_run=True+confirm=True).
- Stage 1: fast pure-Python grid sweep over
2. Zero-Template Li-ion .BTR, 3-Voltage .OND, and Optional .PAN Refit (Verified on PVsyst 8.1.7)
- Zero-template Li-ion
.BTRsynthesis (pvsyst_build_sourced_component(component_type="BTR")): synthesizesLFPandNMCLi-ion battery definitions directly from datasheet parameters, enforcing PVsyst 8.1.7 per-cell voltage, internal resistance (≤ 40 mV/cell @ I10),AlphaSOC, andCapaCourantvalidation rules. - 3-voltage efficiency curve
.ONDsynthesis & editing: supportsFlags=$1560,VNomEff,EfficMaxV,EfficEuroV, andProfilPIOV1..V3in both zero-template synthesis andpvsyst_update_componentcurve updates (preserving full backward compatibility for single-voltage.ONDfiles). - Optional
.PANsingle-diode auto-refit: passingrefit_single_diode=Trueonpvsyst_update_componentrecomputesRShunt,Rp_0,Rp_Exp,RSerie,Gamma, andmuGammafrom updated STC specs (refit_single_diode=Falsedefault 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=Truedefault,confirm=Truerequired for execution). PVsystCLItransient abort retry: automatically retries transient startup/mid-check aborts (PVSYST_CLI_TRANSIENT_RETRIES, default1) 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_studyandoptimize_bess_sizing(6 prompts total).
- 3 new read-only workspace resources:
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_runguidance). - 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 completepyproject.tomlpackage 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.py31/31 OK (0 skips) +scripts/run_tests.py --suite unit447/447 OK (0 skips). - Live
PVsystCLI 8.1.7verification: 0 warnings across full 8760-hour runs covering refitted.PAN+ edited 3-voltage.ONDand zero-template LFP.BTR+ TOUPowerShift48-slot storage.
v0.4.0
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_componentnow 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-pointProfilPIOefficiency curve synthesis withVNomEff,NbMPPT,IDCMax,IMaxDC.- Verified live on
PVsystCLI 8.1.7with zero warnings.
pvsyst_list_componentsnow 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_weatherandpvsyst_simulate_design(weather.mode) withpvgis_tmy(PVGIS v5.3 8760-hour TMY) andnasa_power(NASA POWER hourly solar/meteorological data) alongsideopen_meteo(ERA5). - Added one-step
prepare=Trueonpvsyst_acquire_weatherto 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 terrainbase_slope_deg(BaseSlopesynchronized acrosspvOrientandpvShdArrayTable, live-verified withrecompute_shading=TrueonPVsystCLI 8.1.7with zero warnings).
5. Bounded Closed-Loop Optimization (pvsyst_optimize_variant)
- Implements a safe Diagnose -> Clone -> Patch -> Re-simulate optimization loop (
max_iterations1..5). - Defaults to
dry_run=Truewith full parameter diff preview; requires explicitconfirm=Trueto 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
adminandexpert). - 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, anddocs/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.7end-to-end probe for zero-template 620W bifacial.PAN+ 110kW 9-MPPT.OND+BaseSlope=5.0°3D shading recomputation: 0 warnings
v0.3.0
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
pvBiFacialserialization and readback (pvsyst_auto.project.bifacial) with.PANbit-23 ($00800000) preflight verification. - Zero-template
ground_sheds(Sheds) andground_tracker(UnlimTracking/TrackHorizNSAxis) synthesis and execution viapvsyst_simulate_design.
2. AI Autonomy & Guidance Layer
- New
pvsyst_suggest_sizingtool (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+.ONDelectrical parameters. sizing_mode="auto_from_components"inpvsyst_simulate_designfor 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, andpvsyst_export_engineering_deliveryinto default tool groups (40 default tools / 69 total withPVSYST_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, andpvsyst_run_simulation.
4. Parametric Batch Sweeps & Sub-Hourly Pipeline
- New
pvsyst_run_batch_sweeptool (pvsyst_auto.workflows.batch) executing multi-axis nativeBatchParams.CSVsweeps (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/.METconversion,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_level0, 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 reportactive_dispatch_cap_kw = PLimGrid * cos(phi)without flaggingEApGrid > PLimGrid; variants embeddingPVObject_UserNeeds=pvLoadwith rootpvVCalcul.Flagsbit 19 ($00080000) clear now emitLOAD_NOT_ENABLED; addeddetect_native_refusalhelper and_DEMO_Tracking.VC3clipping calibration test. - #193:
update_project_sourcesnow preserves distinct.METheaders (SiteM,SiteMet,DateDebF,DateFinF,PasAccum, etc.) instead of copying.SITintoSiteMet; headless house tasks now reject non-zeroorientations[].base_slope_deg/BaseSlopeindry_run=Truepreflight 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
Release v0.2.0: Zero-Template Synthesis, Bifacial, Utility 3D, Batch Sweeps, Sub-Hourly & Tool Surface Consolidation.
v0.1.0
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