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. If you run the script from inside a MoCSI checkout, it auto-detects this — just press Enter to accept the suggested default.

  2. Path to the MoCSI executable, including the filename — e.g. build/Release/mocsi.exe for an MSVC Release build. If a binary is found in a standard build directory, it is offered as a default; press Enter to accept it.

  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. Use a dedicated directory outside the MoCSI source folder rather than somewhere inside the source tree. Press Enter to use the current 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.

Note

At every path prompt you can press Tab to auto-complete files and directories. On Windows this needs the pyreadline3 package (pip install -r configs/python_scripts/requirements.txt, see Requirements); without it, Tab just inserts a tab character (the script tells you this on startup). Linux and macOS work out of the box. Quoted string values in .ini files (paths, labels, …) may also contain spaces and tab characters; they are preserved verbatim when the generator reads and rewrites a file.

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)