Installation

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

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.

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.

  1. 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

  2. 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

  3. 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.

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

    brew install cmake gcc git python

  2. 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

  3. 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.

  1. 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.

  2. Navigate to a preferred folder and clone the repository.

  3. 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.

  4. 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”.

  5. Click Generate. CMake finishes with “Generate done”.

  6. Click Open Project to open the generated solution in Visual Studio.

  7. In the top bar, pick your compilation configuration: Release for the highest optimization level, or Debug for testing.

  8. In the Solution Explorer, right-click ALL_BUILD and choose Build. It should finish with “Build completed”.

  9. 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

Default

How to enable

What it unlocks

VTK

Off

Install system VTK (see below) and pass -DINCLUDE_VTK=ON to CMake

Reading shape-model mesh files

SPICE

Off

Pass -DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice to CMake

Accurate orbital geometry from ephemerides

MPI

Off

Pass -DINCLUDE_MPI=ON to CMake (MPI library must be installed)

Parallel execution across processes

SPICE (for accurate orbital data)

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.

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.

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)

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

Install VTK via Homebrew:

brew install vtk

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

cmake .. -DINCLUDE_VTK=ON

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:

  1. Open Windows system variables, select Path, click Edit.

  2. Add the ../bin/ and ../lib/Release (or ../lib/Debug/) folders from your VTK install.

  3. 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).

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

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

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.