Modules¶

Modules are the building blocks of a MoCSI simulation — they compute physical properties, drive boundary conditions, and write output. Understanding them comes down to three things:

🧩

Module types Managing modules vs. submodules and their permissions

⏱️

Insertion points When in the simulation a module runs

🔌

Wiring it up Registering, configuring, and ordering modules

Module types¶

There are multiple modules available, split into managing modules and submodules. Structurally they are similar but have different permissions and concerns.

A managing module can hold a physical field variable (and usually does). The field variable is also present within the core code; the managing module is responsible for writing into it and maintaining it during the simulation. Every managing module can have an arbitrary number of submodules, which perform tasks related to maintaining the field variable.

Submodules have only read access to the core code. They communicate their results to a managing module in order to affect the simulation. Submodules can themselves have an arbitrary number of child submodules — enabling hierarchical reuse (e.g. equations that perform the same operations on different materials implemented once and specialized via nesting). This is illustrated below:

Managing modules and submodule hierarchy

Module insertion points¶

Module insertion points (MIPs) are places in the core code where the module framework is invoked — points where modules can run and interact with the simulation environment. In the default configuration MoCSI has 5 MIPs:

MIP	Code name	When it runs
Initialization	`InitChain`	Once, directly after the grid has been built and before the time-stepping loop
Pre-time-step	`PreTimeStepChain`	At the start of each time step, before anything else is calculated
Post-time-step	`PostTimeStepChain`	After the temperatures have been updated
Post-non-linear-iterations	`PostNonLinIterChain`	After the time step has converged and been accepted (equivalent to Post-time-step if the model has no non-linear components)
Output	`OutputChain`	Directly before exiting the simulation environment

The same module can be inserted into multiple MIPs and can do different work at each — every module has a corresponding function per MIP. This is what enables complex applications on top of the module framework.

Working with modules¶

MoCSI registers a module automatically when both of these are true:

A source file for the module lives in the modules/ folder.
The module is loaded in module_factory.cpp for the simulation data type in use (default: double).

Registered modules aren’t loaded by default — you opt them in through their .ini file (in the ini_files/ folder) using three parameters:

chain_insertion — lists the MIPs the managing module should run in (e.g. "InitChain", "PreTimeStepChain"). Set to "None" to register the module but not load it.
submodules — names any submodules to load beneath this module. They execute before their supervising module, so chains build bottom-up from the deepest submodule to the managing module.
dependencies — names other modules that must run first within the same MIP. MoCSI resolves the dependency graph automatically and throws an error if a dependency is missing or a cycle is detected.

Current modules¶

Each managing module is listed below with a short description of its role. Expand an entry to see its available submodules.

Submodule	Description
`AlbedoConstantCustom`	Constant user supplied value

Density

Bulk density of all elements.

Submodule	Description
`DensityConstant`	Const. literature values by asteroid type
`DensityConstantCustom`	Constant user supplied value
`DensityConstantGundlach2013RegolithSolidAsteroidType`	Const. literature values by asteroid type (Gundlach & Blum 2013)

Submodule	Description
`EmissivityConstantCustom`	Constant user supplied value

HeatCapacity

Specific heat capacity of all elements.

Submodule	Description
`HeatCapacityConstantCustom`	Constant user supplied value
`HeatCapacityConstantOpeil2010NonPorousRockSolidAsteroidType`	Const. literature values by asteroid type (Opeil et al. 2010)

HeatConductivity

Bulk thermal conductivity of each element.

Submodule	Description
`HeatConductivityConstantCustom`	Constant user supplied value
`HeatConductivityConstantMaxwell1873PorousRockSolid`	Model description of Maxwell (1873)
`HeatConductivityTwoLayers`	Merges two thermal conductivities at given depth
`HeatConductivityVariableGundlach2013NonPorousRockSolidAsteroidType`	Const. literature values by asteroid type (Gundlach & Blum 2013)
`HeatConductivityVariableGundlach2013RegolithSolid`	Model description of Gundlach & Blum (2013)

Submodule	Description
`HeatSourceConstantCustom`	Constant user supplied value

HeliocentricDistance

Distance between the Sun and the target.

Submodule	Description
`HeliocentricDistanceConstantCustom`	Constant user supplied value
`HeliocentricDistanceSpice`	Distance calculated through given SPICE kernels