# 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.
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](../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. 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.

::::{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)
:::

::::