# 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
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:
## 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:
1. A source file for the module lives in the `modules/` folder.
2. 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.
```{dropdown} Albedo
Bolometric Bond albedo for each facet.
| Submodule | Description |
|-----------|-------------|
| `AlbedoConstantCustom` | Constant user supplied value |
```
```{dropdown} 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) |
```
```{dropdown} Emissivity
Emissivity for each facet.
| Submodule | Description |
|-----------|-------------|
| `EmissivityConstantCustom` | Constant user supplied value |
```
```{dropdown} FluxSmoothingTool
Dynamic time step reduction (Schörghofer & Khatiwala 2024). No submodules.
```
```{dropdown} 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) |
```
```{dropdown} 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) |
```
```{dropdown} HeatSource
Additional heat sources/sinks for each element.
| Submodule | Description |
|-----------|-------------|
| `HeatSourceConstantCustom` | Constant user supplied value |
```
```{dropdown} HeliocentricDistance
Distance between the Sun and the target.
| Submodule | Description |
|-----------|-------------|
| `HeliocentricDistanceConstantCustom` | Constant user supplied value |
| `HeliocentricDistanceSpice` | Distance calculated through given SPICE kernels |
```
```{dropdown} OutputCsvTool
Saves field values while the simulation is still running. No submodules.
```
```{dropdown} RuntimeProgressTool
Outputs current simulation progress. No submodules.
```
