mosaik-pypower
==============
This package contains the adapter to connect *PYPOWER* to *mosaik*.
.. contents:: Table of Contents
:depth: 3
Installation and starting
-------------------------
You can install mosaik-pypower via pip:
.. code-block:: bash
$ pip install mosaik-pypower
You can run the tests with:
.. code-block:: bash
$ git clone https://gitlab.com/mosaik/mosaik-pypower.git
$ cd mosaik-pypower
$ pip install -r requirements.txt
$ pytest # Run tests on current Python
$ tox # Run tests on all supported Python versions
You can either start mosaik-pypower as normal process or use it as a library.
If you run it via the command line, you need to pass the address that mosaik
is listening on:
.. code-block:: bash
$ mosaik-pypower HOST:PORT
You can run ``mosaik-pypower --help`` to get more help.
In order to use it as a library, you have to import the module
``mosaik_pypower.mosaik`` and instantiate the class ``PyPower``:
.. code-block:: python
>>> import mosaik_pypower.mosaik
>>> pp = mosaik_pyower.mosaik.PyPower()
Input file format
-----------------
Mosaik-pypower uses, like PYPOWER, the bus-branch model to represent power
grids.
This model is fairly simple: You have a number of buses / nodes that are
connected via branches / lines. Transformers are just a special kind of branch.
Buses are divided into three sub-types: the reference bus (also known as swing
or slack bus), PQ buses and PU buses.
For PQ buses, the (re)active power *P* and *Q* are given, PYPOWER will
calculate the voltage magnitude and angle for these nodes. PU buses provide
active power and a constant voltage, thus PYPOWER computes the reactive power
for these buses. Mosaik-pypower currently *only supports PQ buses*, because
they are more general and if you model your power grid for mosaik, you do not
know in advance what kind of unit (consumer, producer, …) will be connected to
a bus.
Every grid needs to have *exactly one* reference bus. It has a constant voltage
magnitude and angle (usually 1 p.u. and 0°). PYPOWER computes the residual
(re)active power for that node. Usually it is placed on the primary or
secondary side of the grid's transformer station (or where it would be)::
With transformer Without transformer
REF REF
| |
8 |
| PQ0
PQ0 / \
/ \ | |
| | PQ1 PQ2
PQ1 PQ2
PYPOWER's original input format is relatively hard to read/write and also
contains more information than we need to model power grids for the use with
mosaik. For example, it contains loads and feed-in for each bus which we don't
need here because mosaik will provide it from other simulators.
Thus, mosaik-pypower provides simpler input file formats which it will convert
to the format used by PYPOWER. Currently, it can read Excel (xlsx) and JSON
files (in an old an a new variant).
The Excel and new JSON formats are structured in a similar way. The difference
of the old JSON format are larger. You can find example files in our `source
code repository`__. Below, you’ll find a detailed description of them.
__ https://gitlab.com/mosaik/mosaik-pypower/-/tree/master/tests/data/
Excel
^^^^^
Excel files need to have the suffix ``*.xlsx`` and need to provide at least to
sheets: one for buses and one for branches. They should usually be named
*Nodes* and *Lines*, but you can also use any name you want (more on that
later).
In every sheet, the first row is reserved for headings. From row two, you list
the buses and branches (one per row). If the first cell of a row starts with
a ``#`` this row is treated as a comment.
Bus sheet
"""""""""
The bus sheet contains at least three columns (you can use the other columns
for comments):
1. The bus name (string)
2. The bus type (either ``REF`` or ``PQ``)
3. The bus' base voltage (integer in kV line-to-line, e.g. ``400`` for
a European LV node).
Example::
Node name Node type Base voltage [kV] Notes
Grid REF 110 Slack bus
# This is a comment
Bus0 PQ 20
Bus1 PQ 20
Bus2 PQ 20
Bus3 PQ 20
There must be *exactly one* REF bus in the list and it must be first in the
list.
Branch sheet
""""""""""""
The branch sheet contains at least seven columns (again, you can use additional
columns for notes):
1. The branch name (string)
2. One end of the branch (a valid bus name)
3. The other end of the branch (a valid bus name)
4. The transformer or line type (see `here`__ for a list of built-in types. You
can also `add your own`__)
5. The branch length (float in km)
6. A flag indicating whether the branch is online / active (``1``) or offline
/ inactive (``0``)
7. The default tap turn for a transformer (usually ``0``)
__ https://gitlab.com/mosaik/mosaik-pypower/-/tree/master/mosaik_pypower/resource_db.py
__ resource-db_
Example::
Name From To Type Length [km] Online Tap
# Transformer
Trafo1 Grid Bus0 TRAFO_40 1.0 1 0
# Lines
B_0 Bus0 Bus1 NA2XS2Y_185 5.0 1
B_1 Bus0 Bus2 NA2XS2Y_185 3.0 1
B_2 Bus1 Bus3 NA2XS2Y_185 2.0 1
B_3 Bus2 Bus3 NA2XS2Y_185 0.3 1
.. _resource-db:
Additional branch and transformer types
"""""""""""""""""""""""""""""""""""""""
You can add more line and transformer types via two additional sheets, *Line
types* and *Transformer types* (you can give them other names if you want to).
The headings should be pretty self-explanatory:
Example line types::
Type name R' [Ω/km] X' [Ω/km] C' [nF/km] I_max [A]
SPAM_200 0.1337 0.0815 0 404
Example transformer types::
Transformer Type S_r [MVA] I_max_prim [A] I_max_sec [A] P_loss [kW] R [Ω] X [Ω] taps
TRAFO_23 23 100 800 100 0.0123 1.234 {-1: 0.9, 0: 1.0, 1: 1.1}
JSON (new format)
^^^^^^^^^^^^^^^^^
The new JSON format (use ``*.json`` as a suffix) is very similar to the Excel
format, but instead of separate sheets, its just different entries in a JSON
object. There is one entry for the buses, one for branches and one for
transformers. Each entry contains is a list of lists which are structured
like the columns in the Excel format:
.. code-block:: json
{
"bus": [
["Grid", "REF", 110.0],
["Bus0", "PQ", 20.0],
["Bus1", "PQ", 20.0],
["Bus2", "PQ", 20.0],
["Bus3", "PQ", 20.0]
],
"trafo": [
["Trafo1", "Grid", "Bus0", "TRAFO_40", true, 0]
],
"branch": [
["B_0", "Bus0", "Bus1", "NA2XS2Y_185", 5.0, true],
["B_1", "Bus0", "Bus2", "NA2XS2Y_185", 3.0, true],
["B_2", "Bus1", "Bus3", "NA2XS2Y_185", 2.0, true],
["B_3", "Bus2", "Bus3", "NA2XS2Y_185", 0.3, true]
]
}
There must be *exactly one* REF bus in the list and it must also be the first
entry of the list.
If you want to specify additional branch or transformer types, you can add
``branch_types`` or ``trafo_types`` to the object. They are also structured
similarly to the Excel file:
.. code-block:: json
{
"bus": [
["Grid", "REF", 110.0],
["Bus0", "PQ", 20.0],
["Bus1", "PQ", 20.0],
],
"trafo": [
["Trafo1", "Grid", "Bus0", "TRAFO_23", true, 0]
],
"branch": [
["B_0", "Bus0", "Bus1", "SPAM_200", 5.0, true]
],
"branch_types": {
"SPAM_200": [0.1337, 0.0815, 0, 404]
},
"trafo_types": {
"TRAFO_23": [23, 100, 800, 100, 0.0123, 1.234, {"-1": 0.9, "0": 1, "1": 1.1}]
}
}
JSON (old format)
^^^^^^^^^^^^^^^^^
The old JSON format (also with the ``*.json`` suffix) differs from the new
format by explicitly listing the branch and transformer parameters for each
branch and transformer. It must also have a ``base_mva`` entry which is used
for the p.u. conversion. It can usually just be set to ``1``:
::
{
"base_mva": <global_base_mva>,
"bus": [
["<bus_id>", "REF|PQ", <base_kv>],
...
],
"trafo": [
["<trafo_id>", "<from_bus_id>", "<to_bus_id>", <Sr_MVA>, <v1_%>,
<P1_MW>, <Imax_p_A>, <Imax_s_A>],
...
],
"branch": [
["<branch_id>", "<from_bus_id>", "<to_bus_id>", <length_km>,
<R'_ohm/km>, <X'_ohm/km>, <C'_nF/km>, <I_max_A>],
...
]
}
Again, there may only be one *REF* bus and it must be the first in the list
Usage in mosaik
---------------
As pointed out above, you can run mosaik-pypower in-process or as
a sub-process. Every instance of mosaik-pypower can handle multiple power grids
at once. This is very handy for scenarios with a lot of separate grids. You can
start one instance of mosaik-pypower for every CPU core of your machine and
distribute all grids over these instance. More instances would mean more
overhead, less instances would mean less parallelization.
Instantiation and initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is an example *sim config* for mosaik:
.. code-block:: python
sim_config = {
'PyPower-inproc': {
'python': 'mosaik_pypower.mosaik:PyPower',
},
'PyPower-subproc': {
'cmd': 'mosaik-pypower %(addr)s',
},
}
When you create an instance of mosaik-pypower, you can pass three parameters:
- *step_size* is an integer in seconds (of simulation time) and defines how
often a power flow analysis should be performend.
- *pos_load* is an optional boolean that lets you specify whether the active
power for loads is a positive or a negative number.
The default (``True``) is to use positive numbers for loads and negative
numbers for feed-in of active power.
If you want to use negative values for loads and positive for feed-in, set
this flag to ``False``.
- *converge_exception* is an optional boolean that allows to set the behavior
in case that the power flow does not converge.
As default (``False``) all output attributes are set to NaN and the
simulation continues. If set to ``True``, an exception is thrown and the
simulation stops.
Examples:
.. code-block:: python
# Power-flow every minute:
pp_a = world.start('PyPower', step_size=60)
# Power-flow every 15 minutes, negative values for active power of loads:
pp_b = world.start('PyPower', step_size=300, pos_loads=False)
Models
^^^^^^
Mosaik-pypower provides the following models / entity types:
**Grid**
**public:** True
**parameters:** *gridfile* [, *sheetnames*]
This model is used to instantiate a power-grid within mosaik-pypower from the
*gridfile* provided. The *Grid* instance will have child entities for every
element in that grid (buses, branches, …). You can access these entities
via the ``children`` attribute of the *Grid* entity. These entities also
contain information about how they are related to each other. This allows
mosaik to determine the grid topology. You can query it via
``world.entity_graph[<full_entity_id>``.
If you use an Excel file and deviate from the default sheet names, you can
optionally pass a *sheetnames* argument which is a dict with the sheet names
to use.
**RefBus** / **PQBus**
**public:** False
**attributes:** *P*, *Q*, *Vl*, *Vm*, *Va*
Every *Grid* will contain exactly one *RefBus* entity and at least one
*PQBus* entity.
*P* and *Q* are active / reactive power in [W] / [VAr].
*Vl* is the nominal voltage in [V] as defined in the grid file. *Vm* is the
current voltage magnitude in [V] and my deviate from *Vl*. *Va* is the voltage
angle in [°] (degree).
**Branch**
**public:** False
**attributes:** *P_from*, *Q_from*, *P_to*, *Q_to*, *I_real*, *I_imag*,
*S_max*, *I_max*, *length*, *R_per_km*, *X_per_km*, *onine*
A grid consists of an arbitrary amount of branches connecting the *PQBus*
entities with each other.
The attributes *(P|Q)_(from|to)* denote the (re)active power on both ends of
the branch in [W] or [VAr]. *I_real* and *I_imag* are the complex current in
[A] flowing through the branch.
*S_max* and *I_max* denote the maximum acceptable apparent power (in [VA])
and current (in [A]) for that branch.
*lengh*, *R_per_km*, *X_per_km*, *C_per_km* and *online* are the respective
values for the branch from the input file.
**Transformer**
**public:** False
**attributes:** *P_from*, *Q_from*, *P_to*, *Q_to*, *S_r*, *I_max_p*,
*I_max_s*, *P_loss*, *U_p*, *U_s*, *taps*, *tap_turn*.
A grid may have an arbitrary number of transformers (zero, one or more).
Since it is just a special kind of *Branch* it shares many attributes with
it.
The attributes *(P|Q)_(from|to)* denote the (re)active power on both ends of
the branch in [W] or [VAr]. *I_real* and *I_imag* are the complex current in
[A] flowing through the branch.
*S_r* is the rated apparent power (in [VA]) of the transformer. *I_max_p* and
*I_max_s* are the maximum currents in [A] for the primary and secondary side
of the transformer. *P_loss* is the transformer's nominal power loss in [W].
*U_p* and *U_s* are the nominal primary and secondary line-to-line voltages
in [V].
*taps* is a dictionary of the available tap turns of the transformer.
*tap_turn* is the currently active tap turn.
Examples for model instantiation and connection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here are some examples on how to instantiate a power grid and work with the
entities that you get in return.
Basic examples:
.. code-block:: python
pp = world.start('PyPower', step_size=60)
# Create a grid from a JSON file:
grid = pp.Grid(gridfile='path/to/grid.json')
# Get a list of RefBus, PQBus, Transformer and Branch entities:
grid = grid.children
# Create some PV entities and randomly connect them to a PQBus:
pvs = make_pvs(...) # Returns a list of PV entities
pq_buses = [e for e in grid if e.type == 'PQBus']
mosaik.util.connect_randomly(world, pvs, pq_buses, ('P_out', 'P'), ('Q_out', 'Q'))
Advanced stuff:
.. code-block:: python
pp = world.start('PyPower', step_size=60)
# Create a grid from an Excel file and overwrite default sheet names.
# Directly grab the list of child entities
grid = pp.Grid(gridfile='path/to/grid.xlsx', sheetnames={
'bus': 'Nodes',
'branch': 'Lines',
'branch_types': 'Line types',
'trafo_types': 'Transformer types',
}).children
# Get the RefBus
ref_bus = [e for e in grid if e.type == 'RefBus']
# Get all nodes starting with "ConnectionPoint_". Note that every entity ID
# is prefixed with a grid index (e.g., "1-"). We can use regular expressions
# to handle this:
import re
regex_cn = re.compile(r'\d+-ConnectionPoint_.*')
conpoints = [e for e in grid if regex_cn.match(e.eid)]
# Create a dictionary mapping node names to the respective entities. Again,
# we have to strip the grid index:
conpoints = {e.eid.split('-', 1)[1]: n
for n in grid if regex_cn.match(n.eid)}
# Connected loads to defined connection points:
houses = create_houses(...) # Returns a list of (house, node-id) tuples
for house, node_id in houses:
mosaik.connect(house, conpoints[house_id], ('P_out', 'P'), ('Q_out', 'Q'))
# Get "secondary side" buses of all transformers
trafo_nodes = []
# 1. Get all transformers:
trafos = [e for e in grid if e.type == 'Transformer']
# 2. Group PQBuses by full ID for easier access:
nodes = {e.full_id: e for e in grid if e.type == 'PQBus'}
# 3. Iterate transformer relations (assuming that they are connected to the
# RefBus on their primary side):
for trafo in trafos:
rels = world.entity_graph[trafo.full_id]
assert len(rels) == 2
for rel in rels:
if rel in nodes:
trafo_nodes.append(nodes[rel])
break
else:
raise ValueError('No PQBus found at trafo.')
Getting help
------------
If you need, please visit either the `mosaik-users mailing list`__ (or the
`PYPOWER Google group`__ if your issue is very PYPOWER specific).
__ https://mosaik.offis.de/mailinglist
__ https://groups.google.com/forum/#!forum/pypower
Changelog
=========
0.8.2 – 2022-09-27
------------------
- [BUGFIX] Added restriction to numpy <1.23, because newer versions are incompatible with current PYPOWER version
0.8.1 – 2022-03-23
------------------
- [BUGFIX] Removed limitation for scypi and increased python compatibility to 3.10.
0.8.0 – 2021-05-21
------------------
- [CHANGE] Updated to mosaik-api 3.0.
- [NEW] converge_exception can be set to throw an exception if load flow
doesn't converge
0.7.3 - 2021-03-04
------------------
- [BUGFIX] Require version <1.6.0 of scipy and <2.0 of xlrd, because newer versions are incompatible
- [BUGFIX] Set I_real and I_imag in case of failure of power flow
0.7.2 – 2017-07-19
------------------
- [BUGFIX] --> Issue #5: https://bitbucket.org/mosaik/mosaik-pypower/issues/5
- [BUGFIX] --> Issue #6: https://bitbucket.org/mosaik/mosaik-pypower/issues/6
- [LIB-UPDATE] --> scipy update from version 0.17.0 to version 0.19.1
0.7.1 – 2016-02-15
------------------
- [FIX] Fixed a typo in model.py. "Tap" can now be read from Excel files.
0.7 – 2014-10-28
----------------
- [NEW] Added ability to extend the built-in branch/transformer database
(`issue #2`_).
- [NEW] Wrote a lot new documentation (`issue #3`_)
.. _`issue #2`: https://bitbucket.org/mosaik/mosaik-pypower/issue/2/
.. _`issue #3`: https://bitbucket.org/mosaik/mosaik-pypower/issue/3/
0.6.3 – 2014-09-22
------------------
- [CHANGE] Updated to mosaik-api 2.0.
0.6.2 – 2014-07-31
------------------
- [CHANGE] Cache xlsx files to improve performance
- [CHANGE] Updated to mosaik-api 2.0a4.
0.6.1 – 2014-06-30
------------------
- [NEW] Added *I_max_p* [A] and *I_max_s* [A] to the transformer data.
0.6 – 2014-06-26
----------------
- [NEW] Can import grids from Excel files (xlsx)
- [NEW] New import format for JSON files (the old format is still supported)
- [CHANGE] Massive internal refactoring.
- [CHANGE] Updated to mosaik-api 2.0a3.
0.5 – 2014-03-26
----------------
- Initial release
Authors
=======
The mosaik-pypower is developed by Stefan Scherfke.
André El-Ama joined the team in July 2017.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/mosaik/components/energy/mosaik-pypower",
"name": "mosaik-pypower",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Stefan Scherfke",
"author_email": "mosaik@offis.de",
"download_url": "https://files.pythonhosted.org/packages/9b/25/9b70cd9c9ba94ca32455ce3d15a8bff98d966594abc890dff85aaed00d78/mosaik-pypower-0.8.3.tar.gz",
"platform": null,
"description": "mosaik-pypower\n==============\n\nThis package contains the adapter to connect *PYPOWER* to *mosaik*.\n\n.. contents:: Table of Contents\n :depth: 3\n\n\nInstallation and starting\n-------------------------\n\nYou can install mosaik-pypower via pip:\n\n.. code-block:: bash\n\n $ pip install mosaik-pypower\n\nYou can run the tests with:\n\n.. code-block:: bash\n\n $ git clone https://gitlab.com/mosaik/mosaik-pypower.git\n $ cd mosaik-pypower\n $ pip install -r requirements.txt\n $ pytest # Run tests on current Python\n $ tox # Run tests on all supported Python versions\n\nYou can either start mosaik-pypower as normal process or use it as a library.\nIf you run it via the command line, you need to pass the address that mosaik\nis listening on:\n\n.. code-block:: bash\n\n $ mosaik-pypower HOST:PORT\n\nYou can run ``mosaik-pypower --help`` to get more help.\n\nIn order to use it as a library, you have to import the module\n``mosaik_pypower.mosaik`` and instantiate the class ``PyPower``:\n\n.. code-block:: python\n\n >>> import mosaik_pypower.mosaik\n >>> pp = mosaik_pyower.mosaik.PyPower()\n\n\nInput file format\n-----------------\n\nMosaik-pypower uses, like PYPOWER, the bus-branch model to represent power\ngrids.\n\nThis model is fairly simple: You have a number of buses / nodes that are\nconnected via branches / lines. Transformers are just a special kind of branch.\nBuses are divided into three sub-types: the reference bus (also known as swing\nor slack bus), PQ buses and PU buses.\n\nFor PQ buses, the (re)active power *P* and *Q* are given, PYPOWER will\ncalculate the voltage magnitude and angle for these nodes. PU buses provide\nactive power and a constant voltage, thus PYPOWER computes the reactive power\nfor these buses. Mosaik-pypower currently *only supports PQ buses*, because\nthey are more general and if you model your power grid for mosaik, you do not\nknow in advance what kind of unit (consumer, producer, \u2026) will be connected to\na bus.\n\nEvery grid needs to have *exactly one* reference bus. It has a constant voltage\nmagnitude and angle (usually 1 p.u. and 0\u00b0). PYPOWER computes the residual\n(re)active power for that node. Usually it is placed on the primary or\nsecondary side of the grid's transformer station (or where it would be)::\n\n With transformer Without transformer\n\n REF REF\n | |\n 8 |\n | PQ0\n PQ0 / \\\n / \\ | |\n | | PQ1 PQ2\n PQ1 PQ2\n\nPYPOWER's original input format is relatively hard to read/write and also\ncontains more information than we need to model power grids for the use with\nmosaik. For example, it contains loads and feed-in for each bus which we don't\nneed here because mosaik will provide it from other simulators.\n\nThus, mosaik-pypower provides simpler input file formats which it will convert\nto the format used by PYPOWER. Currently, it can read Excel (xlsx) and JSON\nfiles (in an old an a new variant).\n\nThe Excel and new JSON formats are structured in a similar way. The difference\nof the old JSON format are larger. You can find example files in our `source\ncode repository`__. Below, you\u2019ll find a detailed description of them.\n\n__ https://gitlab.com/mosaik/mosaik-pypower/-/tree/master/tests/data/\n\n\nExcel\n^^^^^\n\nExcel files need to have the suffix ``*.xlsx`` and need to provide at least to\nsheets: one for buses and one for branches. They should usually be named\n*Nodes* and *Lines*, but you can also use any name you want (more on that\nlater).\n\nIn every sheet, the first row is reserved for headings. From row two, you list\nthe buses and branches (one per row). If the first cell of a row starts with\na ``#`` this row is treated as a comment.\n\nBus sheet\n\"\"\"\"\"\"\"\"\"\n\nThe bus sheet contains at least three columns (you can use the other columns\nfor comments):\n\n1. The bus name (string)\n2. The bus type (either ``REF`` or ``PQ``)\n3. The bus' base voltage (integer in kV line-to-line, e.g. ``400`` for\n a European LV node).\n\nExample::\n\n Node name Node type Base voltage [kV] Notes\n Grid REF 110 Slack bus\n # This is a comment\n Bus0 PQ 20\n Bus1 PQ 20\n Bus2 PQ 20\n Bus3 PQ 20\n\nThere must be *exactly one* REF bus in the list and it must be first in the\nlist.\n\n\nBranch sheet\n\"\"\"\"\"\"\"\"\"\"\"\"\n\nThe branch sheet contains at least seven columns (again, you can use additional\ncolumns for notes):\n\n1. The branch name (string)\n2. One end of the branch (a valid bus name)\n3. The other end of the branch (a valid bus name)\n4. The transformer or line type (see `here`__ for a list of built-in types. You\n can also `add your own`__)\n5. The branch length (float in km)\n6. A flag indicating whether the branch is online / active (``1``) or offline\n / inactive (``0``)\n7. The default tap turn for a transformer (usually ``0``)\n\n__ https://gitlab.com/mosaik/mosaik-pypower/-/tree/master/mosaik_pypower/resource_db.py\n__ resource-db_\n\nExample::\n\n Name From To Type Length [km] Online Tap\n # Transformer\n Trafo1 Grid Bus0 TRAFO_40 1.0 1 0\n # Lines\n B_0 Bus0 Bus1 NA2XS2Y_185 5.0 1\n B_1 Bus0 Bus2 NA2XS2Y_185 3.0 1\n B_2 Bus1 Bus3 NA2XS2Y_185 2.0 1\n B_3 Bus2 Bus3 NA2XS2Y_185 0.3 1\n\n\n.. _resource-db:\n\nAdditional branch and transformer types\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nYou can add more line and transformer types via two additional sheets, *Line\ntypes* and *Transformer types* (you can give them other names if you want to).\n\nThe headings should be pretty self-explanatory:\n\nExample line types::\n\n Type name R' [\u03a9/km] X' [\u03a9/km] C' [nF/km] I_max [A]\n SPAM_200 0.1337 0.0815 0 404\n\nExample transformer types::\n\n Transformer Type S_r [MVA] I_max_prim [A] I_max_sec [A] P_loss [kW] R [\u03a9] X [\u03a9] taps\n TRAFO_23 23 100 800 100 0.0123 1.234 {-1: 0.9, 0: 1.0, 1: 1.1}\n\n\nJSON (new format)\n^^^^^^^^^^^^^^^^^\n\nThe new JSON format (use ``*.json`` as a suffix) is very similar to the Excel\nformat, but instead of separate sheets, its just different entries in a JSON\nobject. There is one entry for the buses, one for branches and one for\ntransformers. Each entry contains is a list of lists which are structured\nlike the columns in the Excel format:\n\n.. code-block:: json\n\n {\n \"bus\": [\n [\"Grid\", \"REF\", 110.0],\n [\"Bus0\", \"PQ\", 20.0],\n [\"Bus1\", \"PQ\", 20.0],\n [\"Bus2\", \"PQ\", 20.0],\n [\"Bus3\", \"PQ\", 20.0]\n ],\n \"trafo\": [\n [\"Trafo1\", \"Grid\", \"Bus0\", \"TRAFO_40\", true, 0]\n ],\n \"branch\": [\n [\"B_0\", \"Bus0\", \"Bus1\", \"NA2XS2Y_185\", 5.0, true],\n [\"B_1\", \"Bus0\", \"Bus2\", \"NA2XS2Y_185\", 3.0, true],\n [\"B_2\", \"Bus1\", \"Bus3\", \"NA2XS2Y_185\", 2.0, true],\n [\"B_3\", \"Bus2\", \"Bus3\", \"NA2XS2Y_185\", 0.3, true]\n ]\n }\n\nThere must be *exactly one* REF bus in the list and it must also be the first\nentry of the list.\n\nIf you want to specify additional branch or transformer types, you can add\n``branch_types`` or ``trafo_types`` to the object. They are also structured\nsimilarly to the Excel file:\n\n.. code-block:: json\n\n {\n \"bus\": [\n [\"Grid\", \"REF\", 110.0],\n [\"Bus0\", \"PQ\", 20.0],\n [\"Bus1\", \"PQ\", 20.0],\n ],\n \"trafo\": [\n [\"Trafo1\", \"Grid\", \"Bus0\", \"TRAFO_23\", true, 0]\n ],\n \"branch\": [\n [\"B_0\", \"Bus0\", \"Bus1\", \"SPAM_200\", 5.0, true]\n ],\n \"branch_types\": {\n \"SPAM_200\": [0.1337, 0.0815, 0, 404]\n },\n \"trafo_types\": {\n \"TRAFO_23\": [23, 100, 800, 100, 0.0123, 1.234, {\"-1\": 0.9, \"0\": 1, \"1\": 1.1}]\n }\n }\n\n\nJSON (old format)\n^^^^^^^^^^^^^^^^^\n\nThe old JSON format (also with the ``*.json`` suffix) differs from the new\nformat by explicitly listing the branch and transformer parameters for each\nbranch and transformer. It must also have a ``base_mva`` entry which is used\nfor the p.u. conversion. It can usually just be set to ``1``:\n\n::\n\n {\n \"base_mva\": <global_base_mva>,\n \"bus\": [\n [\"<bus_id>\", \"REF|PQ\", <base_kv>],\n ...\n ],\n \"trafo\": [\n [\"<trafo_id>\", \"<from_bus_id>\", \"<to_bus_id>\", <Sr_MVA>, <v1_%>,\n <P1_MW>, <Imax_p_A>, <Imax_s_A>],\n ...\n ],\n \"branch\": [\n [\"<branch_id>\", \"<from_bus_id>\", \"<to_bus_id>\", <length_km>,\n <R'_ohm/km>, <X'_ohm/km>, <C'_nF/km>, <I_max_A>],\n ...\n ]\n }\n\nAgain, there may only be one *REF* bus and it must be the first in the list\n\n\nUsage in mosaik\n---------------\n\nAs pointed out above, you can run mosaik-pypower in-process or as\na sub-process. Every instance of mosaik-pypower can handle multiple power grids\nat once. This is very handy for scenarios with a lot of separate grids. You can\nstart one instance of mosaik-pypower for every CPU core of your machine and\ndistribute all grids over these instance. More instances would mean more\noverhead, less instances would mean less parallelization.\n\nInstantiation and initialization\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nHere is an example *sim config* for mosaik:\n\n.. code-block:: python\n\n sim_config = {\n 'PyPower-inproc': {\n 'python': 'mosaik_pypower.mosaik:PyPower',\n },\n 'PyPower-subproc': {\n 'cmd': 'mosaik-pypower %(addr)s',\n },\n }\n\nWhen you create an instance of mosaik-pypower, you can pass three parameters:\n\n- *step_size* is an integer in seconds (of simulation time) and defines how\n often a power flow analysis should be performend.\n\n- *pos_load* is an optional boolean that lets you specify whether the active\n power for loads is a positive or a negative number.\n\n The default (``True``) is to use positive numbers for loads and negative\n numbers for feed-in of active power.\n\n If you want to use negative values for loads and positive for feed-in, set\n this flag to ``False``.\n \n- *converge_exception* is an optional boolean that allows to set the behavior\n in case that the power flow does not converge.\n \n As default (``False``) all output attributes are set to NaN and the\n simulation continues. If set to ``True``, an exception is thrown and the\n simulation stops.\n\nExamples:\n\n.. code-block:: python\n\n # Power-flow every minute:\n pp_a = world.start('PyPower', step_size=60)\n\n # Power-flow every 15 minutes, negative values for active power of loads:\n pp_b = world.start('PyPower', step_size=300, pos_loads=False)\n\n\nModels\n^^^^^^\n\nMosaik-pypower provides the following models / entity types:\n\n**Grid**\n **public:** True\n\n **parameters:** *gridfile* [, *sheetnames*]\n\n This model is used to instantiate a power-grid within mosaik-pypower from the\n *gridfile* provided. The *Grid* instance will have child entities for every\n element in that grid (buses, branches, \u2026). You can access these entities\n via the ``children`` attribute of the *Grid* entity. These entities also\n contain information about how they are related to each other. This allows\n mosaik to determine the grid topology. You can query it via\n ``world.entity_graph[<full_entity_id>``.\n\n If you use an Excel file and deviate from the default sheet names, you can\n optionally pass a *sheetnames* argument which is a dict with the sheet names\n to use.\n\n**RefBus** / **PQBus**\n **public:** False\n\n **attributes:** *P*, *Q*, *Vl*, *Vm*, *Va*\n\n Every *Grid* will contain exactly one *RefBus* entity and at least one\n *PQBus* entity.\n\n *P* and *Q* are active / reactive power in [W] / [VAr].\n\n *Vl* is the nominal voltage in [V] as defined in the grid file. *Vm* is the\n current voltage magnitude in [V] and my deviate from *Vl*. *Va* is the voltage\n angle in [\u00b0] (degree).\n\n**Branch**\n **public:** False\n\n **attributes:** *P_from*, *Q_from*, *P_to*, *Q_to*, *I_real*, *I_imag*,\n *S_max*, *I_max*, *length*, *R_per_km*, *X_per_km*, *onine*\n\n A grid consists of an arbitrary amount of branches connecting the *PQBus*\n entities with each other.\n\n The attributes *(P|Q)_(from|to)* denote the (re)active power on both ends of\n the branch in [W] or [VAr]. *I_real* and *I_imag* are the complex current in\n [A] flowing through the branch.\n\n *S_max* and *I_max* denote the maximum acceptable apparent power (in [VA])\n and current (in [A]) for that branch.\n\n *lengh*, *R_per_km*, *X_per_km*, *C_per_km* and *online* are the respective\n values for the branch from the input file.\n\n**Transformer**\n **public:** False\n\n **attributes:** *P_from*, *Q_from*, *P_to*, *Q_to*, *S_r*, *I_max_p*,\n *I_max_s*, *P_loss*, *U_p*, *U_s*, *taps*, *tap_turn*.\n\n A grid may have an arbitrary number of transformers (zero, one or more).\n Since it is just a special kind of *Branch* it shares many attributes with\n it.\n\n The attributes *(P|Q)_(from|to)* denote the (re)active power on both ends of\n the branch in [W] or [VAr]. *I_real* and *I_imag* are the complex current in\n [A] flowing through the branch.\n\n *S_r* is the rated apparent power (in [VA]) of the transformer. *I_max_p* and\n *I_max_s* are the maximum currents in [A] for the primary and secondary side\n of the transformer. *P_loss* is the transformer's nominal power loss in [W].\n\n *U_p* and *U_s* are the nominal primary and secondary line-to-line voltages\n in [V].\n\n *taps* is a dictionary of the available tap turns of the transformer.\n *tap_turn* is the currently active tap turn.\n\n\nExamples for model instantiation and connection\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nHere are some examples on how to instantiate a power grid and work with the\nentities that you get in return.\n\nBasic examples:\n\n.. code-block:: python\n\n pp = world.start('PyPower', step_size=60)\n\n # Create a grid from a JSON file:\n grid = pp.Grid(gridfile='path/to/grid.json')\n\n # Get a list of RefBus, PQBus, Transformer and Branch entities:\n grid = grid.children\n\n # Create some PV entities and randomly connect them to a PQBus:\n pvs = make_pvs(...) # Returns a list of PV entities\n pq_buses = [e for e in grid if e.type == 'PQBus']\n mosaik.util.connect_randomly(world, pvs, pq_buses, ('P_out', 'P'), ('Q_out', 'Q'))\n\n\nAdvanced stuff:\n\n.. code-block:: python\n\n pp = world.start('PyPower', step_size=60)\n\n # Create a grid from an Excel file and overwrite default sheet names.\n # Directly grab the list of child entities\n grid = pp.Grid(gridfile='path/to/grid.xlsx', sheetnames={\n 'bus': 'Nodes',\n 'branch': 'Lines',\n 'branch_types': 'Line types',\n 'trafo_types': 'Transformer types',\n }).children\n\n # Get the RefBus\n ref_bus = [e for e in grid if e.type == 'RefBus']\n\n # Get all nodes starting with \"ConnectionPoint_\". Note that every entity ID\n # is prefixed with a grid index (e.g., \"1-\"). We can use regular expressions\n # to handle this:\n import re\n regex_cn = re.compile(r'\\d+-ConnectionPoint_.*')\n conpoints = [e for e in grid if regex_cn.match(e.eid)]\n\n # Create a dictionary mapping node names to the respective entities. Again,\n # we have to strip the grid index:\n conpoints = {e.eid.split('-', 1)[1]: n\n for n in grid if regex_cn.match(n.eid)}\n\n # Connected loads to defined connection points:\n houses = create_houses(...) # Returns a list of (house, node-id) tuples\n for house, node_id in houses:\n mosaik.connect(house, conpoints[house_id], ('P_out', 'P'), ('Q_out', 'Q'))\n\n # Get \"secondary side\" buses of all transformers\n trafo_nodes = []\n # 1. Get all transformers:\n trafos = [e for e in grid if e.type == 'Transformer']\n # 2. Group PQBuses by full ID for easier access:\n nodes = {e.full_id: e for e in grid if e.type == 'PQBus'}\n # 3. Iterate transformer relations (assuming that they are connected to the\n # RefBus on their primary side):\n for trafo in trafos:\n rels = world.entity_graph[trafo.full_id]\n assert len(rels) == 2\n for rel in rels:\n if rel in nodes:\n trafo_nodes.append(nodes[rel])\n break\n else:\n raise ValueError('No PQBus found at trafo.')\n\n\nGetting help\n------------\n\nIf you need, please visit either the `mosaik-users mailing list`__ (or the\n`PYPOWER Google group`__ if your issue is very PYPOWER specific).\n\n__ https://mosaik.offis.de/mailinglist\n__ https://groups.google.com/forum/#!forum/pypower\n\n\nChangelog\n=========\n\n0.8.2 \u2013 2022-09-27\n------------------\n- [BUGFIX] Added restriction to numpy <1.23, because newer versions are incompatible with current PYPOWER version\n\n0.8.1 \u2013 2022-03-23\n------------------\n- [BUGFIX] Removed limitation for scypi and increased python compatibility to 3.10.\n\n0.8.0 \u2013 2021-05-21\n------------------\n\n- [CHANGE] Updated to mosaik-api 3.0.\n- [NEW] converge_exception can be set to throw an exception if load flow\n doesn't converge\n\n\n0.7.3 - 2021-03-04\n------------------\n\n- [BUGFIX] Require version <1.6.0 of scipy and <2.0 of xlrd, because newer versions are incompatible\n- [BUGFIX] Set I_real and I_imag in case of failure of power flow\n\n\n0.7.2 \u2013 2017-07-19\n------------------\n\n- [BUGFIX] --> Issue #5: https://bitbucket.org/mosaik/mosaik-pypower/issues/5\n- [BUGFIX] --> Issue #6: https://bitbucket.org/mosaik/mosaik-pypower/issues/6\n- [LIB-UPDATE] --> scipy update from version 0.17.0 to version 0.19.1\n\n\n0.7.1 \u2013 2016-02-15\n------------------\n\n- [FIX] Fixed a typo in model.py. \"Tap\" can now be read from Excel files.\n\n\n0.7 \u2013 2014-10-28\n----------------\n\n- [NEW]\u00a0Added ability to extend the built-in branch/transformer database\n (`issue #2`_).\n- [NEW] Wrote a lot new documentation (`issue #3`_)\n\n.. _`issue #2`: https://bitbucket.org/mosaik/mosaik-pypower/issue/2/\n.. _`issue #3`: https://bitbucket.org/mosaik/mosaik-pypower/issue/3/\n\n\n0.6.3 \u2013 2014-09-22\n------------------\n\n- [CHANGE] Updated to mosaik-api 2.0.\n\n\n0.6.2 \u2013 2014-07-31\n------------------\n\n- [CHANGE] Cache xlsx files to improve performance\n- [CHANGE] Updated to mosaik-api 2.0a4.\n\n\n0.6.1 \u2013 2014-06-30\n------------------\n\n- [NEW] Added *I_max_p* [A] and *I_max_s* [A] to the transformer data.\n\n\n0.6 \u2013 2014-06-26\n----------------\n\n- [NEW] Can import grids from Excel files (xlsx)\n- [NEW] New import format for JSON files (the old format is still supported)\n- [CHANGE] Massive internal refactoring.\n- [CHANGE] Updated to mosaik-api 2.0a3.\n\n\n0.5 \u2013 2014-03-26\n----------------\n\n- Initial release\n\n\nAuthors\n=======\n\nThe mosaik-pypower is developed by Stefan Scherfke.\nAndr\u00e9 El-Ama joined the team in July 2017.\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "An adapter to use PYPOWER with mosaik.",
"version": "0.8.3",
"project_urls": {
"Homepage": "https://gitlab.com/mosaik/components/energy/mosaik-pypower"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b6b3cd8781425e9ed4f3c6952adf0a266fb9ab8d8c4d0a4fd6fca8e1e29f34e",
"md5": "c4b6a91546f2e4c24ac5663c3d8a46cd",
"sha256": "29ae0a0d3d133ac17249f294c861268b90ca98dfe6ad0aaea3d5b64b3c88f33d"
},
"downloads": -1,
"filename": "mosaik_pypower-0.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c4b6a91546f2e4c24ac5663c3d8a46cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22048,
"upload_time": "2023-06-14T09:05:05",
"upload_time_iso_8601": "2023-06-14T09:05:05.416134Z",
"url": "https://files.pythonhosted.org/packages/7b/6b/3cd8781425e9ed4f3c6952adf0a266fb9ab8d8c4d0a4fd6fca8e1e29f34e/mosaik_pypower-0.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9b259b70cd9c9ba94ca32455ce3d15a8bff98d966594abc890dff85aaed00d78",
"md5": "7a577d80449b815aecfbf9bd192f14a1",
"sha256": "66c4993edad017df90768ee0b79095b3d89842213b7bc4a838f0900d4958fc9b"
},
"downloads": -1,
"filename": "mosaik-pypower-0.8.3.tar.gz",
"has_sig": false,
"md5_digest": "7a577d80449b815aecfbf9bd192f14a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27255,
"upload_time": "2023-06-14T09:05:07",
"upload_time_iso_8601": "2023-06-14T09:05:07.574497Z",
"url": "https://files.pythonhosted.org/packages/9b/25/9b70cd9c9ba94ca32455ce3d15a8bff98d966594abc890dff85aaed00d78/mosaik-pypower-0.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-14 09:05:07",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "mosaik",
"gitlab_project": "components",
"lcname": "mosaik-pypower"
}
JSON