Metadata-Version: 2.2
Name: pulsim
Version: 0.3.3
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 :: 3 - Alpha
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: grpc
Requires-Dist: grpcio>=1.50.0; extra == "grpc"
Requires-Dist: grpcio-tools>=1.50.0; extra == "grpc"
Requires-Dist: protobuf>=4.0.0; extra == "grpc"
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"
Provides-Extra: all
Requires-Dist: pulsim[data,dev,grpc,jupyter]; extra == "all"
Description-Content-Type: text/markdown

# PulsimCore

High-performance power-electronics simulation with a Python-first runtime.

## Supported Product Surface

Pulsim is now **Python-only** for user-facing usage:

- Supported: `import pulsim` APIs and YAML netlist workflows.
- Not supported as product surface: legacy CLI, gRPC server/client docs, JSON netlist loading.
- Core execution engine: unified `v1` kernel.

See:

- `docs/user-guide.md`
- `docs/migration-guide.md`
- `openspec/changes/refactor-python-only-v1-hardening/tasks.md`

## Quick Start

### 1) Build local Python bindings

```bash
cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DPULSIM_BUILD_PYTHON=ON
cmake --build build -j
```

### 2) Run with Python package from local build

```bash
PYTHONPATH=build/python python3 - <<'PY'
import pulsim as ps

parser_opts = ps.YamlParserOptions()
parser = ps.YamlParser(parser_opts)
circuit, sim_opts = parser.load("benchmarks/circuits/rc_step.yaml")

sim_opts.newton_options.num_nodes = int(circuit.num_nodes())
sim_opts.newton_options.num_branches = int(circuit.num_branches())

sim = ps.Simulator(circuit, sim_opts)
result = sim.run_transient(circuit.initial_state())
print("success:", result.success, "steps:", result.total_steps)
PY
```

## Benchmarks and Validation

```bash
# Benchmark matrix (Python runtime path)
PYTHONPATH=build/python python3 benchmarks/validation_matrix.py --output-dir benchmarks/matrix

# External parity (ngspice)
PYTHONPATH=build/python python3 benchmarks/benchmark_ngspice.py \
  --backend ngspice \
  --output-dir benchmarks/ngspice_out

# External parity (LTspice, explicit executable path required)
PYTHONPATH=build/python python3 benchmarks/benchmark_ngspice.py \
  --backend ltspice \
  --ltspice-exe "/Applications/LTspice.app/Contents/MacOS/LTspice" \
  --output-dir benchmarks/ltspice_out

# Tiered stress suite (A/B/C)
PYTHONPATH=build/python python3 benchmarks/stress_suite.py --output-dir benchmarks/stress_out
```

## Documentation Site

Build docs locally:

```bash
python3 -m pip install -r docs/requirements.txt
mkdocs build --strict
```

Serve locally:

```bash
mkdocs serve
```

Versioned deploy:

- Workflow: `.github/workflows/docs.yml`
- Trigger: only when pushing version tags `v*` (example: `v0.2.1`)
- Deploy mode: `mike` on `gh-pages` branch with version selector enabled
- Old versions remain published and selectable in the docs UI

## Notes

- YAML schema is `pulsim-v1`.
- Benchmark/parity artifacts are machine-readable (`results.json`, `parity_results.json`, `stress_results.json`).
- For migration details (removed APIs and timeline), see `docs/migration-guide.md`.
