Documentation for utility functions

A number of utility functions are aggregated in the file utils.cpp. Information for some of these functions are provided below.

Checking functions

This corresponds to the functions CheckVolume and CheckSoil, which can be used to check the validity of the simulation outputs. It is important to call these functions either before or after the simulation stepping process, as the outputs may be temporarily invalid during the stepping.

The CheckVolume function verifies mass conservation, ensuring that the total mass of soil is properly conserved throughout the simulation, and that the amount of soil in the body_soil_ and body_soil_pos_ fields of the SimOut class are consistent. The CheckSoil function checks the coherence and integrity of the terrain, body soil, and body. It ensures that there are no intersections or conflicting cell assignments between these three groups.

Note that these functions are computationally intensive and may slow down the simulation. Therefore, it is recommended to use them primarily for debugging and testing purposes.

Writing functions

This corresponds to the functions WriteSoil and WriteBody, which can be used to write the outputs into csv files. The WriteBody function generates files starting either with bucket or blade, depending on the type of rigid body simulated, containing the Cartesian coordinates of the body walls’ edges. The WriteSoil function generates files starting with terrain for the terrain height and body_soil for the body soil height. All the output files are saved in the results folder, with sequentially increasing numbers appended to the filenames.

Note that these functions are primarily designed to be used in the example script provided. Consequently, they have potential limitations that should be considered by the user. Firstly, the file numbers are assigned sequentially. If the WriteBody and WriteSoil functions are not called together consistently, the file numbers may not correspond. As a result, the two functions are always called together by the WriteOutputs function of the simulator. Additionally, this may cause issues if existing files are present in the results folder.

Secondly, the file formats generated by these functions are specifically designed for visualization with Paraview.

Quaternions operations

Several functions have been implemented to make the use of Quaternions easier. All these operations are already extensively described online and would not be explicited here.

First, the function MultiplyQuaternion simply implements the multiplication of two Quaternions. This function is used in CalcRotationQuaternion to apply the rotation given by a Quaternion to a given position.

Second, the function AngleToQuat converts Euler angles following the ZYX convention to a Quaternion. Note that other conventions are currently not supported.

Lastly, the function CalcBodyFramePos calculates the position of a given cell in the reference frame of the body. To do so, the inverse of the body orientation is applied to the position. This is used to keep the position where the soil has initially landed on the body.

Terrain initialization

The function SimplexNoise provides a way to initialize terrain with realistic random shapes. The implementation follows the Simplex noise algorithm that is standard for this type of problem. The produced terrain has only slight height variations as the purpose of the terrain initialization is not to reproduce all the diversity of construction site but only to provide simple terrain for testing the simulator.

Note that it is straightforward to change the terrain initialization implementation to a more advanced algorithm if needed.

Determine whether soil should be updated

The function CheckBodyMovement can be used before the soil update to verify whether the soil should be updated. This function calculates the distance travelled by the body corners since the last soil update. If the maximum distance is lower than 50% of the cell size (vertical AND lateral), then the function returns false and the soil should not be updated, otherwise the function returns true.

Note that if the distance is larger than twice the cell size (vertical OR lateral), a warning is sent mentioning that the integrity of the simulation cannot be guaranteed.