Repository navigation
Releases
PEARSim 0.1.1
Documentation and provenance release. There is no change to the simulator or its results.
- README: the install section points at the published PyPI packages and at the MCP Registry entry
io.github.PEAR-power/pear-sim(#19). - Every Python and Rust source file carries an
SPDX-License-Identifier: Apache-2.0and copyright header. README and AGENTS.md explain the attribution required when the code is copied (#17). - Product source files carry a provenance-mark GUID in their header (#18).
pip install pear-sim==0.1.1
uvx pear-sim-mcpThe attached files were downloaded from PyPI and verified against PyPI's SHA-256 digests.
PEARSim 0.1.0
First public release of PEARSim, published by PEAR Power.
Simulator
-
Event-driven piecewise-LTI kernel (modified nodal analysis with an ideal-diode
active set): scheduled gate edges and natural commutations are located as
exact events; capacitor voltages and inductor currents stay continuous. -
DC-DC (buck, boost, inverting buck-boost in CCM/BCM/DCM), DAB, half-bridge
LLC, half-wave / 6-pulse / 12-pulse and phase-controlled rectifiers,
two-level three-phase inverters (six-step, SPWM, SVPWM, floating neutral,
weak grid, grid-following with PLL), three- and five-level NPC inverters,
PMSM, synchronous reluctance and DC machines, coupled windings and a
saturable inductor. -
Control: fixed and complementary PWM with dead time, three-phase and NPC
modulators, sampled PI and dq current loops, and a signal-block layer
(gain, sum, product, saturation, unit delay, lookup tables, Park/inverse
Park, logic) for writing controllers as data. -
Post-processed losses and thermal: device cards, Foster networks, air and
liquid cooling, efficiency map, rainflow counting. -
Piecewise-linear conduction:
on_resistanceonideal_switchanddiode,
forward_voltageondiode(v = V_f + R_on·i in the circuit equations; a blocking
diode turns on at V_f). Checked against closed forms; ideal devices keep their hashes. -
pisignal block: a discrete PI controller with optional limits and back-calculation
anti-windup, expanded at load time into primitive blocks. -
Clearer errors: an unknown component type lists the valid ones (and how to model a
MOSFET); a node left without a conduction path next to a switch suggests the missing
antiparallel diode.
Analyses
- Periodic steady state by Newton shooting (cycle averages exact for every state);
small-signal loop gain with phase/gain margins for a declared compensator,
including the ZOH and computation-delay term, for one PWM leg with or without
dead time; a gain margin is reported unbounded when the sweep covers the
validity band and the phase never reaches −180°; modal resonance audit; event-aligned Fourier/THD;
bounded parameter and tolerance-corner sweeps; run comparison.
Fixed before release (found by running 20 user stories through the MCP server)
- Loop gain: margins were taken at the FIRST 0 dB / −180° crossing; a loop crossing
0 dB twice could report ~150° instead of the binding ~53°. Margins are now the worst
over every crossing, and all crossings are recorded. - A parameter sweep failed on any model with a thyristor (the schematic renderer did
not know the symbol). - The buck analytic self-check failed correct circuits whose run had not settled; it
now requires periodic steady state and otherwise reportsnot_runwith the reason. - EMI and compliance are declared unsupported in the capability registry and the
server instructions. - MCP: tolerance corners pass on warnings and flag corners that had not settled;
simulatereports whether the run reached steady state. - A run whose energy balance misses its numerical budget now carries a warning that
names the likely cause (a stiff circuit on an explicit solver) and the remedy. - The flyback library entry explains the bleeder-resistor condition under which a
user model runs, instead of claiming it cannot run.
Fixed before release (second round of 20 user stories)
losses-thermal.jsonpublishes each device's mean switching power, its total mean
power and a min/max envelope of its junction temperature, so the report and the MCP
server draw them instead of dividing energies themselves.- Report waveforms were thinned by a fixed stride: on a 20 kHz PWM recorded at 1 us
and drawn at 800 points it picked about one sample per carrier period and drew a
clean multilevel staircase that is not in the data. The display now keeps each
bucket's minimum and maximum, so every pulse stays visible. Because that overview of
a long switched run is a filled band, each main waveform now also gets a zoom: 200
sample steps drawn undecimated, shaded on the overview, shared by all signals and
placed where the first signal switches with a duty near one half. - Junction temperature no longer starts the junction-to-case Foster stages cold under a
case already held at its steady temperature. A slow stage (100 ms against a 40 ms run)
read as headroom: on the 250 kW five-level example the hottest switch was reported at
92.5 °C instead of 103.1 °C. The stages now start at the steady rise for the run-mean
power (thermal.initial_state). - A heatsink bound without a fan must declare a 0 m³/h row: the estimate reads that
natural-convection point, and a table starting at forced air was read as one. - The report labels analytic-check values read from the run "Simulated", not
"Measured"; the NPC modulator warning no longer says "three-level" on a five-level
run; the ideal-device note says where device-card losses come from. - A transient run is limited to 2 000 001 output samples, checked at load. Before,
2 s at a 10 ns output step allocated a 1.6 GB time grid and kept growing until the
machine ran out of memory, long before any time limit stopped it. - MCP
simulateandsteady_statereturn the confidence level together with
what it means and which features have no independent check, sonot_runis no
longer read as a failed run. - An override of a parameter that no value references as
${name}is refused with
the reason; it used to be accepted and change nothing. The FOC, flux-map and
signal-block buck examples no longer declare parameters their signal blocks do
not use. - Energy audit with a salient machine or flux map: the reluctance power
1/2 i^T (dL/dt) i is not represented, so the balance is nownot_assessedwith
that reason instead ofoutside_numerical_tolerancewith a stiff-solver hint. - Machine back-EMF branches are no longer counted as supplies; the audit and the
MCP power summary report the machines' electromagnetic power separately, and
efficiency_outputaccepts a machine id (drive efficiency). - Harmonics: a
genericsemantic analyses any recorded signal, e.g. a rectifier's
DC-side ripple (amplitudes only, no THD). - MCP:
get_artifactreads line artifacts (events, control and signal traces) by
line range; a relativemodel_pathon a server without a project directory
explains how to fix it.
Design exploration
pear-sim batch,api.evaluate_designsand the MCP toolevaluate_designs: screen
up to 2 000 designs of one model (Latin hypercube, grid or an explicit list), rank
feasible designs by one objective under any number of constraints (signal metrics,
device losses, junction temperature), and re-run the top finalists with full
evidence. A finalist must reproduce its screening values exactly or the batch fails.
Screening runs are lean and keep only the files the ranking reads. The result is the
best design of the sample, not an optimum. Seedocs/batch.md.pear-sim sensitivity,api.sensitivityand the MCP toolsensitivity: global
sensitivity over declared parameter ranges. Morris screening (mu_star,sigma) or
Sobol indices (first-orderS1, totalST, Saltelli design), every index with a
bootstrap 95 % interval. The estimators are checked against closed forms (a linear
function, the Ishigami function) and the ideal buck law. Seedocs/sensitivity.md.
Performance
- Recorded output samples solve the circuit's algebraic unknowns once per sample
instead of once per output, and the mode feasibility check reuses the vector it
already holds for every diode guard. Same arithmetic, fewer evaluations: every
example bundle is identical; buck ~20 % and NPC ~8 % less CPU time. - Diode mode selection replays its search for a repeated switch configuration: which
candidates it visits and what each compiles to depend only on the gates and the
diode guess, so only the state-dependent feasibility check runs again. The
topology key is also built once per search instead of once per candidate. Five-
level NPC over three line periods: mode selection 2.9 → 1.3 s, whole run 7.0 →
5.1 s CPU. Every example's bundle is unchanged except wall time
(tests/test_mode_plans.pyholds replayed and fresh searches to exact equality). - Optional compiled kernel
rust/pear-sim-core(Rust, PyO3) andsimulate --backend rust. Inside each segment the kernel integrates (a step-for-step port of SciPy's
RK45 with terminal events), samples every output, integrates the metrics and the
energy audit, and finds the state extrema. Every covered example agrees with the
reference engine within 1e-12 on metrics, samples, energy audit and extrema, with
identical event sequences (CI jobrust-core). Simulation phase 1.2–25× faster
(buck 7×, NPC 2–2.6×). Coversdopri5models with DC sources; anything else is
refused with the reason. A run records its backend, which is part ofrun_sha256.
Seedocs/rust-core.md. - Long-lived point workers for
batch,sensitivity,sweep parameterand
tolerance-corners: each worker imports Python and PEARSim once and then runs many
points, instead of starting a fresh interpreter per point. Each point is still a
killable child process with its own captured stderr, warnings, working directory and
timeout; a worker that overruns or dies is replaced. Retained bundles are identical
to one-shot workers apart from measured wall times (tests/test_worker_pool.py).
Small models: 950 → 199 ms per point; the 40-design loss-card batch example
41 → 24 s on 7 jobs. Workers are recycled after 200 points. batchandsensitivitytake"backend": "rust"in the request: every run uses the
compiled kernel, checked against the model before anything runs. Runs are accepted
only from the exact requested engine id; finalists re-run on the same engine. The
loss-card batch example ranks identically to the reference e...