Commit e9033579 authored by Markus Mirz's avatar Markus Mirz
Browse files

remove obsolete docs

parent 9ecc35fc
......@@ -47,6 +47,3 @@ __pycache__/
.eggs/
*.egg-info/
.ipynb_checkpoints/
# Auto-generated
Documentation/README.md
\ No newline at end of file
......@@ -76,7 +76,7 @@ build:windows:
# - cd build
# - cmake -DCMAKE_C_COMPILER=/usr/local/bin/gcc-9
# -DCMAKE_CXX_COMPILER=/usr/local/bin/g++-9
# -DWITH_CIM_SUBMODULE=ON
# -DWITH_CIM_SUBMODULE=ON
# -DWITH_SUNDIALS=OFF ..
# - make -j $(sysctl -n hw.ncpu)
# cache:
......@@ -118,8 +118,8 @@ generate:docs:
- build:linux
artifacts:
paths:
- build/Documentation/html
- build/Documentation/Cxx/html
- build/docs/html
- build/docs/Cxx/html
tags:
- docker
......@@ -142,7 +142,7 @@ generate:packages:
build:docker:
stage: build
script:
- docker build
- docker build
--file Packaging/Docker/Dockerfile
--build-arg DOCKER_TAG=${DOCKER_TAG}
--build-arg CI=1
......@@ -177,8 +177,8 @@ test:jupyter:
pages:
stage: deploy
script:
- cp -r build/Documentation/html/. public
- cp -r build/Documentation/Cxx/html/. public/cxx
- cp -r build/docs/html/. public
- cp -r build/docs/Cxx/html/. public/cxx
artifacts:
paths:
- public
......
......@@ -25,7 +25,7 @@ set(PROJECT_HOMEPAGE_URL "http://www.fein-aachen.org/projects/dpsim/")
set(PROJECT_VCS_URL "https://git.rwth-aachen.org/acs/public/simulation/dpsim")
include(CheckCXXCompilerFlag)
if(MSVC)
if(MSVC)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /EHsc")
check_cxx_compiler_flag("/W4 /WX" CXX_SUPPORTS_WERROR)
......@@ -58,7 +58,7 @@ option(SPDLOG_BUILD_EXAMPLES "Build spdlog examples" OFF)
# Workaround for spdlog in Windows
# A custom FindSpdlog does not work currently
option(WITH_SPDLOG_SUBMODULE "Build with Spdlog as submodule" OFF)
if (WITH_SPDLOG_SUBMODULE OR WIN32)
if (WITH_SPDLOG_SUBMODULE OR WIN32)
set(SPDLOG_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Dependencies/spdlog/include)
else()
find_package(spdlog REQUIRED)
......@@ -110,7 +110,7 @@ set(INCLUDE_DIRS
add_subdirectory(Tests)
add_subdirectory(Source)
add_subdirectory(Documentation)
add_subdirectory(docs)
if(BUILD_EXAMPLES)
add_subdirectory(Examples)
......
Build
========
Development Version
-------------------
In the repository, there is a Docker file with all required dependencies::
$ cd dpsim
$ docker build -t rwthacs/dpsim-dev -f Packaging/Docker/Dockerfile.dev .
Alternatively, the image can be pulled from DockerHub like so::
$ docker pull rwthacs/dpsim-dev
To run Jupyter lab notebooks from the dpsim repository, call::
$ git clone --recurse-submodules git@git.rwth-aachen.de:acs/public/simulation/dpsim.git
$ cd dpsim
$ docker run -it -p 8888:8888 -v $(pwd):/dpsim --privileged rwthacs/dpsim-dev bash
For Windows, you might need to specify the current directory like this::
$ docker run -it -p 8888:8888 -v ${pwd}:/dpsim --privileged rwthacs/dpsim-dev bash
The DPsim C++ and DPsim Python library can be built as follows::
$ cd dpsim
$ mkdir build
$ cd build
$ cmake ..
$ cmake --build . --target dpsim_python
To build everything run:::
$ cmake --build .
Finally, the Python package is added to the path and Jupyter started::
$ export PYTHONPATH=$(pwd)/Source/Python:$(pwd)/../Source/Python
$ cd /dpsim
$ jupyter lab --ip="0.0.0.0" --allow-root --no-browser
Documentation
-------------
Python
^^^^^^
- Install `Sphinx`_ or use the Docker image.
- Generate the Python documentation by running Sphinx via CMake::
$ mkdir -p build
$ cd build
$ cmake ..
$ make docs
- The resulting documentation will be generated in ``Documentation/html/``
C++
^^^
- Install `Doxygen`_ or use the Docker image.
- Generate the C++ documentation by running Doxygen via CMake:::
$ mkdir -p build
$ cd build
$ cmake ..
$ make docs_cxx
- The resulting documentation will be generated in ``Documentation/html/Cxx``
.. _Sphinx: http://www.sphinx-doc.org/en/master/index.html
.. _Doxygen: http://www.doxygen.org/
Python Package
--------------
Docker
^^^^^^
1. Follow the steps in for the development version to set up the Docker container.
2. To build the Python package run::
$ python3 setup.py bdist_wheel
CMake for Linux
^^^^^^^^^^^^^^^
The most recent list of requirements can be found in the Dockerfiles.
1. Make sure that the required dependencies are installed.
**Note:** There are currently no Debian packages for `villas-node` and `libcimpp16v29a`.
If you want to use these optional feature, you have to build them manually.
# Install Sundials
$ git clone --branch v3.1.1 https://github.com/LLNL/sundials.git
$ mkdir sundials/build
$ pushd sundials/build
$ cmake .. \
-DBUILD_SHARED_LIBS=ON \
-DBUILD_STATIC_LIBS=OFF \
-DEXAMPLES_ENABLE_C=OFF
$ make -j$(nproc) install
$ popd
# Install CIM++
$ git clone --recursive https://github.com/RWTH-ACS/libcimpp.git
$ mkdir libcimpp/build
$ pushd libcimpp/build
$ cmake .. \
-DUSE_CIM_VERSION=IEC61970_16v29a \
-DBUILD_SHARED_LIBS=ON \
-DCMAKE_POSITION_INDEPENDENT_CODE=ON
$ make -j$(nproc) install
2. Fetch sources::
$ git clone https://git.rwth-aachen.de/acs/public/simulation/dpsim.git
$ cd dpsim
$ git submodule update --init Dependencies/libcps
3. Compile::.
$ mkdir build
$ cmake ..
$ make -j$(nproc)
4. To install the generated Python module to your system::
$ sudo make install
CMake for Windows
^^^^^^^^^^^^^^^^^
1. Make sure that the required dependecies are installed::
- Visual Studio 2017 and the C++ Desktop development package
- `CMake`_ for Windows
- `Git for Windows`_
- For Python support, install `Python 3`_ using the normal installer or a distribution like Anaconda, and add Python to your PATH.
2. Fetch sources::
$ git clone --recursive git@git.rwth-aachen.de:acs/core/simulation/dpsim.git
$ cd dpsim
3. Open a windows command prompt and navigate into the new DPsim folder.
4. Generate a Visual Studio project with CMake and use it to build the project::
$ mkdir build
$ cd build
$ cmake -G "Visual Studio 15 2017 Win64" ..
5. Open Visual Studio and load the Visual Studio project from the build directory within the DPsim folder.
6. You can either build the project from within Visual Studio or from the command line by running the following command in the windows command prompt::
$ cmake --build .
7. To build the Python package run::
$ python3 setup.py bdist_wheel
8. To install the Python package use Visual Studio and the Release configuration to build the DPsim Python module and then build the INSTALL project.
.. _`Python 3`: https://www.python.org/downloads/
.. _CMake: https://cmake.org/download/
.. _`Git for Windows`: https://git-scm.com/download/win
.. _VILLASnode: https://git.rwth-aachen.de/VILLASframework/VILLASnode
.. _DPsim: https://git.rwth-aachen.de/acs/core/simulation/dpsim
CMake for macOS
^^^^^^^^^^^^^^^
1. Make sure that the required dependecies are installed::
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install gcc9 git cmake graphviz python3 gsl eigen spdlog
$ sudo pip3 install numpy
2. Fetch sources::
$ git clone --recursive git@git.rwth-aachen.de:acs/core/simulation/dpsim.git
$ cd dpsim
3. Compile::.
$ mkdir build
$ cmake ..
$ make -j$(sysctl -n hw.ncpu)
4. To install the generated Python module to your system::
$ sudo make install
Operating System Optimizations
------------------------------
The operating system configuration has a large impact on the real-time performance of DPsim.
For optimal results, follow the suggestions collected in the `VILLASnode documentation`_.
.. _`VILLASnode documentation`: https://villas.fein-aachen.org/doc/node-tuning.html
\ No newline at end of file
.. mdinclude:: ../CHANGELOG.md
.. mdinclude:: ../COPYING.md
Development
===========
Environment
-----------
At the Institute for Automation of Complex Power Systems (ACS) we recommend the following development tools:
- Editor: [Visual Studio Code](https://code.visualstudio.com)
- Extensions:
- [Install](vscode:extension/ms-vscode-remote.remote-containers)
- [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
- [CMake Tools](https://marketplace.visualstudio.com/items?itemName=vector-of-bool.cmake-tools)
- [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)
- [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
- [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
- [Docker](https://www.docker.com)
- [CMake](https://cmake.org)
- [Git](https://git-scm.com)
- Issues: http://git.rwth-aachen.de/acs/public/simulation/dpsim/issues
- Merge Requests: http://git.rwth-aachen.de/acs/public/simulation/dpsim/merge_requests
- Continous Integration and Testing: http://git.rwth-aachen.de/acs/public/simulation/dpsim/pipelines
Please follow the [Build](./Build.rst) guide to checkout your code and install the basic dependencies and tools.
Add a new Component Model
-------------------------
In this section we will show the implementation of a new component model at the example of a three-phase inductor.
C++ OOP for Component Models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DPsim implements component models in a sub-component called CPowerSystems or short CPS.
CPS is embedded as a submodule to the DPsim repository.
TODO: add class diagram
Every component in CPS is represented by a C++ class.
DPsim supports different types of solvers (MNA, DAE, NRP).
Each solver requires certain member functions in the component class to be implemented.
These functions are specified by the solver interface classes: ``MNAInterface.h``, ``DAEInterface.h``, ...
Directory / Namespace Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For the implementation of the new component, we add two new files
- ``Dependencies/libcps/Source/DP/DP_Ph3_Inductor.cpp``
- ``Dependencies/libcps/Include/DP/DP_Ph3_Inductor.h``
In these files, we will implement a new C++ class with the name ``CPS::DP::Ph3::Inductor``.
Component Types
"""""""""""""""
Directories:
::
DPsim
|
|- Source
|- Include
\ Dependencies
\ libcps
|- Source
|- DP
|- EMT
|- Static
\ Signal
|- Include
|- DP
|- EMT
|- Static
\ Signal
Namespaces:
::
CPS::{DP,EMT,Signal,Static}::{Ph1,Ph3}::{Name}
Attributes
~~~~~~~~~~
Tasks for Pre/Post-step Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TODO: add example task dependency graph
MNA Matrix Stamping
~~~~~~~~~~~~~~~~~~~
https://en.wikipedia.org/wiki/Modified_nodal_analysis
Adding the new Component to DPsim
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After finishing the implementation of the new component, it needs to be added to the following files:
- ``Dependencies/libcps/Include/cps/Components.h``
- ``Dependencies/libcps/Source/CMakeLists.txt``
- ``Sources/Python/Module.cpp``
\ No newline at end of file
# DPsim C++ Developer Documentation
DPsim is a solver library for power system simulation.
- It supports both the electro-magnetic transient (EMT) and dynamic phasor (DP) domain.
- It provides a Python module which can be embedded in any Python 3 application / scripts.
- It is implemented in highly-efficient C++ code.
- It supports real-time execution with time-steps up to 50 micro seconds.
- It can load models in the [Common Information Model (CIM)](https://en.wikipedia.org/wiki/Common_Information_Model_%28electricity%29) XML format.
- It can be interfaced to a variety of protocols and interfaces via [VILLASnode](http://www.fein-aachen.org/projects/villas-framework/).
## Documentation
The [user documentation](http://dpsim.fein-aachen.org/doc/development/sphinx/) has examples, build / installation instructions and covers the Python API.
The C++ [developer documentation](http://dpsim.fein-aachen.org/doc/development/doxygen/) only includes automatically generated content using Doxygen.
It is helpful to understand the general structure of the C++ DPsim core components.
## Copyright
2017-2020, Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
## License
This project is released under the terms of the [GPL version 3](https://dpsim.fein-aachen.org/doc/development/sphinx/Copying.html).
```
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
```
For other licensing options please consult [Prof. Antonello Monti](mailto:amonti@eonerc.rwth-aachen.de).
## Contact
- Markus Mirz <mmirz@eonerc.rwth-aachen.de>
- Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
[Institute for Automation of Complex Power Systems (ACS)](http://www.acs.eonerc.rwth-aachen.de)
[EON Energy Research Center (EONERC)](http://www.eonerc.rwth-aachen.de)
[RWTH University Aachen, Germany](http://www.rwth-aachen.de)
Examples
========
Jupyter Notebooks
-----------------
The following examples have been provided as Jupyter Notebooks.
You can read them online or :doc:`install </Install>` DPsim and execute them interactively on your local machine.
Notebooks including the results can be found in a dedicated `Github repository <https://github.com/DPsim-Simulator/DPsim-Notebooks>`__.
.. toctree::
:glob:
:titlesonly:
Notebooks/Quickstart Guide
Notebooks/DP_Basics
Notebooks/Features/*
Notebooks/Circuits/*
Notebooks/Components/*
Notebooks/Grids/*
Links
-----
More examples can be found in the DPsim repository.
Apart from the `Jupyter notebooks`_, there are pure `Python`_ and `C++`_ examples available.
.. _Jupyter notebooks: https://git.rwth-aachen.de/acs/core/simulation/dpsim/tree/development/Examples/Notebooks
.. _Python: https://git.rwth-aachen.de/acs/core/simulation/dpsim/tree/development/Examples/Python
.. _C++: https://git.rwth-aachen.de/acs/core/simulation/dpsim/tree/development/Examples/Cxx
Installation
============
DPsim is a Python module / C++ library for complex power system
simulation. As a Python module, the easiest way to get to know DPsim is
via `Jupyter Notebooks <https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/>`__.
Docker
------
1. First, you need to install `Docker <https://docs.docker.com/install/>`_.
2. To start a Jupyter session, run a DPsim Docker container
::
$ docker run -p 8888:8888 rwthacs/dpsim
And access the session by opening the following link: http://localhost:8888/lab/tree/Index.ipynb?token=3adaa57df44cea75e60c0169e1b2a98ae8f7de130481b5bc
Python
------
**Currently, the DPsim Python packages are broken. Until we have updated the packages, please use the docker installation.**
Prerequisites
^^^^^^^^^^^^^
First, you need to make sure that Python is installed and your version is compatible.
DPsim is built for **Python 3.5, 3.6 and 3.7**.
An easy way to install Python and all required packages is the `Anaconda distribution <https://www.anaconda.com/>`_.
To get started, install the latest installer for Python 3.x from the `downloads section <https://www.anaconda.com/download/>`_.
Then, run the Anaconda Prompt and create a new conda environment:
.. code-block:: bash
conda create -n dpsim python=3.6
After creating the environment you need to make sure that it is activated.
The current environment is displayed at the beginning of the command line in brackets.
It should read *"(dpsim)..."*.
In case it is not activated, run:
.. code-block:: bash
activate dpsim
Pip Package Installation
^^^^^^^^^^^^^^^^^^^^^^^^
Then, DPsim can be easily installed as a Python module by running for the latest stable release:
.. code-block:: bash
pip install dpsim
or for the latest nightly version:
.. code-block:: bash
pip install --extra-index-url https://packages.fein-aachen.org/python/simple dpsim
From Source
-----------
To build and install DPsim from the source files, please refer to the section :doc:`Build </Build>`.
\ No newline at end of file
Jupyter Notebooks
=================
The following examples have been provided as Jupyter Notebooks.
You can read them online or execute and modify them interactively on your local machine.
Use the notebooks on your local machine
---------------------------------------
*Please note that the DPsim source code is not yet publicy available.*
Jupyter
~~~~~~~
Please install jupyter by following `this guide`_.
.. _`this guide`: http://jupyter.readthedocs.io/en/latest/install.html
DPsim module + notebooks
~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
$ git clone git@git.rwth-aachen.de:acs/core/simulation/dpsim.git
$ cd dpsim
$ sudo python3 setup.py install
$ jupyter notebook --notebook-dir Examples/Notebooks/
List of Notebooks
~~~~~~~~~~~~~~~~~
.. toctree::
:glob:
:titlesonly:
Notebooks/Quickstart Guide
Notebooks/DP_Basics
Notebooks/Features/*
Notebooks/Circuits/*
Notebooks/Components/*
Notebooks/Grids/*
\ No newline at end of file
Real-time Execution
===================
This page describes recommended techniques to optimize the host operating system for real-time execution of DPsim.
In principle, real-time execution is supported on all platforms.
However, we recommend to use an optimized Linux installation.
Operating System and Kernel
---------------------------
For minimum latency several kernel and driver settings can be optimized.
To get started, we recommend the `Redhat Real-time Tuning Guide <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_MRG/2/html/Realtime_Tuning_Guide/index.html>`__.
A `PREEMPT_RT patched Linux <https://rt.wiki.kernel.org/index.php/Main_Page>`__ kernel is recommended.
Precompiled kernels for Fedora can be found here: http://ccrma.stanford.edu/planetccrma/software/
Use the *tuned* tool for improving general real-time performance.
Please adjust the setting ``isolated_cpucores`` according to your hardware and enable the ``realtime`` profile as follows:
.. code:: bash
dnf install tuned-profiles-realtime
echo "realtime" > /etc/tuned/active_profile
echo "isolated_cpucores=6-7" >> /etc/tuned/realtime-variables.conf
systemctl enable tuned && systemctl start tuned
systemctl reboot
Running a real-time simulation
------------------------------
As a reference, real-time simulation examples are provided here: https://git.rwth-aachen.de/acs/public/simulation/dpsim/tree/development/Examples/Cxx/RealTime
In order to run a real-time simulation, the simulation process must be started in a special way in order to change the execution priority, scheduler and CPU affinity.
For this purpose the ``chrt`` and ``taskset`` commands are used.
In the following example, we pin the execution of the simulation to CPU cores 6-7 which have been reserved previously by the tuned real-time profile (see above).
.. code:: bash
taskset --all-tasks --cpu-list 6-7 \
chrt --fifo 99 \
Examples/Cxx/RT_DP_CS_R_1
More details:
- `chrt man-page <http://man7.org/linux/man-pages/man1/chrt.1.html>`__
- `taskset man-page <http://man7.org/linux/man-pages/man1/taskset.1.html>`__