Metadata-Version: 2.4
Name: peslite-core
Version: 0.5.0
Summary: Core runtime for the PESLite power electronics simulator.
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/lonaparte/PESLite
Project-URL: Documentation, https://github.com/lonaparte/PESLite/wiki
Project-URL: Repository, https://github.com/lonaparte/PESLite
Project-URL: Issues, https://github.com/lonaparte/PESLite/issues
Requires-Python: >=3.10.1
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: PyYAML>=6.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: matplotlib>=3.7.0; extra == "test"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "test"
Dynamic: license-file

# PESLite

**[Documentation](https://github.com/lonaparte/PESLite/wiki)**
· **[PyPI](https://pypi.org/project/peslite/)**
· **[Releases](https://github.com/lonaparte/PESLite/releases)**

PESLite is an open-source, lightweight, multirate, and extensible power electronics simulator in
Python. It provides time-domain simulation for power-electronic converters and converter-based 
systems—combining switching and averaged models, sampled control, event-driven operation,
and flexible multi-time-scale numerical integration via readable YAML files and a Python 
API—designed as a deterministic simulation backend for LLM reasoning and verification.

## Features

- AC and DC converter networks, including grid-connected and wireless-power-transfer systems.
- Configurable grid-following, grid-forming and DC converter control.
- Switching, PWM-period-averaged and continuously averaged models.
- Sampled control, sensing and converter protection.
- Fixed-step, adaptive and multirate integration with exact event boundaries.
- Simulation events and continuation from saved states.
- Streamed waveform output, optional plotting and energy accounting.
- Custom control loops, circuit elements, events and solvers through the Python extension API.
- Standalone C++17 export with no third-party C++ runtime dependencies.

## Install

```bash
pip install peslite
```

PESLite requires Python 3.10.1 or newer.

## Quick start

Run a bundled example:

```bash
peslite gfl-example
```

Run `case.pes` from the current directory:

```bash
peslite case.pes
```

Results are written to `output/<case-name>/` by default.

Override a parameter by dotted path when needed:

```bash
peslite case.pes --set simulation.t_end=1.0 --out output/test
```

Bridge and solver presets are available through three run modes:

```bash
peslite case.pes --switching
peslite case.pes --pwm-averaging
peslite case.pes --averaging
```

See [Bridge and PWM](https://github.com/lonaparte/PESLite/wiki/Bridge-and-PWM)
for bridge models, control periods and solver presets.

Use `peslite --help` for the full interface.

The same workflow is available from Python:

```python
import peslite

params = peslite.load("case.pes")
result = peslite.Simulation(params).run()

print(result.summary)
print(result.final_states())
```

## C++ export

Select the parameters that should remain variable in the compiled simulator, or use `common`:

```bash
peslite export case.pes common
c++ -O3 -DNDEBUG -std=c++17 export/case/peslite.cpp -o export/case/peslite
```

The generated executable uses the same parameter-override and output conventions as PESLite and
writes the same result structure. See the [C++ Export guide](https://github.com/lonaparte/PESLite/wiki/Cpp-Export)
for compilation, runtime configuration and current backend limits.

## Documentation

- [Documentation](https://github.com/lonaparte/PESLite/wiki)
- [Getting Started](https://github.com/lonaparte/PESLite/wiki/Getting-Started)
- [Examples](https://github.com/lonaparte/PESLite/wiki/Examples)
- [CLI Reference](https://github.com/lonaparte/PESLite/wiki/CLI-Reference)

## Development

[Fork PESLite](https://github.com/lonaparte/PESLite/fork) on GitHub, then clone your fork and install
it with the development dependencies:

```bash
git clone https://github.com/<your-username>/PESLite.git
cd PESLite
python -m pip install -e ".[test]"
```

Run the fast test suite from the repository root:

```bash
python -m pytest
```

Use `python -m pytest --run-full` to include compiler, external-reference and long numerical tests.

## License

GNU Affero General Public License v3.0 only (`AGPL-3.0-only`). See `LICENSE`.
