Metadata-Version: 2.2
Name: pulsim
Version: 1.0.0
Summary: High-performance circuit simulator for power electronics
Keywords: circuit,simulation,spice,power electronics,eda
Author-Email: Pulsim Authors <pulsim@example.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Project-URL: Homepage, https://github.com/pulsim/pulsim-core
Project-URL: Documentation, https://pulsim.readthedocs.io
Project-URL: Repository, https://github.com/pulsim/pulsim-core
Project-URL: Issues, https://github.com/pulsim/pulsim-core/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.20
Provides-Extra: jupyter
Requires-Dist: ipywidgets>=8.0; extra == "jupyter"
Requires-Dist: matplotlib>=3.5; extra == "jupyter"
Requires-Dist: plotly>=5.0; extra == "jupyter"
Provides-Extra: data
Requires-Dist: pandas>=1.3; extra == "data"
Requires-Dist: xarray>=2022.0; extra == "data"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<9.6,>=9.5; extra == "docs"
Requires-Dist: mike<3.0,>=2.1; extra == "docs"
Requires-Dist: pymdown-extensions<11.0,>=10.9; extra == "docs"
Requires-Dist: mkdocstrings[python]>=1.0; extra == "docs"
Requires-Dist: griffe>=2.0; extra == "docs"
Provides-Extra: schematic
Requires-Dist: schemdraw<1.0,>=0.18; extra == "schematic"
Requires-Dist: networkx>=3.0; extra == "schematic"
Requires-Dist: cairosvg>=2.7; extra == "schematic"
Requires-Dist: anthropic>=0.34; extra == "schematic"
Provides-Extra: all
Requires-Dist: pulsim[data,dev,jupyter,schematic]; extra == "all"
Description-Content-Type: text/markdown

# Pulsim

Power-electronics circuit simulator — C++23 kernel with a Python-first API.

Pulsim is a header-only C++ simulation engine (`pulsim`) wrapped by a
flat Python module (`import pulsim`). It is built around a PWL
state-space cache (for fast switched-converter dynamics), a Newton
refinement on top of the cached linear factor (for non-linear devices),
and a built-in event detector for diode/MOSFET commutations.

If you have legacy code from the pre-1.0 cycle (the old
``Circuit`` / ``Simulator`` / ``YamlParser`` surface), see
[`docs/migration-guide.md`](docs/migration-guide.md) for the
device / analysis mapping table.

## Why Pulsim

- **PLECS-style PWL cache** — switched-converter steady-state in
  milliseconds instead of minutes.
- **Header-only C++23 kernel** — drop `pulsim/` into your own CMake
  target via `pulsim::core`; no static-library link step.
- **Python-first ergonomics** — `CircuitBuilder` API takes string node
  names and SI-unit parameters, returns the same `SimulationResult` whether
  you run a transient, an AC sweep, or a parameter sweep.
- **Mixed-domain composable control** — `MixedDomainBlockChain` runs
  PI/PID, comparators, rate limiters, op-amps, FOC blocks and thermal
  networks at kernel speed (no Python interpreter cost per step).
- **Frequency-domain analysis included** — small-signal MNA Bode +
  swept-sine FRA + closed-loop GM/PM measurement, all in the same surface.

## Quick start

```bash
git clone https://github.com/lgili/Pulsim.git
cd Pulsim

# Build kernel + Python extension
cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DPULSIM_BUILD_PYTHON=ON
cmake --build build -j

# Use Pulsim from the source tree (no `pip install` required)
export PYTHONPATH="$(pwd)/build/python:$PYTHONPATH"

# First run — open-loop buck
python3 examples/scripts/run_buck.py

# Print available components + helpers
python3 -c "import pulsim as p; p.catalog()"
```

### First simulation — 8 lines

```python
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.scope(b, res, signals=["vc"])           # one-liner plot
```

### What ships

- **Builder**: `CircuitBuilder` with 20+ helpers covering passives,
  sources, MOSFETs (SH1), IGBTs (Level 1), saturable inductors,
  transformers, op-amps, three-phase sources, …
- **YAML loader**: same surface, 13 ready-made example circuits in
  `examples/`.
- **Solver**: PWL state-space cache + Newton refresh + event detection +
  optional state-aware `step_observer(t, x)` callback for closed loops.
- **Control library**: `PIController`, `PIDController`, `Comparator`,
  `RateLimiter`, `FirstOrderLowPass`, …
- **AC analysis**: swept-sine Bode + auto-tuning (`tune_pi_from_bode`)
  with phase-margin / gain-margin extraction.
- **Frequency-response analyser (FRA)**: closed-loop / nonlinear-Bode
  via the time-domain swept-sine path.
- **Plot helpers**: `p.scope()`, `p.plot_bode()` — one-line waveform +
  Bode plots with sensible defaults.

### Where to learn more

- 6 narrative tutorials: [`docs/tutorials/`](docs/tutorials/)
- Mental model: [`docs/mental-model.md`](docs/mental-model.md)
- API reference: [`docs/api-reference.md`](docs/api-reference.md)
- Gotchas: [`docs/gotchas.md`](docs/gotchas.md)
- 20 runnable scripts: [`examples/scripts/`](examples/scripts/)

## Validation

```bash
# Python runtime tests
PYTHONPATH=build/python pytest python/tests -v

# C++ kernel tests (layer-by-layer Catch2 binaries)
ctest --test-dir build --output-on-failure
```

Reference CSV traces for the converter showcases live in
`benchmarks/baselines/`; a 1.0-native regression runner that
consumes them is not yet wired up.

## Documentation

- Documentation site: [https://lgili.github.io/Pulsim/](https://lgili.github.io/Pulsim/)
- Migration guide (from the pre-1.0 surface): [`docs/migration-guide.md`](docs/migration-guide.md)

## Docs deployment (GitHub Pages)

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

- PR: strict docs build
- `main`: deploy `dev` docs channel
- `vX.Y.Z` tag: deploy release docs and update `latest`

In repository settings, set **Pages Source** to **GitHub Actions**.
