From 55729a00cf06c204d02083de514912b95e565cd5 Mon Sep 17 00:00:00 2001 From: Coline PILOQUET Date: Tue, 16 Jul 2024 17:16:35 +0200 Subject: [PATCH] Some improvements of the getting started and network documentation. Signed-off-by: Coline PILOQUET --- docs/conf.py | 4 +- docs/getting_started.rst | 23 +++++------ docs/user_guide/network.rst | 76 ++++++++++++++++++++++++++----------- 3 files changed, 68 insertions(+), 35 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2b1a721cb..4d3e7db87 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 diff --git a/docs/getting_started.rst b/docs/getting_started.rst index df2870a86..bf2e821ee 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -27,19 +27,18 @@ instructions on `github `_. Basic usage ----------- -The main data type you will manipulate is the :class:`Network `, -defined in :mod:`pypowsybl.network` module. +The main data type that you will manipulate is the :class:`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 @@ -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:: @@ -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 @@ -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 `_. diff --git a/docs/user_guide/network.rst b/docs/user_guide/network.rst index f2596a8bf..34710fdbb 100644 --- a/docs/user_guide/network.rst +++ b/docs/user_guide/network.rst @@ -6,6 +6,8 @@ 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 `_. +It details the equipment supported as well as their characteristics. pypowsybl provides methods to create networks, and to access and modify their data. @@ -13,13 +15,15 @@ pypowsybl provides methods to create networks, and to access and modify their da 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 @@ -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 `_. + + 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:: @@ -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 `_, 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 `_. + + 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 `. 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 @@ -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: