Metadata-Version: 2.1
Name: ieeh-power-system-data-model
Version: 2.1.1
Summary: A data model for describing power systems
Author-Email: Sasan Jacob Rasti <sasan_jacob.rasti@tu-dresden.de>, Sebastian Krahmer <sebastian.krahmer@tu-dresden.de>, Laura Fiedler <laura.fiedler1@tu-dresden.de>, Maximilian Schmidt <maximilian.schmidt@tu-dresden.de>
License: BSD 3-Clause License
        
        Copyright (c) 2022-2023, Institute of Electrical Power Systems and High Voltage Engineering - TU Dresden
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Source, https://github.com/ieeh-tu-dresden/power-system-data-model
Requires-Python: >=3.10
Requires-Dist: loguru
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# IEEH Power System Data Model

[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

A data model for the description of electrical power systems.

- [IEEH Power System Data Model](#ieeh-power-system-data-model)
  - [ Field of Application](#-field-of-application)
  - [ General Remarks](#-general-remarks)
  - [ Installation](#-installation)
  - [ Development](#-development)
  - [ Attribution](#-attribution)

## <div id="application" /> Field of Application

This data model is intended to describe electrical power systems. It provides a hierarchical structure/schema to describe unique entity relations as well as parameter sets.

The data model is structured as the following schema:

### Grid Topology
This is the base topology containing all elements of the exported grid:
- Branches (symmetrical: overhead lines, cables, fuses from type "branch")
- Nodes
- Transformers (symmetrical: 2- or 3-winding)
- External grids
- Loads (consumer, producer, grid assets, fuses from type)
  ![topology relationship diagram](./docs/topology.png)

### Topology Case
This holds information about disabled elements to represent a specific operational case based on the base topology.
  ![topology case relationship diagram](./docs/topology_case.png)

### Steadystate Case
This holds information for a specific operational case such as:
- power draw/infeed of load
- tap posistion of transformer
- operating point of external grid
  ![steadystate case relationship diagram](./docs/steady_state_case.png)

## <div id="remarks" /> General Remarks

Please find below some important general remarks and assumptions to consider for consistent usage across different applications:
- The passive sign convention should be used for all types of loads (consumer as well as producer).
- Numeric values should be set using the SI unit convention.
- Topology
  - Only **symmetrical** grid assets, e.g. transformer or line, are supported.
  - The `Rated Power` should always be defined positive (absolute value).
- The interaction between load models and controllers are depicted in the following schematic:
  ![active/reactive power schematics](./docs/power_schematics.png)

## <div id="installation" /> Installation

Just install via pip:

```bash
pip install ieeh-power-system-data-model
```

## <div id="development" /> Development

Install [pdm](https://github.com/pdm-project/pdm)

Windows:

```bash
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py -UseBasicParsing).Content | python -
```

Linux/Mac:

```bash
curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 -
```

Or using pipx or pip:
```bash
pipx install pdm
```
```bash
pip install --user pdm
```

Clone `power-system-data-model`

```bash
git@github.com:ieeh-tu-dresden/power-system-data-model.git
```

```bash
cd power-system-data-model
```

Install `power-system-data-model` as a production tool

```bash
pdm install --prod
```

Install `power-system-data-model` in development mode

```bash
pdm install
```

For development in [Visual Studio Code](https://github.com/microsoft/vscode), all configurations are already provided:

- [ruff](https://github.com/astral-sh/ruff)
- [black](https://github.com/psf/black)
- [mypy](https://github.com/python/mypy)

## <div id="attribution" /> Attribution

Please provide a link to this repository:

<https://github.com/ieeh-tu-dresden/power-system-data-model>

Please cite as:

Institute of Electrical Power Systems and High Voltage Engineering - TU Dresden, _Power System Data Model - A data model for the description of electrical power systems_, Zenodo, 2023. <https://doi.org/10.5281/zenodo.8087079>.

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8087079.svg)](https://doi.org/10.5281/zenodo.8087079)
