mbsolve

An open-source solver tool for the full wave 1D Maxwell-Bloch equations.

Overview

The project consists of the following components:

• mbsolve-lib: Contains the common base classes for solvers and writers (which are subsequently derived and implemented in the other subprojects). As the name suggests, the solver class is responsible for solving the Maxwell-Bloch equations while the writer class writes the results to a file of the respective format. It also provides classes to describe a device setup (materials, dimensions, ...) and a simulation scenario (simulation settings, sources, ...).

• mbsolve-tool: A C++ test application that implements various simulation setups.

• solver-cpu: Uses the OpenMP standard to efficiently solve the equation system on multi-core CPUs or Intel's Xeon Phi.

• solver-cuda: Uses NVIDIA's CUDA framework to efficiently solve the equation system on graphics processing units (GPUs). Different solvers are implemented in this subproject.

• tools: Various scripts in different scripting languages.

• writer-hdf5: Writes the results into the HDF5 format.

All libraries feature a Python interface and can be used conveniently from Python scripts, Jupyter notebooks etc. See tools/python for examples.

Install via conda

If you have a conda distribution installed, you can install mbsolve using

$ conda install -c conda-forge mbsolve

from the conda-forge channel.

Get the code

Make sure to clone using

git clone --recurse-submodules [...]

in order to clone third-party libraries recursively. Alternatively, issue

git submodule update --init --recursive

in the repository if it already exists.

Build instructions

The project is built using the CMake build system. The typical commands under Linux are

$ cd mbsolve
$ mkdir build
$ cd build
$ cmake ..
$ make -j 8
$ ./mbsolve [--options]

By default, the build type is set to release with debug information, which enables debugging but features the optimization necessary for reasonable performance. Adjust the -j command line parameter of the make command in order to speed up the compilation.

In order to enable/disable a component, an extra option has to be passed to CMake:

$ cmake -DWITH_CUDA=ON/OFF ..

The project has been successfully compiled with the GNU compiler collection (gcc) and the Intel compiler (icc). gcc is used as default, the Intel compiler may be used with the following command:

$ CC=path_to_intel/icc CXX=path_to_intel/icpc cmake -DWITH_CUDA=OFF ..

Note that CUDA does not support all versions of the Intel compiler, hence the CUDA support is disabled.

The target architecture may be set using the ARCH option. By default, compiler optimizations suitable for the host machine are applied. However, when building for another machine the architecture can be set with e.g.

$ cmake -DARCH=AVX2 ..

The Doxygen documentation can be build with

$ make doc

If you want to use Eclipse, use the appropriate generator flag -G and (if desired) set the build type to Debug. (Note that Eclipse yields a warning if the build directory is a child of the source directory. Adjust path_src.)

$ cmake -DCMAKE_BUILD_TYPE=Debug -G"Eclipse CDT4 - Unix Makefiles" path_src

Tools

• Python scripts: Example scripts that define simulation setups and run the solver. Execute from build directory. See tools/python.

• MATLAB scripts: The examples read the simulation results and plot them. See tools/matlab.

• Slurm scripts: Example scripts for the Slurm Workload Manager. See tools/slurm.

Dependencies

The following software packages are required to build the project:

• C++ compiler
  • GNU Compiler Collection (gcc) >= 4.9.2
  • Intel C++ Compiler, any recent version
  • Clang >= v7.0.0 (Note: AppleClang lacks OpenMP support)
  • Microsoft Visual C++ (MSVC), any recent version (Note: MSVC only supports OpenMP 2.0)
• cxxopts (any recent version) for mbsolve-tool
• CMake >= 3.9
• Eigen library >= 3.3.4
• HDF5 (any recent version) for the writer-hdf5
• Python >= 2.7 and SWIG >= 2.0.12 for Python support
• CUDA >= 7.0 for solver-cuda
• OpenMP (see supported compilers) for solver-cpu
• Doxygen (any recent version) for the documentation

If the required dependencies are not met, the components may be disabled by the build system. Consider the minimum version given in the brackets.

The runtime dependencies are a reduced set of the list above. Namely, those are:

• C/C++ standard libraries including OpenMP support
• Python runtime
• HDF5

Naturally, the same versions as used during compilation must be available.

Contributing to mbsolve

Feel free to use the code and do not hesitate to contact me or to create an issue on GitHub. Any contributions are welcome.

If you found the code helpful and used it in your research, you can cite the following paper:
Riesch, Michael and Jirauschek, Christian, "mbsolve: An open-source solver tool for the Maxwell-Bloch equations," Comp. Phys. Comm. 268, 108097 (2021).

If desired, you can cite the project web page directly:
Riesch, Michael and Jirauschek, Christian, "mbsolve: An open-source solver tool for the Maxwell-Bloch equations," https://github.com/mriesch-tum/mbsolve [Online], (2017).