# Model parameters

## Explanation of parameters

MoCSI can be controlled fully through setting parameters in the ini files present in the `/ini_files/` folder of the code. There are two types of ini files: **core ini files** and **module ini files**.

Only two of the ini files in that folder belong to the core, the `default.ini` and the `run.ini`. The `default.ini` must always be present, as it contains all the parameters that need to be set for the model to run with their default parameters. To change these default values, you should overwrite them with the `run.ini` as all values within that ini file can be used to overwrite the default values. It is advised to not change any value within the `default.ini` and only work with the `run.ini`.

Each module ini file belongs to the corresponding module with which it shares a name. These ini files can only be used to change behavior *within* the corresponding module. Despite there being parameters which some modules share, each have to be set within their own ini file.

## Parameter reference

`````{tab-set}

````{tab-item} Core

Parameters below belong to `default.ini`. The `run.ini` file accepts every one of them and always takes priority — prefer editing `run.ini` over changing `default.ini`.

### Time parameters

| Parameter | Description |
|-----------|-------------|
| `time_delta` | The time step length in seconds (s). |
| `time_max` | The total simulation time in seconds (s). |

### Inner iteration options

| Parameter | Description |
|-----------|-------------|
| `inner_iterations` | The maximum number of internal iterations ran to achieve convergence for non-linear models. A warning is passed if convergence is not reached. |
| `epsilon_inner_iterations` | The allowed difference between two inner iteration steps to be considered converged in Kelvin (K). Once $T_{inner, i+1} - T_{inner, i} \leq \epsilon$, the time step is accepted. |

### Grid options

| Parameter | Description |
|-----------|-------------|
| `spatial_dimension` | Only `"1D"` currently implemented. If set to `"1D"` and `used_shape_file = true`, will look for a shape model to load under `shape_model_path`. |
| `cell_length` | The length of each FEM element when using a **uniform grid**. Used during uniform grid creation together with `numerical_layers`. Either this or `max_depth` must be present. |
| `numerical_layers` | The number of temperature nodes **(not elements)** within each facet. |
| `max_depth` | The maximum depth of a facet domain in meters (m). Used during uniform grid creation together with `numerical_layers`. Either this or `cell_length` must be present. |
| `grid` | Path to a file containing the node depths to be used for grid creation. Supports any non-uniform grid. |

### Initial temperature

| Parameter | Description |
|-----------|-------------|
| `initial_temperature` | The initialization temperature of the model in Kelvin (K). |

### Ini folder path

| Parameter | Description |
|-----------|-------------|
| `ini_folder_path` | The (relative) path where the model should look for the rest of the ini files. Best practice is to keep them all in one place — by default `"../ini_files/"`. |

### Shape model

| Parameter | Description |
|-----------|-------------|
| `use_shape_file` | Whether a shape file should be loaded. |
| `shape_model_option` | Currently only `"1D"`. With `use_shape_file = true`, runs a 1D heat transfer simulation on each facet. Higher dimensions will be supported in the future. |
| `shape_model_path` | Path to a VTK-readable mesh file (VTK required). Supported: `.ply`, `.vtp`, `.obj`, `.stl`, `.vtk`, `.g`. |

### Finite Element Method options

| Parameter | Description |
|-----------|-------------|
| `cell_type` | Element type used in the FEM. Currently only `"OneDimLinearElement"`. |

### Boundary condition options

| Parameter | Description |
|-----------|-------------|
| `top_boundary_condition_type` | Top domain boundary condition for each facet. One of: `"BCTopSurfaceEnergyBalance"`, `"BCSinusoidalTemperature"`, `"BCConstantHeatFlux"`. |
| `bottom_boundary_condition_type` | Bottom domain boundary condition for each facet. Same options as above. |
| `boundary_temperture` | Helper field for iterative boundary conditions. Use `"IterativeSurfaceTemperature"` when the boundary needs iteration, else `"Temperature"`. |
| `top_boundary_heat_flux` | Heat flux in W m$^{-2}$, when `"BCConstantHeatFlux"` is chosen as the top boundary condition. |
| `bottom_boundary_heat_flux` | Heat flux in W m$^{-2}$, when `"BCConstantHeatFlux"` is chosen as the bottom boundary condition. |
| `top_temperature_amplitude` | Amplitude of the sinusoidal temperature wave in Kelvin (K), for the top boundary condition `"BCSinusoidalTemperature"`. |
| `bottom_temperature_amplitude` | Amplitude of the sinusoidal temperature wave in Kelvin (K), for the bottom boundary condition `"BCSinusoidalTemperature"`. |
| `top_period` | Period of the sinusoidal temperature wave in seconds (s), for the top boundary condition. |
| `bottom_period` | Period of the sinusoidal temperature wave in seconds (s), for the bottom boundary condition. |

### Snapshot options

| Parameter | Description |
|-----------|-------------|
| `snapshot` | Path to the MoCSI snapshot file to load for this simulation. |
| `_snapshot_keep_sim` | Prevents overwrite of the current `default.ini` and `run.ini` values when loading the snapshot. |
| `_snapshot_keep_module` | Prevents overwrite of all current module ini file values when loading the snapshot. |
| `snapshot_save_file` | Path to save the MoCSI snapshot at simulation end. |

````

````{tab-item} Modules

Most module `.ini` files share a small set of common parameters. They appear in every table below:

| Common parameter | Description |
|------------------|-------------|
| `chain_insertion` | Managing-module-only. Module Insertion Points where this managing module is loaded. One of `"InitChain"`, `"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"`, `"OutputChain"`, or `"None"` to disable. |
| `submodules` | The submodules to be loaded beneath this module. Use `"None"` if there are none. |
| `dependencies` | The module's dependencies, if any. |

### Albedo

```{dropdown} Albedo.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} AlbedoConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_albedo` | The custom bolometric Bond albedo value. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Density

```{dropdown} Density.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} DensityConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_suplied_density` | The custom bulk density value in kg m$^{-3}$. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} DensityConstantGundlach2013RegolithSolidAsteroidType.ini
| Parameter | Description |
|-----------|-------------|
| `asteroid_type` | The spectral class of the target asteroid type. Currently: `"S"`, `"M"`, `"C"`, `"Q"`. |
| `volume_filling_factor` | The volume filling factor of the regolith. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Emissivity

```{dropdown} Emissivity.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} EmissivityConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_emissivity` | The custom emissivity value in the thermal infrared. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Flux smoothing

```{dropdown} FluxSmoothingTool.ini
| Parameter | Description |
|-----------|-------------|
| `upper_threshold` | Triggers flux smoothing when the current time step overshoots the previous one by this factor. |
| `lower_threshold` | Triggers flux smoothing when the current time step undershoots the previous one by this factor. |
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Heat capacity

```{dropdown} HeatCapacity.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatCapacityConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_heat_capacity` | The custom specific heat capacity value in J kg$^{-1}$ K$^{-1}$. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatCapacityConstantOpeil2010NonPorousRockSolidAsteroidType.ini
| Parameter | Description |
|-----------|-------------|
| `asteroid_type` | The spectral class of the target asteroid type. Currently: `"S"`, `"M"`, `"C"`, `"Q"`. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatCapacityVariableCustomPolynomial.ini
| Parameter | Description |
|-----------|-------------|
| `coefficient A` | The coefficient A for c(T) = A + B*T + C*T**2 + D*T**3. |
| `coefficient B` | The coefficient A for c(T) = A + B*T + C*T**2 + D*T**3. |
| `coefficient C` | The coefficient A for c(T) = A + B*T + C*T**2 + D*T**3. |
| `coefficient D` | The coefficient A for c(T) = A + B*T + C*T**2 + D*T**3. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```


### Heat conductivity

```{dropdown} HeatConductivity.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatConductivityConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_heat_conductivity` | The custom bulk heat conductivity value in W m$^{-1}$ K$^{-1}$. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatConductivityConstantMaxwell1873PorousRockSolid.ini
| Parameter | Description |
|-----------|-------------|
| `porosity` | The porosity (1 − volume filling factor) of the rock. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatConductivityTwoLayers.ini
| Parameter | Description |
|-----------|-------------|
| `transition_depth` | The depth of the layer transition in meters (m). |
| `use_upper_hc_on_node` | If `true`, the upper layer's conductivity is used when the transition falls exactly on a node; otherwise the lower layer's. |
| `submodules` | Two submodules must be loaded: the first is used in the upper layer (surface → `transition_depth`), the second in the lower layer (`transition_depth` → max depth). |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatConductivityVariableGundlach2013NonPorousRockSolidAsteroidType.ini
| Parameter | Description |
|-----------|-------------|
| `asteroid_type` | The spectral class of the target asteroid type. Currently: `"S"`, `"M"`, `"C"`, `"Q"`. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatConductivityVariableGundlach2013RegolithSolid.ini
| Parameter | Description |
|-----------|-------------|
| `poissons_ration` | Poisson's ratio of the material. |
| `youngs_modulus` | The Young's modulus of the material. |
| `f1` | The $f_1$ fit parameter from Gundlach and Blum (2012). |
| `f2` | The $f_2$ fit parameter from Gundlach and Blum (2012). |
| `chi` | The angular and polydisperse particle adaption factor from Gundlach and Blum (2013). |
| `e1` | The $e_1$ fit parameter from Gundlach and Blum (2012). |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatConductivityVariableKiradjiev2019PorousRockSolidRadiation.ini
| Parameter | Description |
|-----------|-------------|
| `porosity` | The porosity (1 − volume filling factor) of the rock. |
| `pore_space_diameter` | The pore space diameter of the rock. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Heat source

```{dropdown} HeatSource.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeatSourceConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_heat_source` | The custom heat source or sink value in W m$^{-2}$. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Heliocentric distance

```{dropdown} HeliocentricDistance.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeliocentricDistanceConstant.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_heliocentric_distance` | The custom heliocentric distance value in astronomical units (AU). |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} HeliocentricDistanceVariableSpice.ini
| Parameter | Description |
|-----------|-------------|
| `spice_metakernel_path` | Path to the SPICE metakernel file. |
| `object_id` | SPICE object ID of the target body. |
| `reference_frame_id` | SPICE reference frame (usually `"J2000"`). |
| `start_time_utc` | Starting time for the simulation in UTC (`YYYY-MM-DDThh:mm:ss`). |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Output

```{dropdown} OutputToolCsv.ini
| Parameter | Description |
|-----------|-------------|
| `file_path` | Path and name of the CSV file that will be saved. |
| `save_fields` | Names of the field values to be saved, comma-separated. |
| `save_mode` | How the selected fields should be saved: `"specific_time_steps"` (on time steps in `save_time_steps`), `"interval"` (every `interval` steps), `"interval_surface"` (surface values only, every `interval` steps). |
| `interval` | Interval of time steps at which the field values should be saved (when `save_mode` uses it). |
| `save_time_steps` | Specific time steps at which field values should be saved (when `save_mode = "specific_time_steps"`). |
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} TemperatureSaverIterationsTool.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Runtime progress

```{dropdown} RuntimeProgressTool.ini
| Parameter | Description |
|-----------|-------------|
| `iteration_interval` | Number of time steps between progress reports. |
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Solar flux

```{dropdown} SolarFlux.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} SolarFluxConstantCustom.ini
| Parameter | Description |
|-----------|-------------|
| `user_supplied_solar_flux` | The custom incoming solar flux value in W m$^{-2}$. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} SolarFluxVariableCustomSinusoidal.ini
| Parameter | Description |
|-----------|-------------|
| `period` | Period of the day-night cycle in seconds (s). |
| `declination` | Declination of the surface on a sphere in degrees (°). |
| `latitude` | Latitude of the surface on a sphere in degrees (°). |
| `slope_angle` | Slope angle of the surface against the normal of the sphere in degrees (°). |
| `azimuth_topo_grad` | Azimuth of the topographic gradient against a specified prime meridian in degrees (°). |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} SolarFluxVariablePotter2023Radiosity.ini
| Parameter | Description |
|-----------|-------------|
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

### Solar vector

```{dropdown} SolarVector.ini
| Parameter | Description |
|-----------|-------------|
| `chain_insertion` | Common — see above. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} SolarVectorConstant.ini
| Parameter | Description |
|-----------|-------------|
| `polar_angle` | Angle between the solar vector and the z-axis in degrees (°). |
| `azimuth` | Angle in the x-y plane measured from the x-axis in degrees (°). |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

```{dropdown} SolarVectorSpice.ini
| Parameter | Description |
|-----------|-------------|
| `spice_metakernel_path` | Path to the SPICE metakernel file. |
| `object_id` | SPICE object ID of the target body. |
| `reference_frame_id` | SPICE reference frame (usually `"J2000"`). |
| `start_time_utc` | Starting time for the simulation in UTC (`YYYY-MM-DDThh:mm:ss`). |
| `rotating_frame_id` | SPICE frame ID of the body-fixed frame of the target body. |
| `submodules` | Common — see above. |
| `dependencies` | Common — see above. |
```

````

`````