Metadata-Version: 2.2
Name: pulsim
Version: 0.7.6
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: 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: all
Requires-Dist: pulsim[data,dev,jupyter]; extra == "all"
Description-Content-Type: text/markdown

# PulsimCore

High-performance backend for power electronics simulation.

PulsimCore combines a C++ simulation kernel with a Python-first runtime so you can build, validate, and ship converter simulations with reproducible YAML netlists.

## Why PulsimCore

- Python-native workflow: `import pulsim`
- Versioned YAML netlist schema (`pulsim-v1`)
- Robust transient flow for switched converters (fallback-aware)
- Mixed-domain support (control, events, thermal coupling)
- Built-in benchmark, parity, and stress tooling for CI gates

## Quick Start

### Build local bindings

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

### Run a first simulation

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

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

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

sim = ps.Simulator(circuit, options)
result = sim.run_transient(circuit.initial_state())

print("success:", result.success, "steps:", result.total_steps)
PY
```

## Documentation

- Documentation site: [https://lgili.github.io/Pulsim/](https://lgili.github.io/Pulsim/)
- Getting started guide: [`docs/getting-started.md`](docs/getting-started.md)
- Netlist format (including `simulation.control`): [`docs/netlist-format.md`](docs/netlist-format.md)
- Frontend control/signal contract: [`docs/frontend-control-signals.md`](docs/frontend-control-signals.md)
- Electrothermal workflow: [`docs/electrothermal-workflow.md`](docs/electrothermal-workflow.md)
- Backend C++ contributor guide: [`docs/backend-cpp-contributor-guide.md`](docs/backend-cpp-contributor-guide.md)
- Configuration guide (solver/control/thermal): [`docs/configuration.md`](docs/configuration.md)
- API reference: [`docs/api-reference.md`](docs/api-reference.md)
- Benchmarks and parity: [`docs/benchmarks-and-parity.md`](docs/benchmarks-and-parity.md)
- Contribution guidelines: [`CONTRIBUTING.md`](CONTRIBUTING.md)

## Closed-Loop + Thermal Quickstart

Use the backend-ready closed-loop buck example:

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

parser = ps.YamlParser(ps.YamlParserOptions())
circuit, options = parser.load("examples/09_buck_closed_loop_loss_thermal_validation_backend.yaml")
options.newton_options.num_nodes = int(circuit.num_nodes())
options.newton_options.num_branches = int(circuit.num_branches())

sim = ps.Simulator(circuit, options)
result = sim.run_transient(circuit.initial_state())

print("ok:", result.success)
print("max_temp:", result.thermal_summary.max_temperature)
print("components:", len(result.component_electrothermal))
print("thermal_trace_keys:", [k for k in result.virtual_channels if k.startswith("T(")])
PY
```

Generate a plot with electrical/control channels plus switch thermal trace (`T(M1)`):

```bash
PYTHONPATH=build/python python3 examples/plot_buck_closed_loop_thermal_backend.py
```

## Validation and Performance Workflows

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

# C++ kernel tests
ctest --test-dir build --output-on-failure

# Benchmark suite
PYTHONPATH=build/python python3 benchmarks/benchmark_runner.py --output-dir benchmarks/out
```

## Product Surface

Supported user-facing surface:

- Python runtime (`import pulsim`)
- YAML netlists (`schema: pulsim-v1`)

Legacy CLI/gRPC/JSON-first paths are not the canonical integration target.

## 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**.
