Commit 1a8d6964 authored by Markus Mirz's avatar Markus Mirz
Browse files

Merge branch 'update-docs' into 'master'

Update docs

See merge request !162
parents 47ba8841 23bfe413
......@@ -47,6 +47,3 @@ __pycache__/
.eggs/
*.egg-info/
.ipynb_checkpoints/
# Auto-generated
Documentation/README.md
\ No newline at end of file
variables:
RSYNC_OPTS: --recursive --ignore-missing-args --chown ${DEPLOY_USER}:${DEPLOY_USER}
DOCKER_TAG: ${CI_COMMIT_REF_NAME}
DOCKER_TAG_DEV: ${CI_COMMIT_REF_NAME}
DOCKER_IMAGE: rwthacs/dpsim
DOCKER_IMAGE_DEV: rwthacs/dpsim-dev
......@@ -22,14 +21,14 @@ docker:
script:
- docker build
--file Packaging/Docker/Dockerfile.dev
--tag ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
--tag ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
--tag ${DOCKER_IMAGE_DEV}:latest .
# build dedicated jupyter image in the future
- docker build
--file Packaging/Docker/Dockerfile.jupyter
--build-arg DOCKER_IMAGE=${DOCKER_IMAGE_DEV}
--build-arg DOCKER_TAG=${DOCKER_TAG_DEV}
--tag ${DOCKER_IMAGE_DEV}-jupyter:${DOCKER_TAG_DEV}
--build-arg DOCKER_TAG=${DOCKER_TAG}
--tag ${DOCKER_IMAGE_DEV}-jupyter:${DOCKER_TAG}
--tag ${DOCKER_IMAGE_DEV}-jupyter:latest .
tags:
- shell
......@@ -42,7 +41,7 @@ build:linux:
- cd build
- cmake ..
- make -j 32
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
cache:
paths:
- build
......@@ -76,7 +75,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:
......@@ -102,7 +101,7 @@ build:windows:
# - pytest -v Examples/Python/Circuits
# - pytest -v Examples/Python/RealTime
# #- pytest -v Examples/Python/Shmem
# image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
# image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
# dependencies:
# - build:linux
# tags:
......@@ -113,13 +112,13 @@ generate:docs:
script:
- make -j$(nproc) -C build docs
- make -j$(nproc) -C build docs_cxx
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
dependencies:
- build:linux
artifacts:
paths:
- build/Documentation/html
- build/Documentation/Cxx/html
- build/docs/sphinx/html
- build/docs/doxygen/html
tags:
- docker
......@@ -131,7 +130,7 @@ generate:packages:
- tags
tags:
- docker
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
dependencies:
- build:linux
artifacts:
......@@ -142,7 +141,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
......@@ -163,7 +162,7 @@ test:jupyter:
PYTHONPATH: "build/Source/Python:Source/Python"
script:
- pytest -v Examples/Notebooks
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
dependencies:
- build:linux
tags:
......@@ -177,8 +176,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/sphinx/html/. public/sphinx
- cp -r build/docs/doxygen/html/. public/doxygen
artifacts:
paths:
- public
......@@ -193,7 +192,7 @@ pages:
deploy:docker:
stage: deploy
script:
- docker push ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
- docker push ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
- docker push ${DOCKER_IMAGE_DEV}:latest
- docker push ${DOCKER_IMAGE}:${DOCKER_TAG}
- docker push ${DOCKER_IMAGE}:latest
......
......@@ -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
if(WITH_PYTHON)
find_package(Sphinx)
if(SPHINX_EXECUTABLE)
# configured documentation tools and intermediate build results
set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build")
# Sphinx cache with pickled ReST documents
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
# HTML output directory
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
set(SPHINX_TITLE "${PROJECT_NAME} Documentation")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
"${BINARY_BUILD_DIR}/conf.py"
@ONLY
)
# Copy figures into Sphinx working directory
add_custom_target(copy_imgs
COMMAND
${CMAKE_COMMAND} -E make_directory
"${CMAKE_CURRENT_BINARY_DIR}/html/images/"
COMMAND
${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/images/dpsim.png"
"${CMAKE_CURRENT_BINARY_DIR}/html/images/"
COMMENT "Copying figures to Sphinx output dir"
)
# Copy figures into Sphinx working directory
add_custom_target(copy_notebooks
COMMAND
${CMAKE_COMMAND} -E make_directory
"${CMAKE_CURRENT_SOURCE_DIR}/Notebooks/"
COMMAND
${CMAKE_COMMAND} -E copy_directory
"${CMAKE_SOURCE_DIR}/Examples/Notebooks/"
"${CMAKE_CURRENT_SOURCE_DIR}/Notebooks/"
COMMENT "Copying notebooks to Sphinx output dir"
)
# We add the path of the freshly build dpsim.so module to Python path here
add_custom_target(docs
COMMAND
${CMAKE_COMMAND} -E env PYTHONPATH=$<TARGET_FILE_DIR:dpsim_python>:${CMAKE_CURRENT_SOURCE_DIR}/../Source/Python/:$ENV{PYTHONPATH}
${SPHINX_EXECUTABLE}
-q -b html
-c "${BINARY_BUILD_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx"
DEPENDS
${CMAKE_CURRENT_SOURCE_DIR}/README.md
dpsim_python
copy_imgs
copy_notebooks
)
add_custom_command(
OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/README.md
DEPENDS ${PROJECT_SOURCE_DIR}/README.md
COMMENT Fixing mainpage for Sphinx
COMMAND
sed -e 's/Documentation\\/images/images/'
< ${PROJECT_SOURCE_DIR}/README.md
> ${CMAKE_CURRENT_SOURCE_DIR}/README.md
)
endif()
endif()
# add a target to generate API documentation with Doxygen
find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
@ONLY
)
# HTML output directory
set(DOXYGEN_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/Cxx")
file(MAKE_DIRECTORY ${DOXYGEN_HTML_DIR})
# Copy figures into Doxygen working directory
add_custom_target(copy_imgs_cxx
COMMAND
${CMAKE_COMMAND} -E make_directory
"${CMAKE_CURRENT_BINARY_DIR}/Cxx/html/images/"
COMMAND
${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/images/dpsim.png"
"${CMAKE_CURRENT_BINARY_DIR}/Cxx/html/images/"
COMMENT "Copy figures to Doxygen output dir"
)
add_custom_target(docs_cxx
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
DEPENDS
copy_imgs_cxx
)
endif(DOXYGEN_FOUND)
.. 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)