relax: Doxygen documentation

namespace soil_simulator

Functions

void RelaxTerrain(SimOut *sim_out, Grid grid, Body *body, SimParam sim_param, float tol)

This function moves the soil in terrain_ towards a state closer to equilibrium.

The soil stability is determined by the repose_angle_. If the slope formed by two neighbouring soil columns exceeds the repose_angle_, it is considered unstable, and the soil from the higher column should avalanche to the neighbouring column to reach an equilibrium state.

By convention, this function only checks the stability of the soil in the four adjacent cells: ↑ ← O → ↓

The diagonal directions are not checked for simplicity and performance reasons.

This function only moves the soil when the following conditions are met:

(1) The soil column in the neighbouring cell is low enough. (2) Either: (a) The body is not on the soil, meaning there is space between the terrain_ and the body, or there is no body. (b) The body is on the terrain_, but the combination of the body and body soil is not high enough to prevent soil avalanche.

In case (2a), the soil will avalanche on the terrain_, while in case (2b), the soil will avalanche on the body.

Parameters:

sim_out – Class that stores simulation outputs.
grid – Class that stores information related to the simulation grid.
body – Class that stores information related to the body object.
sim_param – Class that stores information related to the simulation.
tol – Small number used to handle numerical approximation errors.

void RelaxBodySoil(SimOut *sim_out, Grid grid, Body *body, SimParam sim_param, float tol)

This function moves the soil in body_soil_ towards a state closer to equilibrium.

The soil stability is determined by the repose_angle_. If the slope formed by two neighbouring soil columns exceeds the repose_angle_, it is considered unstable, and the soil from the higher column should avalanche to the neighbouring column to reach an equilibrium state.

By convention, this function only checks the stability of the soil in the four adjacent cells: ↑ ← O → ↓

The diagonal directions are not checked for simplicity and performance reasons.

This function only moves the soil when the following conditions are met:

(1) The soil column in the neighbouring cell is low enough. (2) There is space on the top of the neighbouring soil column.

Parameters:

sim_out – Class that stores simulation outputs.
grid – Class that stores information related to the simulation grid.
body – Class that stores information related to the body object.
sim_param – Class that stores information related to the simulation.
tol – Small number used to handle numerical approximation errors.

std::vector<std::vector<int>> LocateUnstableTerrainCell(SimOut *sim_out, float dh_max, float tol)

This function locates all the cells in terrain_ that have a height difference larger than dh_max with at least one neighbouring cell.

It is important to note that the cells selected by this function are not necessarily unstable, as a body or the soil resting on it could be supporting the soil column. This is only a first-order selection of cells potentially unstable.

Parameters:

sim_out – Class that stores simulation outputs.
dh_max – Maximum height difference allowed between two neighbouring cells. [m]
tol – Small number used to handle numerical approximation errors.

Returns:

Collection of cells indices that are possibly unstable.

int CheckUnstableTerrainCell(SimOut *sim_out, int ii_c, int jj_c, float h_min, float tol)

This function checks the stability of a soil column in terrain_ compared to one of its neighbour (ii_c, jj_c)

In case of instability, this function returns a two-digit number (status) that provides information on how the soil should avalanche. The interpretation of the two-digit number is described below.

The first digit indicates the potential presence of the body:

1 when the first body layer is present.
2 when the second body layer is present.
3 when the two body layers are present.
4 when no body layer is present.

The second digit indicates the layer where the soil should avalanche:

0 when it is the terrain` (no body is present).
1 when it is the second body soil layer.
2 when it is the second body layer.
3 when it is the first body soil layer.
4 when it is the first body layer.

The combination of these two digits provides a comprehensive description of how the soil should avalanche in different scenarios.

Note that not all combinations for status are possible. Some combinations, such as 41 or 23 are impossible.

Parameters:

sim_out – Class that stores simulation outputs.
ii_c – Index of the neighbouring cell in the X direction.
jj_c – Index of the neighbouring cell in the Y direction.
h_min – Minimum allowed height for a stable configuration. [m]
tol – Small number used to handle numerical approximation errors.

Returns:

Two-digit number indicating how the soil should avalanche. 0 is returned if the soil column is stable.

int CheckUnstableBodyCell(SimOut *sim_out, int ii, int jj, int ind, int ii_c, int jj_c, float h_min, float tol)

This function checks the stability of a soil column in the soil layer ind of body_soil_ at (ii, jj) compared to one of its neighbour at (ii_c, jj_c).

In case of instability, this function returns a two-digit number (status) that provides information on how the soil should avalanche. The interpretation of the two-digit number is described below.

The first digit indicates the potential presence of the body:

1 when the first body layer is present.
2 when the second body layer is present.
3 when the two body layers are present.
4 when no body layer is present.

The second digit indicates the layer where the soil should avalanche:

0 when it is the terrain (no body is present).
1 when it is the second body soil layer.
2 when it is the second body layer.
3 when it is the first body soil layer.
4 when it is the first body layer.

The combination of these two digits provides a comprehensive description of how the soil should avalanche in different scenarios.

Note that not all combinations for status are possible. Some combinations, such as 41 or 23 are impossible.

Parameters:

sim_out – Class that stores simulation outputs.
ii – Index of the considered cell in the X direction.
jj – Index of the considered cell in the Y direction.
ind – Index of the considered soil layer.
ii_c – Index of the neighbouring cell in the X direction.
jj_c – Index of the neighbouring cell in the Y direction.
h_min – Minimum allowed height for a stable configuration. [m]
tol – Small number used to handle numerical approximation errors.

Returns:

Two-digit number indicating how the soil should avalanche. 0 is returned if the soil column is stable.

void RelaxUnstableTerrainCell(SimOut *sim_out, int status, float dh_max, int ii, int jj, int ii_c, int jj_c, Grid grid, Body *body, float tol)

This function moves the soil from the terrain_ at (ii, jj) to the soil column in (ii_c, jj_c).

The precise movement applied to the soil cell depends on the status number provided by the CheckUnstableTerrainCell function.

The soil is moved such that the slope formed by the two neighbouring soil columns is equal to the repose_angle_. When the body is preventing this configuration, the soil avalanche below the body to fill the space under it.

Note that it is assumed that the given status is accurate, so no extra checks are present.

Parameters:

sim_out – Class that stores simulation outputs.
status – Two-digit number indicating how the soil should avalanche.
dh_max – Maximum height difference allowed between two neighbouring cells. [m]
ii – Index of the considered cell in the X direction.
jj – Index of the considered cell in the Y direction.
ii_c – Index of the neighbouring cell in the X direction.
jj_c – Index of the neighbouring cell in the Y direction.
grid – Class that stores information related to the simulation grid.
body – Class that stores information related to the body object.
tol – Small number used to handle numerical approximation errors.

void RelaxUnstableBodyCell(SimOut *sim_out, int status, std::vector<body_soil> *body_soil_pos, float dh_max, int nn, int ii, int jj, int ind, int ii_c, int jj_c, Grid grid, Body *body, float tol)

This function moves the soil from the soil layer ind of body_soil_ at (ii, jj) to the soil column in (ii_c, jj_c).

The precise movement applied to the soil cell depends on the status number provided by the CheckUnstableBodyCell function.

The soil is moved such that the slope formed by the two neighbouring soil columns is equal to the repose_angle_, provided that the body is not preventing this configuration.

Note that it is assumed that the given status is accurate, so no extra checks are present.

Parameters:

sim_out – Class that stores simulation outputs.
status – Two-digit number indicating how the soil should avalanche.
body_soil_pos – Queue to append new body_soil_pos.
dh_max – Maximum height difference allowed between two neighbouring cells. [m]
nn – Index of the considered soil in body_soil_pos_.
ii – Index of the considered cell in the X direction.
jj – Index of the considered cell in the Y direction.
ind – Index of the considered soil layer.
ii_c – Index of the neighbouring cell in the X direction.
jj_c – Index of the neighbouring cell in the Y direction.
grid – Class that stores information related to the simulation grid.
body – Class that stores information related to the body object.
tol – Small number used to handle numerical approximation errors.