# Model parameter
## 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 files belongs to the corresponding module with which it shares a name. These ini files can only be used to change behavior *within* the correspondig module. Despite there being parameters which some modules share, each have to be set within their own ini file.

## List of available parameters

The following is a list of all parameters for all ini files:

### Core ini file

`default.ini`

- Time Parameters:
    - `time_delta` - The time step length in seconds (s).
    - `time_max` - The total simulation time in seconds (s).
- Inner iteration options:
    - `inner_iterations` - The maximum number of internal iterations ran to achieve convergence for non-linear models (if not achieved in the specified number, a warning will be passed to the user).
    - `epsilon_inner_iterations` - The allowed difference between to inner iteration steps to be considered converged in Kelvin (K). Once $T_{inner, i+1} - T_{inner, i} \leq \epsilon$, it will accept the time step.
- Grid options:
    - `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 Finite Element Method element when using a **uniform grid**. Is used during uniform grid creation together with `numerical_layers`. (Either this or `max_depth` needs to be present together with `numerical_layers`.)
    - `numerical_layers` - The number of temperature nodes **(not elements)** within each facet.
    - `max_depth` - The maximum depth of a facet domain in meters (m). Is used during uniform grid creation together with `numerical_layers`. (Either this or `cell_length` needs to be present together with `numerical_layers`).
    - `grid` - A path to a file containing the node depths to be used for the grid creation. Can be any form of non-uniform grid.
- Initial temperature
    - `initial_temperature` - The initialization temperature of the model in Kelvin (K).
- Ini folder path
    - `ini_folder_path` - The (relative) path where the model should look for the rest of the ini files. Usually it is best practice to have all at the same place, as it looks for the default ini file in `"../ini_files/"`.
- Shape model
    - `use_shape_file` - Whether a shape file should be loaded or not.
    - `shape_model_option` - Currently, only "1D" is implemented. When `use_shape_file` is set to true, will run a 1D heat transfer equation simulation on each facet of the shape model. Higher dimensions will be supported in the future.
    - `shape_model_path` - A path to a file containing a VTK readable mesh file (VTK must be installed on your machine for it to work), being .ply/.vtp/.obj/.stl/.vtk/.g file formats.
- Finite Element Method options
    - `cell_type` - The type of element to be used in the Finite Element Method. Currently only `"OneDimLinearElement"` implemented.
- Boundary condition options
    - `top_boundary_condition_type` - The top domain boundary condition for each facet. Currently implemented: `"BCTopSurfaceEnergyBalance"`, `"BCSinusoidalTemperature"`, `"BCConstantHeatFlux"`.
    - `bottom_boundary_condition_type` - The bottom domain boundary condition for each facet. Currently implemented: `"BCTopSurfaceEnergyBalance"`, `"BCSinusoidalTemperature"`, `"BCConstantHeatFlux"`.
    - `boundary_temperture` - A helper field needed for when the boundary condition also needs to be iterated. Chose `"IterativeSurfaceTemperature"` in this case and `"Temperature"` else.
    - `top_boundary_heat_flux` - The amount of heat flux in Watt per square meter (W m$^{-2}$), for when `"BCConstantHeatFlux` is chosen as the top boundary condition.
    - `bottom_boundary_heat_flux` - The amount of heat flux in Watt per square meter (W m$^{-2}$), for when `"BCConstantHeatFlux` is chosen as the bottom boundary condition.
    - `top_temperature_amplitude` - The amplitude of the sinusoidal temperature wave in Kelvin (K), for when `"BCSinusoidalTemperature` is chosen as the top boundary condition.
    - `bottom_temperature_amplitude` - The amplitude of the sinusoidal temperature wave in Kelvin (K), for when `"BCSinusoidalTemperature` is chosen as the bottom boundary condition.
    - `top_period` - The period of the sinusoidal temperature wave in seconds (s), for when `"BCSinusoidalTemperature` is chosen as the top boundary condition.
    - `bottom_period` - The period of the sinusoidal temperature wave in seconds (s), for when `"BCSinusoidalTemperature` is chosen as the bottom boundary condition.
- Snapshot options
    - `snapshot` - Path to the MoCSI snapshot file that should be loaded for this simulation
    - `_snaphsot_keep_sim` - Prohibits overwrite of the current `default.ini` and `run.ini` values when loading the snapshot.
    - `_snaphsot_keep_module` - Prohibits overwrite of all current module ini file values when loading the snapshot.
    - `snapshot_save_file` - Path to save MoCSI snapshot at simulation end.


`run.ini`
- All options from `default.ini` are allowed in this ini file. Values in this ini file **always** take priority over default values.

### Module ini files

`Albedo.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`AlbedoConstantCustom.ini`
- `user_supplied_albedo` - The custom bolometric Bond albedo value.
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`Density`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`DensityConstantCustom`
- `user_suplied_density` - The custom bulk density value in kilogram per cubic meters (kg m$^{-3}$).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`DensityConstantGundlach2013RegolithSolidAsteroidType`
- `asteroid_type` - The spectral class of the target asteroid type. Currently implemented are `"S"`, `"M"`, `"C"` and `"Q"`.
- `volume_filling_factor` - The volume filling factor of the regolith.
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`Emissivity.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`EmissivityConstantCustom.ini`
- `user_supplied_emissivity` - The custom emissivity value in the thermal infrared.
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`FluxSmoothingTool.ini`
- `upper_threshold` - The factor that determines when flux smoothing is triggered when the temperature of the current time step overshoots the temperature of the previous timestep times the upper threshold.
- `lower_threshold` - The factor that determines when flux smoothing is triggered when the temperature of the current time step undershoots the temperature of the previous timestep times the lower threshold.
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`HeatCapacity.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`HeatCapacityConstantCustom.ini`
- `user_supplied_heat_capacity` - The custom specific heat capacity value in Joule per kilogram and Kelvin (J kg$^{-1}$ K$^{-1}$).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeatCapacityConstantOpeil2010NonPorousRockSolidAsteroidType`
- `asteroid_type` - The spectral class of the target asteroid type. Currently implemented are `"S"`, `"M"`, `"C"` and `"Q"`.
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeatConductivity.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`HeatConductivityConstantCustom.ini`
- `user_supplied_heat_conductivity` - The custom bulk heat conductivity value in Watt per meter and Kelvin (W m$^{-1}$ K$^{-1}$).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeatConductivityConstantMaxwell1873PorousRockSolid.ini`
- `porosity` - The porosity (1 - volume filling factor) of the rock.
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeatConductivityTwoLayers`
- `transition_depth` - The depth of the layer transition in meter (m).
- `use_upper_hc_on_node` - If true, the heat conductivity of the upper layer will be used, if the layer transition falls exactly on a node. Uses the lower layer one if false.
- `submodules` - There have to be two submodules loaded for the module to function correctly. The first loaded module is used in the upper layer (surface to `transition_depth`) and the second loaded module is used in the lower layer (`transition_depth` to maximum depth)
- `dependencies` - The modules dependencies, if there are any.

`HeatConductivityVariableGundlach2013NonPorousRockSolidAsteroidType`
- `asteroid_type` - The spectral class of the target asteroid type. Currently implemented are `"S"`, `"M"`, `"C"` and `"Q"`.
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeatConductivityVariableGundlach2013RegolithSolid.ini`
- `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 $e1$ fit parameter from Gundlach and Blum (2012).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeatSource.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`HeatSourceConstantCustom.ini`
- `user_supplied_heat_source` - The custom heat source or sink value in Watt per meter squared (W m$^{-2}$).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeliocentricDistance.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`HeliocentricDistanceConstant.ini`
- `user_supplied_heliocentric_distance` - The custom heliocentric distance value in astromicals units (AU).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`HeliocentricDistanceVariableSpice.ini`
- `spice_metakernel_path` - The path to the SPICE metakernel file.
- `object_id` - The SPICE object ID of the target body.
- `reference_frame_id` - The SPICE reference frame (usually `"J2000"`).
- `start_time_utc` - The starting time for the simulation of the target body in UTC format (YYYY-MM-DDThh:mm:ss).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`OutputToolCsv.ini`
- `file_path` - The path and name of the csv file that will be saved.
- `save_fields` - The names of the field values to be saved, separated by commas.
- `save_mode` - How the selected fields should be saved. Currently implemented: `"specific_time_steps"`, saves the fields on the time steps specified in `save_time_steps`. `"interval"` saves the fields on a specific interval specified by `interval`. `"interval_surface"` saves only the surface values of the fields on a specific interval specified by `interval`.
- `interval` - The interval of time steps at which the field values should be saved, if the corresponding `save_mode` was selected.
- `save_time_steps` - The time steps at which the field values should be saved, if the corresponding `save_mode` was selected.
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`RuntimeProgressTool.ini`
- `iteration_interval` - Number of time steps between progress reports.
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`SolarFlux.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`SolarFluxConstantCustom.ini`
- `user_supplied_solar_flux` - The custom incoming solar flux value in Watt per meter squared (W m$^{-2}$).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`SolarFluxVariableCustomSinusoidal`
- `period` - The period of the day-night-cycle in seconds (s).
- `declination` - The declination of the surface on a sphere in degrees (°).
- `latitude` - The latitude of the surface on a sphere in degrees (°).
- `slope_angle` - The slope angle of the surface against the normal of the sphere in degrees (°).
- `azimuth_topo_grad` - Azimuth of the topographic gradient agains a specified prime meridian in degrees (°).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`SolarFluxVariablePotter2023Radiosity`
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`SolarVector.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.

`SolarVectorConstant.ini`
- `polar_angle` - Angle between the solar vector and the z-axis in degrees (°).
- `azimuth` - Angle in x-y axis measured from the x-axis in degrees (°).
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`SolarVectorSpice.ini`
- `spice_metakernel_path` - The path to the SPICE metakernel file.
- `object_id` - The SPICE object ID of the target body.
- `reference_frame_id` - The SPICE reference frame (usually `"J2000"`).
- `start_time_utc` - The starting time for the simulation of the target body in UTC format (YYYY-MM-DDThh:mm:ss).
- `rotating_frame_id` - The SPICE frame ID of the body-fixed frame of the target body. 
- `submodules` - The submodules to be loaded beneath this module, if there are any.
- `dependencies` - The modules dependencies, if there are any.

`TemperatureSaverIterationsTool.ini`
- `chain_insertion` - The Module Insertion Points in which this managing module should be loaded. Default available chains are `"InitChain"`,`"PreTimeStepChain"`, `"PostTimeStepChain"`, `"PostNonLinIterChain"` and `"OutputChain"`. If this managing module should not be loaded, use `"None"`.
- `submodules` - The submodules to be loaded beneath this module. If there are none, use `"None"`.
- `dependencies` - The modules dependencies, if there are any.