Metadata-Version: 2.4
Name: hermess
Version: 1.7.0
Summary: Hybrid EMT/RMS Modern Electric power System Simulator
Keywords: power systems,dynamic simulation,DAE,grid-forming converters,small-signal stability
Author: Milos Katanic, Maitraya Avadhut Desai
Author-email: Milos Katanic <mkatanic@ethz.ch>, Maitraya Avadhut Desai <mdesai@ethz.ch>
License-Expression: GPL-3.0-or-later
License-File: AUTHORS
License-File: LICENSE.txt
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.12.0
Requires-Dist: casadi>=3.6.5
Requires-Dist: matplotlib>=3.8.4
Requires-Dist: pandas>=2.2.2
Requires-Dist: pydantic>=2.10.3
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: pyside6>=6.6 ; extra == 'gui'
Requires-Dist: pyqtgraph>=0.13.7 ; extra == 'gui'
Maintainer: Maitraya Avadhut Desai
Maintainer-email: Maitraya Avadhut Desai <mdesai@ethz.ch>
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/maitrayadesai/hermess
Project-URL: Issues, https://github.com/maitrayadesai/hermess/issues
Project-URL: Documentation, https://maitrayadesai.github.io/hermess/
Provides-Extra: gui
Description-Content-Type: text/markdown

<div align="center">

# HERMESS

*Hybrid EMT/RMS Modern Electric power System Simulator*

[![docs](https://img.shields.io/badge/docs-hermess-215CAF)](https://maitrayadesai.github.io/hermess/)
[![tests](https://github.com/maitrayadesai/hermess/actions/workflows/ci.yml/badge.svg)](https://github.com/maitrayadesai/hermess/actions/workflows/ci.yml)
[![license: GPL v3+](https://img.shields.io/badge/license-GPL--3.0--or--later-B7352D)](LICENSE.txt)

**[Documentation](https://maitrayadesai.github.io/hermess/)**

</div>

---
## About

`hermess` is a dynamic simulation tool for power systems modeled by nonlinear Differential-Algebraic Equations (DAEs).
It integrates the dynamic evolution equations of the components together with the algebraic network equations to produce time-domain trajectories of the bus voltages and of every device's internal states.

This repository is the **simulation-only** build of [`PowerDynamicEstimator`](https://doi.org/10.5905/ethz-1007-842): the dynamic state estimation (DSE) layer has been removed, leaving a focused, self-contained power-system dynamic simulator. The Python package is still importable as `hermess`.

## Features

- Time-domain simulation of nonlinear DAE power system models
- Synchronous machine models (transient and subtransient, including Sauer–Pai formulations) with pluggable AVR, governor, PSS and (multi-mass) shaft strategies
- Grid-forming and grid-following converter (inverter) models with composable control strategies
- Static loads (constant power / impedance / ZIP) and infinite bus
- Quasi-static or fully dynamic (differential) network/line models
- Disturbances: bus/line faults, line switching, and load steps
- Configurable reference-frame handling (centre-of-inertia, single-machine, nominal, distributed)
- Small-signal eigenvalue / participation-factor analysis at the operating point
- Multiple integration schemes (`idas`, `cvodes`, `collocation`, `rk`)
- Supports 50 Hz and 60 Hz systems
- User-defined dynamic and static models can be integrated
- Available as a Python package: `hermess`

## Installation

### From PyPI

```bash
pip install hermess
```

With the optional desktop GUI:

```bash
pip install "hermess[gui]"
```

### From source (with `venv`), for development

1. **Clone the repository** and `cd` into it.
2. **Create and activate a virtual environment**:
```bash
python -m venv venv
```
```bash
source venv/bin/activate # On Windows: venv\Scripts\activate
```

3. **Install the package**:
```bash
pip install -e .
```
### From source (with `conda`)

1. **Clone the repository** and `cd` into it.

2. **Create the** `conda` **environment**:

```bash
conda env create -f environment.yaml
```
```bash
conda activate hermess
```

## Usage

### Running a simulation

The package installs a `hermess` command (equivalently `python -m hermess`):

```bash
hermess list                                # the ready-made systems
hermess run 3bus --t-end 5                  # simulate one and plot the trajectories
hermess run ieee39_conv --small-signal      # the shipped demo scenario
```

`hermess run` accepts `--t-end`, `--ts`, `--no-plot`, `--small-signal` and
`--system-root` for systems of your own; any other simulation setting is
reachable with `--set KEY=VALUE` (see `hermess run --help`).

From Python, to run a system without editing `config.py`:

```python
import hermess

hermess.list_systems()                        # the ready-made systems
dae = hermess.simulate("3bus", T_end=5.0)    # run one; returns the finished model
```

User-written models are selectable from a system file once registered, and the
same call takes devices and every pluggable strategy (AVR, governor, PSS, shaft,
converter filter / angle / voltage / inner / PLL):

```python
hermess.register(VSMAngle, "VSM")   # now:  angle = "VSM"  in sim_param.txt
hermess.registered("angle")         # what can be selected today
```

### Graphical interface

An optional desktop GUI covers the interactive workflow: select a shipped or
user-written system, adjust the simulation options, run with live progress, and
inspect the one-line diagram, the time-domain trajectories, the small-signal
modes and the initial power flow. Systems can also be built graphically, by
placing buses, lines and devices on the canvas with parameter forms generated
from the models; the result is saved as an ordinary system folder. Results
export as plot-ready CSV.

```bash
pip install "hermess[gui]"   # from source: pip install -e ".[gui]", or uv sync --extra gui
hermess-gui
```

![HERMESS GUI](docs/source/_static/gui_timedomain.png)

See the [GUI guide](https://maitrayadesai.github.io/hermess/gui.html) for a tour.

## Examples

You can check out the available examples in the `./examples` directory to get started, and the [documentation](https://maitrayadesai.github.io/hermess/) for the full usage guide and API reference.

## Important Notes

### Parameters

System dynamic and static parameters, including the topology, are specified in the `./hermess/systems` subfolder. You can define the loads, generators, converters, and their characteristics at specific nodes in the power system. The component parameters live in `sim_param.txt` and the disturbances in `sim_dist.txt` within each system folder.

### Simulation Settings

Adjust parameters related to the simulation (time step, end time, integration scheme, reference-frame mode, plotting, small-signal analysis, etc.) in the `./hermess/config.py` file.

### Limitations

- **Injector Limitation**: Currently, the platform supports only one injector per node due to initialization ambiguity. To handle multiple injectors per node, you can create a new node connected via a branch with very small impedance.

## Authors and copyright

© 2024-2026 ETH Zurich

Created by: Milos Katanic (original author of `PowerDynamicEstimator`) and Maitraya Avadhut Desai (simulation-only fork and maintainer).

HERMESS is a simulation-only fork of `PowerDynamicEstimator` (https://doi.org/10.5905/ethz-1007-842); the dynamic state estimation has been removed. See [`AUTHORS`](AUTHORS) and [`CONTRIBUTORS`](CONTRIBUTORS) for the full list of authors and contributors, and [`CONTRIBUTING.md`](CONTRIBUTING.md) if you would like to contribute.

## Acknowledgments

`PowerDynamicEstimator`, from which this build is derived, was developed at the [Power Systems Laboratory](https://psl.ee.ethz.ch/) at [ETH Zurich](https://ethz.ch/en.html), supported as part of [NCCR Automation](https://nccr-automation.ch/), a National Centre of Competence in Research funded by the Swiss National Science Foundation (grant number 51NF40_225155).

## Citing

If you use HERMESS in academic work, please cite the software release in the ETH Research Collection (see also [`CITATION.cff`](CITATION.cff)):

> M. A. Desai, M. Katanic, and G. Hug, "HERMESS: Hybrid EMT/RMS Modern Electric power System Simulator," version 1.0.0, ETH Zurich Research Collection, 2026, doi: [10.3929/ethz-c-000805609](https://doi.org/10.3929/ethz-c-000805609).

and the paper describing the underlying models:

> M. Katanic, J. Lygeros, and G. Hug, "Recursive dynamic state estimation for power systems with an incomplete nonlinear DAE model," *IET Generation, Transmission & Distribution*, vol. 18, no. 22, pp. 3657-3668, 2024, doi: [10.1049/gtd2.13308](https://doi.org/10.1049/gtd2.13308).

## License

This software is free software, released by ETH Zurich under the [GNU General Public License v3.0 or later (GPL-3.0-or-later)](https://www.gnu.org/licenses/gpl-3.0.html). See [`LICENSE.txt`](LICENSE.txt) for the full license text. It is distributed WITHOUT ANY WARRANTY; see the license for details.

`hermess/tests/references/` additionally contains third-party benchmark data
redistributed under its own license (BSD-3-Clause, from the
PowerSimulationsDynamics.jl project); the license text and provenance live
next to the data.
