# 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](../installation/installation_instructions.md).

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

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

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
   ```

---

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

1. **Provide the path to `/src`.**  
   Enter the absolute path to the `/src` directory in your MoCSI installation.

2. **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).

3. **(Optional) Select a profile.**  
   Profiles offer pre-defined `.ini` files for different use cases. See the [profiles overview](../configs/config_examples/profiles_overview.md).  
   **Profiles using SPICE or shape models require you to provide paths to kernels and shape model files.**

4. **Choose a simulation name.**  
   This name will be used for the simulation directory, the generated `.ini` file, and the output files.

5. **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).

6. **(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:**
```bash
./mocsi -i name_of_simulation.ini
```

**Windows (Command Prompt or PowerShell):**
```powershell
.\mocsi.exe -i name_of_simulation.ini
```