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¶

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.
`_snaphsot_keep_sim`	Prevents overwrite of the current `default.ini` and `run.ini` values when loading the snapshot.
`_snaphsot_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.

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

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

Parameter	Description
`user_supplied_albedo`	The custom bolometric Bond albedo value.
`submodules`	Common — see above.
`dependencies`	Common — see above.

Density

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

DensityConstantCustom.ini

Parameter	Description
`user_suplied_density`	The custom bulk density value in kg m\(^{-3}\).
`submodules`	Common — see above.
`dependencies`	Common — see above.

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

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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

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

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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.

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.

Heat conductivity

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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.

HeatConductivityConstantMaxwell1873PorousRockSolid.ini

Parameter	Description
`porosity`	The porosity (1 − volume filling factor) of the rock.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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.

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.

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.

Heat source

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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.

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

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.

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

Runtime progress

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

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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.

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.

Parameter	Description
`submodules`	Common — see above.
`dependencies`	Common — see above.

Solar vector

Parameter	Description
`chain_insertion`	Common — see above.
`submodules`	Common — see above.
`dependencies`	Common — see above.

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.

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.