# Quickstart

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

<div class="step-flow">
  <a class="step-card" href="#get-the-mocsi-executable">
    <span class="step-num">1</span>
    <div class="step-body">
      <b>Get MoCSI</b>
      <span>Download a binary or compile from source</span>
    </div>
  </a>
  <a class="step-card" href="#mocsi-configuration-generator">
    <span class="step-num">2</span>
    <div class="step-body">
      <b>Configure</b>
      <span>Generate the <code>.ini</code> files for your simulation</span>
    </div>
  </a>
  <a class="step-card" href="#start-a-simulation">
    <span class="step-num">3</span>
    <div class="step-body">
      <b>Run</b>
      <span>Launch MoCSI and collect the output</span>
    </div>
  </a>
</div>

## 1. Get the MoCSI executable

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

::::{tab-set}

:::{tab-item} Download a pre-built binary
Download a ready-to-use executable for Linux, macOS, or Windows from the [GitLab releases page](https://gitlab.git.nrw/uni-ms/ag-gundlach/public/mocsi/-/releases).

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

:::{tab-item} Compile from source
Install the required programs for your system (Linux, macOS, or Windows) and follow the compilation steps in the [installation instructions](../installation/installation_instructions.md).
:::

::::

## 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:

```bash
|── 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](https://gitlab.git.nrw/uni-ms/ag-gundlach/public/mocsi).
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](../simulation_options/config_examples/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](../installation/installation_instructions.md#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.

::::{tab-set}

:::{tab-item} Linux / macOS
```bash
./mocsi -i name_of_simulation.ini
```
:::

:::{tab-item} Windows
```powershell
.\mocsi.exe -i name_of_simulation.ini
```
(Command Prompt or PowerShell)
:::

::::