Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Improve documentation #807

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[WIP] Improve documentation #807

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
55729a0
Some improvements of the getting started and network documentation.
colinepiloquet Jul 16, 2024
44b7347
Merge branch 'main' into improve_documentation
colinepiloquet Jul 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,11 +121,13 @@

todo_include_todos = True

# Links to external documentations : python 3 and pandas
# Links to external documentations : python 3, pandas, powsybl-core
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'pandas': ('https://pandas.pydata.org/docs', None),
'powsybl-core': ("https://powsybl.readthedocs.io/projects/powsybl-core/en/latest/", None),
}
intersphinx_disabled_reftypes = ["*"]

# Generate one file per method
autosummary_generate = True
23 changes: 12 additions & 11 deletions docs/getting_started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,19 +27,18 @@ instructions on `github <https://github.com/powsybl/pypowsybl>`_.
Basic usage
-----------

The main data type you will manipulate is the :class:`Network <pypowsybl.network.Network>`,
defined in :mod:`pypowsybl.network` module.
The main data type that you will manipulate is the :class:`Network <pypowsybl.network.Network>`,
defined in the :mod:`pypowsybl.network` module.

In order to create one, you can use one of the provided creation methods, for example
you can create the well known IEEE 9-bus test case:
you can create the well-known IEEE 9-bus test case:

.. testcode::

import pypowsybl.network as pn
network = pn.create_ieee9()

You can then start inspecting the content of the network,
for example in order to get lines data:
You can then start inspecting the contents of the network, for example in order to get line data:

.. doctest::
:options: +NORMALIZE_WHITESPACE
Expand All @@ -54,10 +53,10 @@ for example in order to get lines data:
L5-4-0 1.00 8.50 0.0 0.000880 0.0 0.000880 NaN NaN NaN NaN NaN NaN VL5 VL1 VL5_0 VL1_1 True True
L6-4-0 1.70 9.20 0.0 0.000790 0.0 0.000790 NaN NaN NaN NaN NaN NaN VL6 VL1 VL6_0 VL1_1 True True

Each row of the obtained dataframe represents a line of the network.
Each row of the resulting dataframe represents one line of the network.

You may have noticed that the flows are :code:`NaN`. In order to compute them,
you can run a loadflow using the :mod:`pypowsybl.loadflow` module:
you can run a load flow using the :mod:`pypowsybl.loadflow` module:

.. testcode::

Expand All @@ -80,14 +79,13 @@ Flow values are now available in the lines dataframe:
L6-4-0 -30.54 30.70 -16.54 1.03

You can also generate a single line diagram of one of the substations
or voltage level, if you want to visualize the result:
or voltage levels, if you want to visualize the result:

.. code-block::

>>> network.get_single_line_diagram('S1')

This will produce the following SVG image, which will just display if you run
inside a notebook:
This will generate the following SVG image, which will be displayed automatically when running in a notebook:

.. image:: _static/images/getting-started-sld.svg
:class: forced-white-background
Expand All @@ -96,7 +94,10 @@ inside a notebook:
Going further
-------------

For more advanced use cases and topical guides, please check out the :doc:`/user_guide/index`.
For more advanced use cases and topic guides, please check out the :doc:`/user_guide/index`.

For a comprehensive list of features and detailed description of methods,
please check out the :doc:`/reference/index`.

Some introductory notebooks are available on the organization Github page under the repository
`pypowsybl-notebooks <https://github.com/powsybl/pypowsybl-notebooks>`_.
76 changes: 53 additions & 23 deletions docs/user_guide/network.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,24 @@ The network model
The :class:`Network` object is the main data structure of pypowsybl.
It contains all the data of a power network: substations, generators, lines,
transformers, ...
The specific documentation about the network model can be found `here <inv:powsyblcore:std:doc#grid_model/network_subnetwork>`_.
It details the equipment supported as well as their characteristics.

pypowsybl provides methods to create networks, and to access and modify their data.


Create a network
----------------

pypowsybl provides several factory methods to create well known network models.
pypowsybl provides several factory methods to create well-known network models.
For example, you can create the IEEE 9-bus network case:

.. doctest::

>>> network = pp.network.create_ieee9()

To know which networks are available in pypowsybl, you can check the list of creation functions in the `API guide <:ref:/reference/network>`_.

Another common way of creating a network is to load it from a file:

.. code-block:: python
Expand All @@ -35,16 +39,26 @@ The supported formats are the following:

.. Note::

Import formats may support specific parameters,
which you can find by using :func:`get_import_parameters`.
Import formats may support specific parameters, which you can find by using :func:`get_import_parameters`.

For example, to find the parameters available when loading a network with the XIIDM format:

.. code-block::
>>> pp.network.get_import_parameters("XIIDM")

An exhaustive list of these parameters as well as their description is available in the section dedicated to each
supported format `here <inv:powsyblcore:std:doc#grid_exchange_formats/index>`_.

Then, to use these specific parameters, they should be added as the second argument of the :func:`load` function as
a dictionary:

.. code-block:: python

network = pp.network.load('ieee14.raw', {'psse.import.ignore-base-voltage': 'true'})


Loading a network from a binary byte buffer (io.BytesIO) is possible.
Only zipped network loading are supported for now, but inside the zip file the supported network format are the same as pp.network.load.
Loading a network from a binary byte buffer (io.BytesIO) is also possible.
Only zipped network loading is supported for now, but inside the zip file, the supported network formats are the same as pp.network.load.

.. doctest::

Expand All @@ -57,47 +71,63 @@ You may also create your own network from scratch, see below.
Save a network
--------------

Networks can be written to the filesystem, using one of the available export formats:
Networks can be written to the filesystem, using one of the available export formats.

The supported export formats are:

.. doctest::

>>> pp.network.get_export_formats()
['AMPL', 'CGMES', 'JIIDM', 'MATPOWER', 'PSS/E', 'UCTE', 'XIIDM', 'BIIDM']

Note that for some formats, only the updated export is available, which means that it is only possible to export only if
the network was loaded from the same format. On this `page <inv:powsyblcore:std:doc#grid_exchange_formats/index>`_, you
can see details about the supported import and export formats.

To save a network, you can use the :func:`save` function with the path to the network, the format and optionally some parameters:

.. code-block:: python

network.save('network.xiidm', format='XIIDM')

.. Note::

Export formats may support specific parameters, which you can find by using :func:`get_export_parameters`.
For example, to find the parameters available when exporting a network with the XIIDM format:

.. code-block::
>>> pp.network.get_export_parameters("XIIDM")

An exhaustive list of these parameters as well as their description is available in the section dedicated to each
supported format `here <inv:powsyblcore:std:doc#grid_exchange_formats/index>`_.

The parameters must then be added in the :func:`save` function with the keyword argument `parameters`.


You can also serialize networks to a string:

.. code-block:: python

xiidm_str = network.save_to_string('XIIDM')

And also to a zip file as a (io.BytesIO) binary buffer.
And to a zip file as a (io.BytesIO) binary buffer.

.. code-block:: python

zipped_xiidm = network.save_to_binary_buffer('XIIDM')

The supported formats are:

.. doctest::

>>> pp.network.get_export_formats()
['AMPL', 'CGMES', 'JIIDM', 'MATPOWER', 'PSS/E', 'UCTE', 'XIIDM', 'BIIDM']

.. Note::

Export formats may support specific parameters,
which you can find by using :func:`get_export_parameters`.

Reading network elements data
-----------------------------

All network elements data can be read as :class:`DataFrames <pandas.DataFrame>`.
Supported elements are:

- buses (from bus view)
- buses from bus/breaker view
- buses (from the bus view)
- buses (from the bus/breaker view)
- lines
- 2 windings transformers
- 3 windings transformers
- two-winding transformers
- three-winding transformers
- generators
- loads
- shunt compensators
Expand All @@ -115,7 +145,7 @@ Supported elements are:
- branches (lines and two windings transformers)
- terminals are a practical view of those objects which are very important in the java implementation

Each element of the network is mapped to one row of the dataframe, an each element attribute
Each element of the network is mapped to one row of the dataframe, and each element attribute
is mapped to one column of the dataframe (a :class:`~pandas.Series`).

For example, you can retrieve generators data as follows:
Expand Down
Loading