Architecture

svZeroDSolver is written in a highly modular manner to enable reuse of code for many different applications. It is divided into a header based library in the src directory and a collection of different applications in the applications folder. Each application is written for a different use-case of svZeroDSolver, namely:

svZeroDCalibrator in svzerodcalibrator.cpp
svZerodSolver in svzerodsolver.cpp
Python API in pysvzerod.cpp

The header-based library in the src folder contains classes and functions that are collectively used by all applications. A good overview over the general architecture can be found in the list of namespaces.

Build in debug mode

For debug purposes it is recommended to build svZeroDSolver in Debug mode.

mkdir Debug
cd Debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build .

Install with pip

Execute this command in the root folder to install the current source:

pip install -e ".[dev]"

This is useful when continuously running the integration tests during development.

Code Style

We follow the Google C++ Style Guide.

Formatting

We use clang-format to automatically format our code accoring to the Google Style, as specified in the .clang-format file. This increases readability and maintainability of the code while enabling you to focus on coding.

There are tools for your favorite IDE to automatically format your code. Examples are:

Before committing any changes, you can run the following command from your build folder to format all your files:

make codeformat

You can also just check if a file would be formatted without actually formatting it with:

make codecheck

If the above commands do not work on your platform (it does not work on Sherlock at Stanford) you can run the following command from the svZeroDSolver folder to format all your files:

find src/**/*.h src/**/*.cpp | xargs clang-format -style=Google -i

The latter check is also performed in the GitHub CI/CD (a.k.a. Actions) and indicates on merge requests when the code doesnt yet meet all style requirements.

On Sherlock at Stanford, clang-format is included in the llvm module.

Documentation

We use Doxygen to automatically build an html documentation from source code. Please have at Doxygen's Documentation Guide for an introduction into the syntax of writing documentation in C++. For more inspiration, you can look at the existing source files and how they use documentation.

NOTE: Undocumented code will fail the automated code checks on Github and cannot be merged.

In the following you can find a short recap of the most important commands:

Latex equations

For inline equations use \f$a+b=c\f$ and for block equations use:

\f[
a+b=c
\f]

Citations

If you want to cite a piece literature in your documentation, add a respective BibTeX citation to docs/cpp/references.bib and use \cite name_of_citation to cite the document.

Drawing circuits

As the elements of the svZeroDSolver are often represented in the form of electrical circuits, we use CircuiTikZ to draw circuits in the documentation (see blocks in Block for examples). To start a CircuitTikZ drawing use the following command:

\f[
\begin{circuitikz}
...
\end{circuitikz}
\f]

Build

The documentation is automatically built in the GitHub CI/CD and published on GitHub pages. If you want to build the documentation locally, you can use:

doxygen docs/Doxyfile

You can then view the documentation locally in your browser by opening docs/build/html/index.html.

If you do not have Doxygen install you can do that with brew install doxygen on macOS or with sudo apt-get install doxygen on Linux.

Profiling

Profiling helps to easily identify bottlenecks in the code. A profiling report lists the executation time spend on certain parts of the code. If you experience performance issue with svZeroDSolver, you can follow this guide to create a profiling report. The generation of profiling reports requires Docker to be installed on your machine.

docker build -t profile_svzerodsolver -f container/profiling/Dockerfile .

docker run -it -v $(PWD):/opt/data --rm profile_svzerodsolver path/to/simulation_config.json

This will generate a file called profiling_report.pdf in your current working directory.

Table of Contents