Installation¶

Advanced instructions for compiling MoCSI locally, including everything you need to develop new features.

Tip

Don’t want to compile anything? Run the prebuilt Docker image instead — it ships both mocsi and mocsi_mpi with VTK + CSPICE included. See Running MoCSI with Docker.

MoCSI builds on Linux, macOS, and Windows. Pick your platform to jump straight to the steps:

🐧 Linux apt + gcc + CMake + make 🍎 macOS Homebrew + CMake + make 🪟 Windows Visual Studio + CMake GUI

Requirements¶

MoCSI builds with CMake, a C++ compiler (GCC / Clang / MSVC), git, and Python for the config generator. Versions known to work:

Tool	Minimum	Notes
CMake	3.10	Set by `cmake_minimum_required` in `CMakeLists.txt`.
C++ compiler	Must support C++20	GCC ≥ 10, Clang ≥ 11, MSVC ≥ 19.29 (Visual Studio 2019 16.10+, or VS 2022).
Python	3.8	For the config generator. CI exercises Python 3.13.
git	any recent	For cloning the repository.

The config generator runs on a plain Python install with no extra packages. For its optional <Tab> path-completion, Windows additionally needs the pyreadline3 package (readline is built in on Linux/macOS). Install the script’s Python dependencies with:

pip install -r configs/python_scripts/requirements.txt

This is a no-op on Linux/macOS and pulls in pyreadline3 only on Windows. Without it, Tab simply inserts a tab character.

Optional features (VTK, CSPICE, MPI) are disabled by default and must be enabled explicitly via CMake flags — see Installing additional libraries below.

Requirements¶

Mandatory¶

CMake ≥ 3.10
A C++20 compatible compiler
- Linux: GCC or Clang
- macOS: Apple Clang or GCC
- Windows: MSVC (Visual Studio)
git
Python (≥ 3)

Optional¶

CSPICE — accurate orbital data
VTK — shape models and visualization
MPI implementation (e.g. OpenMPI, MPICH)

CMake configuration options¶

All optional features are OFF by default.

Option	Default	Description
`INCLUDE_CSPICE`	OFF	Enable CSPICE support
`INCLUDE_VTK`	OFF	Enable VTK support
`INCLUDE_MPI`	OFF	Build MPI executable (`mocsi_mpi`)
`CSPICE_DIR`	—	Path to CSPICE installation (required if CSPICE is enabled)

Example:

cmake .. -DINCLUDE_CSPICE=ON -DINCLUDE_VTK=ON

Minimum installation (no optional libraries)¶

Each tab below walks through the minimum steps to clone, configure, and build MoCSI without SPICE or VTK.

Linux

Install CMake, a C++ compiler (we recommend gcc), git and Python:

sudo apt-get update && sudo apt-get install -y build-essential cmake git python3 python3-pip

Navigate to a preferred folder, clone the repository, and enter it:

git clone https://gitlab.git.nrw/uni-ms/ag-gundlach/public/mocsi.git
cd mocsi

Create the build directory and run CMake + make:
```
mkdir build
cd build
cmake ..
make
```
The final executable is called mocsi and lives in build/. See the Quickstart for how to run it.

macOS

Install CMake, a C++ compiler (we recommend gcc), git and Python:
```
brew install cmake gcc git python
```

Navigate to a preferred folder, clone the repository, and enter it:

git clone https://gitlab.git.nrw/uni-ms/ag-gundlach/public/mocsi.git
cd mocsi

Create the build directory and run CMake + make:
```
mkdir build
cd build
cmake ..
make
```
The final executable is called mocsi and lives in build/. See the Quickstart for how to run it.

Windows (MSVC + CMake GUI)

Install git, CMake, Python, and Visual Studio. When opening Visual Studio for the first time, select Desktop Development with C++ to install the MSVC compiler.
Navigate to a preferred folder and clone the repository.
Open the CMake GUI. Click Browse Source and select the MoCSI root folder. Create a new folder for your build files and select it via Browse Build.
Click Configure. You’ll be prompted to pick a generator — choose Visual Studio 17 2022 (or your version) and hit Finish. After a few warnings you should see “Configuration done”.
Click Generate. CMake finishes with “Generate done”.
Click Open Project to open the generated solution in Visual Studio.
In the top bar, pick your compilation configuration: Release for the highest optimization level, or Debug for testing.
In the Solution Explorer, right-click ALL_BUILD and choose Build. It should finish with “Build completed”.
Your executable mocsi.exe lives in build/Debug/ or build/Release/ depending on the configuration you picked. See the Quickstart for how to run it.

Installing additional libraries (optional)¶

Three build-time features extend what MoCSI can do. All are OFF by default — enable what you need with the CMake flags below.

Feature	Version	Default	How to enable	What it unlocks
VTK	9.x	Off	Install system VTK (see below) and pass `-DINCLUDE_VTK=ON` to CMake	Reading shape-model mesh files
SPICE	latest NAIF release	Off	Pass `-DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice` to CMake	Accurate orbital geometry from ephemerides
MPI	any (Open MPI / MPICH / MS-MPI)	Off	Pass `-DINCLUDE_MPI=ON` to CMake (MPI library must be installed)	Parallel execution across processes

SPICE (for accurate orbital data)¶

Linux

Download the correct CSPICE toolkit into your preferred folder. With gcc:

curl -O https://naif.jpl.nasa.gov/pub/naif/toolkit/C/PC_Linux_GCC_64bit/packages/cspice.tar.Z
uncompress cspice.tar.Z
tar -xf cspice.tar

Then re-run the CMake command from step 3, with the SPICE flags:

cmake .. -DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice/

All other steps remain the same.

macOS

Download the correct CSPICE toolkit into your preferred folder:

curl -O https://naif.jpl.nasa.gov/pub/naif/toolkit/C/MacIntel_OSX_AppleC_64bit/packages/cspice.tar.Z
uncompress cspice.tar.Z
tar -xf cspice.tar

Then re-run the CMake command from step 3, with the SPICE flags:

cmake .. -DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice/

All other steps remain the same.

Windows

Download the correct CSPICE toolkit and extract the files to a directory of your choosing.

Open the CMake GUI and click + Add Entry twice. First, enable CSPICE:

Name:  INCLUDE_CSPICE
Type:  BOOL
Value: ON

Then, if your SPICE toolkit is at D:/cspice, set:

Name:  CSPICE_DIR
Type:  Path
Value: D:/cspice

Click OK, then continue from step 4 of the Windows minimum-install instructions. (If you already picked a compiler, clicking Configure skips the prompt and jumps straight to the configuration step.)

VTK (for shape-model support)¶

Linux

Install VTK:

sudo apt-get install -y --no-install-recommends libvtk9-dev

Re-run the CMake command from step 3 with the VTK flag:

cmake .. -DINCLUDE_VTK=ON

macOS

Install VTK via Homebrew:

brew install vtk

Re-run the CMake command from step 3 with the VTK flag:

cmake .. -DINCLUDE_VTK=ON

Windows

Download the latest VTK release and extract it to a folder of your choosing. Follow the same MSVC + CMake GUI flow, but select the VTK folder as Source and a new folder as Build. The Visual Studio build takes a while — make sure you pick the same configuration (Release/Debug) you plan to use for MoCSI.

After VTK builds successfully, add its library folders to your Path system variable:

Open Windows system variables, select Path, click Edit.
Add the ../bin/ and ../lib/Release (or ../lib/Debug/) folders from your VTK install.
Confirm and exit.

Then re-open the CMake GUI for MoCSI and click + Add Entry to enable VTK:

Name:  INCLUDE_VTK
Type:  BOOL
Value: ON

Click OK and continue from step 4 of the Windows minimum-install instructions.

MPI (for parallel execution)¶

When MPI is enabled, the executable is named mocsi_mpi (the serial mocsi is still built alongside).

Linux

Install an MPI implementation, e.g. Open MPI:

sudo apt-get install -y openmpi-bin libopenmpi-dev

Re-run the CMake command from step 3 with the MPI flag and mpicxx:

cmake .. -DINCLUDE_MPI=ON -DCMAKE_CXX_COMPILER=mpicxx

macOS

Install Open MPI via Homebrew:

brew install open-mpi

Re-run the CMake command from step 3 with the MPI flag and mpicxx:

cmake .. -DINCLUDE_MPI=ON -DCMAKE_CXX_COMPILER=mpicxx

Windows

Install Microsoft MPI (both the SDK and the runtime).

In the CMake GUI, click + Add Entry to enable MPI:

Name:  INCLUDE_MPI
Type:  BOOL
Value: ON

Click OK and continue from step 4 of the Windows minimum-install instructions.

Tests¶

Tests are built automatically alongside the main executable. CSPICE-dependent tests are skipped when INCLUDE_CSPICE=OFF. Runtime test data is copied into build/tests/ at configure time.