intersecting_cells: Doxygen documentation

namespace soil_simulator

Functions

void MoveIntersectingCells(SimOut *sim_out, Grid grid, Body *body, float tol)

This function moves all soil cells in terrain_ and in body_soil_ that intersect with the body or with another soil cell.

Note that MoveIntersectingBodySoil must be called before MoveIntersectingBody, otherwise some intersecting soil cells may remain.

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.

• tol – Small number used to handle numerical approximation errors.

void MoveIntersectingBodySoil(SimOut *sim_out, Grid grid, Body *body, float tol)

This function moves the soil cells resting on the body that intersect with another body layer.

This function checks the eight lateral directions surrounding the intersecting soil column and moves the soil to available spaces.

The algorithm follows an incremental approach, checking directions farther from the intersecting soil column until it reaches a body wall blocking the movement or until all the soil has been moved. If the movement is blocked by a body wall, the algorithm explores another direction.

In cases where the soil should be moved to the terrain, all soil is moved regardless of the available space. If this movement induces intersecting soil cells, it will be resolved by the MoveIntersectingBody function.

In rare situations where there is insufficient space to accommodate all the intersecting soil, the algorithm currently handles it by allowing the excess soil to simply disappear. This compromise seems to be reasonable as long as the amount of soil disappearing remains negligible.

Note that the order in which the directions are checked is randomized in order to avoid asymmetrical results.

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.

• tol – Small number used to handle numerical approximation errors.

void MoveIntersectingBody(SimOut *sim_out, float tol)

This function moves the soil cells in the terrain_ that intersect with a body.

This function checks the eight lateral directions surrounding the intersecting soil column and moves the soil to available spaces. If there is insufficient space for all the soil, it incrementally checks the eight directions farther from the intersecting soil column until all the soil has been moved. The process can be illustrated as follows

            ↖   ↑   ↗
              ↖ ↑ ↗
            ← ← O → →
              ↙ ↓ ↘
            ↙   ↓   ↘

Note that the order in which the directions are checked is randomized in order to avoid asymmetrical results.

Parameters:

• sim_out – Class that stores simulation outputs.

• tol – Small number used to handle numerical approximation errors.

std::tuple<int, int, int, float, bool> MoveBodySoil(SimOut *sim_out, int ind_p, int ii_p, int jj_p, float max_h, int ii_n, int jj_n, float h_soil, bool wall_presence, Grid grid, Body *body, float tol)

This function tries to move the soil cells resting on the body layer ind_p at the location (ii_p, jj_p) to a new location at (ii_n, jj_n).

This function can be separated into three main scenarios:

• If all the soil can be moved to the new location (either on the terrain or on the body), the soil is moved and the value of h_soil is set to zero.

• If a body wall is blocking the movement, the wall_presence parameter is set to true.

• If there is insufficient space to move all the soil but no body wall is blocking the movement, the function updates the values for the new location and adjusts h_soil accordingly.

This function is designed to be used iteratively by the function MoveIntersectingBodySoil until all intersecting soil cells are moved.

Note that, by convention, the soil can be moved from the body to the terrain even if the body is underground. Moreover, in cases where the soil should be moved to the terrain, all soil is moved regardless of the available space. If this movement induces intersecting soil cells, it will be resolved by MoveIntersectingBody.

Parameters:

• sim_out – Class that stores simulation outputs.

• ind_p – Index of the previous considered body layer.

• ii_p – Index of the previous considered position in the X direction.

• jj_p – Index of the previous considered position in the Y direction.

• max_h – Maximum height authorized for the movement. [m]

• ii_n – Index of the new considered position in the X direction.

• jj_n – Index of the new considered position in the Y direction.

• h_soil – Height of the soil column left to be moved. [m]

• wall_presence – Indicates whether a wall is blocking the movement.

• 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.

Returns:

A tuple composed of the index of the new considered body layer, the index of the new considered position in the X direction, the index of the new considered position in the Y direction, the height of the soil column left to be moved, and a boolean indicating whether a body wall is blocking the movement.

std::vector<std::vector<int>> LocateIntersectingCells(SimOut *sim_out, float tol)

This function identifies all the soil cells in the terrain_ that intersect with the body.

Parameters:

• sim_out – Class that stores simulation outputs.

• tol – Small number used to handle numerical approximation errors.