Quickstart

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

1
Get MoCSI Download a binary or compile from source
2
Configure Generate the .ini files for your simulation
3
Run Launch MoCSI and collect the output

1. Get the MoCSI executable

Pick one of two paths: grab a pre-built binary, or compile MoCSI yourself.

Download a ready-to-use executable for Linux, macOS, or Windows from the GitLab releases page.

Note: pre-built executables do not include VTK support. If you need shape-model I/O, compile from source instead — see the installation instructions.

Install the required programs for your system (Linux, macOS, or Windows) and follow the compilation steps in 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.

Note

Option A users (downloaded executable): 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:

  1. Go to the MoCSI GitLab repository.

  2. On the top bar of the project page, click Code.

  3. Select Download ZIP.

  4. Extract the archive. The script will be located at configs/python_scripts/mocsi_config_generator.py.

Navigate to the script (e.g. ../mocsi/configs/python_scripts/mocsi_config_generator.py) and start it with Python. It will guide you interactively — here’s what it asks:

  1. Absolute path to the /src directory in your MoCSI installation.

  2. Path to the MoCSI executable, including the filename — e.g. build/Release/mocsi.exe for an MSVC Release build.

  3. (Optional) Select a profile. Profiles are pre-defined .ini configurations for common cases — see the profiles overview. Profiles using SPICE or shape models need kernel and shape-model paths.

  4. A simulation name. Used for the simulation directory, the generated .ini file, and the output files.

  5. Where to create the simulation directory. If the directory already exists, you’ll be asked whether to delete its contents — answering No aborts without overwriting.

  6. (Optional) Edit the .ini files to tweak parameters. Some files contain optional keys you may add or remove — see the module and core schemata under ../root/configs for the full reference.

3. Start a simulation

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

./mocsi -i name_of_simulation.ini

.\mocsi.exe -i name_of_simulation.ini

(Command Prompt or PowerShell)