.. _utils:

Documentation for utility functions
===================================

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

Checking functions
------------------

This corresponds to the functions :code:`CheckVolume` and :code:`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 :code:`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 :code:`body_soil_` and :code:`body_soil_pos_` fields of the :code:`SimOut` class are consistent.
The :code:`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 :code:`WriteSoil` and :code:`WriteBody`, which can be used to write the outputs into csv files.
The :code:`WriteBody` function generates files starting either with :code:`bucket` or :code:`blade`, depending on the type of rigid body simulated, containing the Cartesian coordinates of the body walls' edges.
The :code:`WriteSoil` function generates files starting with :code:`terrain` for the terrain height and :code:`body_soil` for the body soil height.
All the output files are saved in the :code:`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 :code:`WriteBody` and :code:`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 :code:`WriteOutputs` function of the simulator.
Additionally, this may cause issues if existing files are present in the :code:`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 :code:`MultiplyQuaternion` simply implements the multiplication of two Quaternions.
This function is used in :code:`CalcRotationQuaternion` to apply the rotation given by a Quaternion to a given position.

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

Lastly, the function :code:`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 :code:`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 :code:`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 :code:`false` and the soil should not be updated, otherwise the function returns :code:`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.