Quickstart¶

Here you can find instructions on setting up MoCSI and running your first simulation.

1. Get the MoCSI executable¶

To start with MoCSI you can either download the correct executable for your system (A) or compile MoCSI locally (B).

Option A: Download MoCSI executable¶

If you prefer not to compile the source code yourself, you can download a ready-to-use executable for Linux, macOS, or Windows here. Please note that these precompiled executables do not include VTK support.

To use VTK functionality, you must have VTK installed on your system and build the program from source (Option B). Detailed instructions for building with VTK can be found in the installations section.

Option B: Compile MoCSI locally¶

To compile MoCSI locally to generate your executable, you first need to install the reqiured programs for your system (we support Windows, Linux and Mac) and then follow the compilation instructions. For this, we refer to the installation instructions.

2. MoCSI configuration generator¶

Once your executable is generated, you need to generate the MoCSI configuration. The folder structure that MoCSI expects for the simulation config files (default.ini and run.ini) and the module ini files is the following:

|── name_of_simulation                  # User specified name
|   ├── mocsi.exe                       # Or just mocsi for Linux and Mac      
|   ├── ini_files
|   |   ├── default.ini
|   |   ├── name_of_simulation.ini      # Overwrites default.ini (same name as directory)
|   |   ├── albedo                      # Module ini files
|   |   |   ├── Albedo.ini
|   |   |   ├── AlbedoConstantCustom.ini
|   |   ├── density
|   |   .
|   |   .
|   |   .
|   ├── snapshots
|   ├── output

You can either recreate this structure manually or use the mocsi_config_generator.py script.

Important note for Option A users (downloaded executable)

If you downloaded the MoCSI executable directly (without cloning the repository), you still need the mocsi_config_generator.py script. You don’t need to install Git for this — simply download the repository as a .zip file:

Go to the MoCSI GitLab repository.
On the top bar of the project page, click Code.
Select Download ZIP.
Extract the archive. The script will be located at:
```
configs/python_scripts/mocsi_config_generator.py
```

Run the configuration script¶

Navigate to the script (e.g. ../mocsi/configs/python_scripts/mocsi_config_generator.py) and start it with Python.
It will guide you interactively, but here’s an overview of the steps:

Provide the path to /src.
Enter the absolute path to the /src directory in your MoCSI installation.
Provide the path to the MoCSI executable.
This must include the file itself. For example:
```
build/Release/mocsi.exe
```
(when using MSVC in Release configuration).
(Optional) Select a profile.
Profiles offer pre-defined .ini files for different use cases. See the profiles overview.
Profiles using SPICE or shape models require you to provide paths to kernels and shape model files.
Choose a simulation name.
This name will be used for the simulation directory, the generated .ini file, and the output files.
Choose where to create the simulation directory.
- If the directory already exists, you’ll be asked whether to delete its contents.
- If you select No, the process will stop (the script will not overwrite existing files).
(Optional) Edit .ini files.
- You can review and modify parameters.
- Some .ini files contain optional parameters you may wish to add or remove.
- For detailed reference, consult the module and core schemata in ../root/configs.

3. Start a simulation¶

Once your configuration is ready, navigate to your simulation directory and run the executable with your .ini file:

Linux/Mac:

./mocsi -i name_of_simulation.ini

Windows (Command Prompt or PowerShell):

.\mocsi.exe -i name_of_simulation.ini