pulsim 2.0.0

██████╗ ██╗   ██╗██╗     ███████╗██╗███╗   ███╗
██╔══██╗██║   ██║██║     ██╔════╝██║████╗ ████║
██████╔╝██║   ██║██║     ███████╗██║██╔████╔██║
██╔═══╝ ██║   ██║██║     ╚════██║██║██║╚██╔╝██║
██║     ╚██████╔╝███████╗███████║██║██║ ╚═╝ ██║
╚═╝      ╚═════╝ ╚══════╝╚══════╝╚═╝╚═╝     ╚═╝

TL;DR

Pulsim is a SPICE alternative tuned for the switched-mode power electronics workload: PWL devices, finite-state topologies, $10^8$-step transients. Where SPICE pays full assembly + LU factorization on every step, Pulsim caches one state-space per switch combination and updates only the columns of $L+U$ that actually changed.

The v1.3.0 sparse LU rewrite + the v1.4.0 generalised path-based update framework give:

Both single-bit and (v1.4.0+) multi-bit / parametric paths run through an in-house C++23 sparse LU. No KLU, no SuiteSparse, no Eigen::SparseLU<complex> in production — only Eigen as a matrix container.

Why Pulsim

Performance

Numbers captured 2026-05-24 on macOS / Apple Silicon (-O3 -DNDEBUG). Reproducible end-to-end via cmake --build build --target pulsim_benchmarks followed by ./build/core/pulsim_benchmarks "[rank1][microbench]" (and the analogous tags [multi_bit], [parametric], [ac_sweep]).

1) Single-bit rank-1 (v1.3.0, N-switch chain)

3-backend microbench. (A) baseline solve per-mask cache, (B) Eigen sliding solver, (C) Pulsim path-based partial refactor.

Zero fallbacks across all 1999 single-bit Gray-code flips × 8 N values.

2) Multi-bit path-union (v1.4.0, Pulsim ÷ Eigen sliding solver)

Hit rate decays gracefully: ~45 % path-union at δ=2 → ~10 % at δ=4 (rest fall back cleanly to full factorize).

3) Parametric sweep / Monte Carlo (v1.4.0, Pulsim ÷ legacy rebuild)

Zero fallbacks across all 12 cells.

4) AC sweep complex LU (v1.4.0, Pulsim ÷ Eigen)

Both solvers numerically interchangeable. v1.4.0 contribution is no third-party LU on the production path; Backend::Eigen is kept explicitly available as a paper-comparison baseline.

Quick start

Prerequisites

Two native dependencies — everything else is header-only or vendored at configure time:

# macOS (Homebrew)
brew install cmake ninja eigen

# Debian / Ubuntu
sudo apt-get install -y cmake ninja-build libeigen3-dev

# Fedora
sudo dnf install cmake ninja-build eigen3-devel

Install from PyPI

pip install pulsim

Or build from source

git clone https://github.com/lgili/Pulsim.git
cd Pulsim
pip install -e .

First simulation — 8 lines

import pulsim as p

b = p.CircuitBuilder()
b.add_voltage_source("Vin", "n0", "gnd", 5.0)
b.add_resistor      ("R1", "n0", "vc",   1000.0)
b.add_capacitor     ("C1", "vc", "gnd",  1e-6)

res = p.simulate(b, t_end=5e-3, dt=1e-5)
p.plot.scope(b, res, signals=["vc"])      # one-line waveform

Parametric sweep — exploit the v1.4.0 path-based refactor

import numpy as np
import pulsim as p

def make_rc(R=5.0, C=10e-6):
    b = p.CircuitBuilder()
    b.add_voltage_source("v1", "vin", "gnd", 10.0)
    b.add_resistor      ("R_load", "vin", "vout", R)
    b.add_capacitor     ("C_out", "vout", "gnd", C)
    return b

def steady_state_vout(res, _params):
    states = np.asarray(res.states)
    return {"vout": float(states[-1, 1])}

# Sweep R_load through 100 values. v1.4.0 path-based refactor:
# build the cache ONCE, then reuse the L+U factors at each point.
out = p.sweep_path_aware(
    make_rc(),                               # initial builder
    params={"R_load": np.linspace(1, 20, 100).tolist()},
    kpi_fn=steady_state_vout,
    t_end=5e-3, dt=1e-6,
)
print(out.to_dataframe().head())

For Monte Carlo, swap sweep_path_aware → monte_carlo_path_aware(builder, distributions={"R_load": lambda r: r.uniform(1, 20)}, n_samples=1000, ...) and get the same ~3.4× speedup over the legacy rebuild-per-sample pattern.

What's new in v1.4.0

Two algorithmic contributions ship in one release — see CHANGELOG.md for the full breakdown.

In-house complex sparse LU

PulsimSparseLuSolver is now templated on Scalar. The new PulsimComplexSparseLuSolver = PulsimSparseLuSolverT<std::complex<Real>> drives the AC-sweep production path — Eigen::SparseLU<complex> is no longer compiled in. Backward-compat aliases keep the v1.3.0 real-scalar API source-identical:

using PulsimSparseLuSolver        = PulsimSparseLuSolverT<Real>;
using PulsimComplexSparseLuSolver = PulsimSparseLuSolverT<std::complex<Real>>;
using Matrix                      = MatrixT<Real>;
using Vector                      = VectorT<Real>;

Multi-bit + parametric path-based update

The v1.3.0 single-bit path-based partial refactor now generalises to three SMPS-relevant use cases:

The MAX_PATH_LENGTH_RATIO = 0.6 gate skips the path-based attempt when the union path covers > 60 % of $n$ (the path-walk would cost the same as a fresh factorise).

Python helpers

Drop-in replacements for the legacy sweep / MC APIs:

import pulsim as p
p.sweep_path_aware(builder, params={...}, kpi_fn=..., t_end=..., dt=...)
p.monte_carlo_path_aware(builder, distributions={...}, n_samples=..., ...)

Auto-fallback to the legacy code path when a parameter name isn't recognised (warns + delegates) — drop-in safe.

What's NOT in Pulsim (intentionally)

Many simulators inherit a sprawling dependency tree from their sparse-LU backend. Pulsim deliberately doesn't:

What IS used: Eigen 3.4+ (header-only, as a sparse matrix container) and pybind11 (for the Python binding). That's it.

Architecture

10 layers, bottom-up:

Layer 0:  Sparse LU + matrix containers      (in-house, real + complex)
Layer 1:  Topology graph + switch state mask
Layer 2:  Device models (R, L, C, MOSFET, IGBT, source, ...)
Layer 3:  Symbolic stamping helpers (Newton refresh)
Layer 4:  PWL state-space cache  ← refactor_parametric + solve_rank1
Layer 5:  Solver loop + event detection + run_transient
Layer 6:  CircuitBuilder (ergonomic API surface)
Layer 7:  YAML loader + reference circuits
Layer 8:  AC analysis (small-signal MNA Bode + FRA)
Layer 9:  Python facade (CircuitBuilder, simulate, sweep, plot)

See docs/how-pulsim-works/ for the chapter-by-chapter walkthrough (18 figures, 11 chapters, MNA basics through path-based partial refactor with full provenance).

Validation

# C++ kernel tests (Catch2 binaries per layer)
ctest --test-dir build --output-on-failure
# 498 / 498 tests pass on a fresh checkout

# Python runtime tests
PYTHONPATH=build/python pytest python/tests -v
# 6 / 6 path-aware sweep tests pass

# Benchmark suite (opt-in, not in default ctest)
./build/core/pulsim_benchmarks "[rank1][microbench]"
./build/core/pulsim_benchmarks "[multi_bit][microbench]"
./build/core/pulsim_benchmarks "[parametric][microbench]"
./build/core/pulsim_benchmarks "[ac_sweep][microbench]"

Reference CSV traces for the 10 converter showcases live under benchmarks/baselines/. A 1.0-native regression runner that consumes them is on the roadmap.

Roadmap

Citation

If you use Pulsim in academic work, please cite:

@software{pulsim,
  author  = {Gili, Luiz Carlos},
  title   = {Pulsim: A piecewise-linear state-space simulator for switched-mode power electronics},
  version = {1.4.0},
  url     = {https://github.com/lgili/Pulsim},
  year    = {2026},
}

Machine-readable CITATION.cff is in the repo root.

Contributing

PRs welcome. Workflow:

1. Open an issue describing the change (or pick one from the issue tracker).
2. For non-trivial work, draft an OpenSpec proposal under openspec/changes/<name>/ (see existing proposals under openspec/changes/archive/ for the format).
3. Implement + add tests under core/tests/ (C++) or python/tests/ (Python).
4. Ensure all 498 C++ tests + 6 Python tests pass and openspec validate --strict is green.
5. Open the PR; CI runs on every push.

See CONTRIBUTING.md for the full guide.

License

MIT © 2026 Luiz Carlos Gili. Free for academic + commercial use; please cite when used in academic work.

Documentation deployment

Docs are published by .github/workflows/docs.yml using MkDocs Material + mike:

• PR: strict docs build (no deploy)
• main: deploys to the dev channel
• vX.Y.Z tag: deploys release docs and updates latest

In repository settings, set Pages Source to GitHub Actions.

Live docs: https://lgili.github.io/Pulsim/