# Tutorial for the ```CrowdMechanics``` engine
The purpose of the engine is to take a configuration of agents, who may or may not have obstacles around, and evolve their position given driving forces and torques, duly handling possible collisions.
There is a single standalone function to be called, that will take as input a list of XML files names and will produce XML files with the resulting configuration.
There are two types of files: the static ones which contains immutable parameters such as the positions of walls, the characteristics of the materials, ... And the dynamic ones that contain values that change over time, ie the kinematics and dynamics of the agents:
- **Static**:
- *Parameters* contain technical information such as working directories, but also time intervals of the simulation;
- *Materials* contain physical information about the materials the agents and obstacles are made of;
- *Geometry* details the layout of the scene: dimensions and positions of obstacles
- *Agents* lists the agents and the shapes that constitute them.
- **Dynamic**
- *Agent Dynamics* contain the current positions and velocities of the agents, as well as the driving forces and torques we apply to them. It is used as input as well as as output of the library.
- (*optional*) *Agent Interactions* is a product of the library that lists all the contacts, be it agent/agent or agent/obstacle, the forces on each agent as well as a technical quantity that we call the Tangential relative displacement. This file must also be provided as input to the library if the current execution is part of a series of consecutive executions of the same situation.
We detail the contents of those files below, by order of importance and of input into the function. Note that all quantities present in those files are expressed in International System of Units (SI), in particular distances are in metres, time in seconds, angles in radians.
> Note: we use the external library [tinyxml2](http://leethomason.github.io/tinyxml2/index.html) for the handling of XML files.
## Static information
### Parameters
The layout is the following:
```xml
```
First, note that the Parameters are enclosed in a root *Parameters* tag. This will be the same for each of the XML files.
The expected tags/fields are
- (*mandatory*) `````` end its enclosing tag `````` surround all other data.
- (*mandatory*) ``````
- ```Static``` (type ```std::string```) is the absolute path to the directory where the library can find the **static** XML files.
- ```Dynamic``` (type ```std::string```) is the absolute path to the directory where the library can find the **dynamic** XML files.
- (*mandatory*) ``````
- ```TimeStep``` (type ```double```) is the total time of the simulation.
- ```TimeStepMechanical``` (type ```double```) is the (smaller) time interval of the calculation of mechanical contacts.
Note that when calling the library, an absolute path to the Parameters file should be given, whereas the other string should just contain the file names since the directories in which they have been put are given by the Parameters file.
### Materials
```xml
```
- (*mandatory*) `````` and its closing tag `````` enclose all data.
- (*mandatory*) `````` and its closing tag `````` enclose the intrinsic properties of the materials:
- (*mandatory*) One `````` tag per material, with the fields
- (*mandatory*, *unique*) ```Id``` (type ```std::string```) is an identifier for the material;
- (*optional*) ```Name``` is not used byt the library;
- (*mandatory*) ```YoungModulus``` (type ```double```) is the value of Young's modulus {math}`E`;
- (*mandatory*) ```ShearModulus``` (type ```double```) is the value of the shear modulus {math}`G`.
- (*mandatory*) `````` and its closing tag `````` enclose the binary properties of the materials, ie the physical quantities related to the contact of two materials:
- (*mandatory*) One `````` tag per couple. All couples should be given. The following fields are expected:
- (*mandatory*) ```Id1``` and ```Id2``` (type ```std::string```) is and identifier for the material;
- (*mandatory*) ```GammaNormal``` is the value of the normal damping factor {math}`\Gamma_{\rm n}` ;
- (*mandatory*) ```GammaTangential``` is the value of the tangential damping factor {math}`\Gamma_{\rm t}` ;
- (*mandatory*) ```KineticFriction``` is the value of the kinetic friction coefficient {math}`\mu_{\rm dyn}`.
### Geometry
The Geometry file gives the dimensions of the area in which the simulation takes place, as well as information about obstacles.
The latter as given as **Walls**, which are an ordered list of **Corners**. Each **Corner** is linked to its direct together by a line segment, forming a wall face. Here below an example:
|
```xml
```
- (*mandatory*) `````` and its closing tag `````` enclose all data.
- (*mandatory*) `````` contain the dimensions of the rectangular domain:
- (*mandatory*) ```Lx``` (type ```double```) is the length of the domain along the x-axis;
- (*mandatory*) ```Ly``` (type ```double```) is the length of the domain along the y-axis.
- (*mandatory*) One `````` tag per wall, with the field
- (*optional*) ```MaterialId``` (type ```std::string```) related to the Ids in the [Materials file](#Materials). If not given or not found, the default value for walls is used.
- (*mandatory*) ```Corner``` tags: at least two of them must be present. Each one contains the *mandatory* field ```Coordinates``` (type ```std::pair```).
- (*mandatory*) A closing `````` tag after the list of corners.
Note that in the example, the first wall is actually enclosing the whole domain and thus acts as a strict boundary.
### Agents
```xml
```
- (*mandatory*) `````` and its closing tag `````` enclose all data.
- (*mandatory*) `````` and its closing tag `````` enclose each agent. It contains the following fields:
- (*optional*, *unused*) ```Type``` is unused for now since the current version only handles pedestrians, but we mention it since we are working on adapting the model to other active modes.
- (*mandatory*, *unique*) ```Id``` (type ```std::string```) is a unique Id for the agent;
- (*mandatory*) ```Mass``` (type ```double```) is the mass (in {math}`\rm kg`) of the agent;
- (*mandatory*) ```MomentOfInertia``` (type ```double```) is the moment of inertia (in {math}`\rm kg\,m^2`) of the agent, with respect to a vertical axis going through the center of mass of the agent;
- (*optional*) ```FloorDamping``` is the inverse of the quantity {math}`\tau_{\rm mech}` (in {math}`\rm s^{-1}`) found in the equations of motion of an unhindered agent. If not given, the default value is used;
- (*optional*) ```AngularDamping``` is the angular version (ie related to angular movement) of the above. If not given, the default value is used;
- (*mandatory*) Each `````` encloses exactly **five** `````` tags, which should be given in a specific order, ie from the left shoulder to the right shoulder. They consisting in the following fields:
- (*mandatory*, *unique within a specific agent*) ```Id``` (type ```std::string```) is an identifier for the shape.
- (*optional*, *unused*) ```Type``` is unused for now since the current version only handles disks, but we mention it since we are working on adapting the model to other active modes.
- (*mandatory*) ```Radius``` (type ```double```) is the radius of the disk;
- (*optional*) ```MaterialId``` (type ```std::string```) related to the Ids in the [Materials file](#Materials). If not given or not found, the default value for humans is used.
- (*mandatory*) ```Position``` (type ```std::pair```) is the position of the center of mass of the shape, relative to the center of mass of the agent.
## Dynamic information
### Agent Dynamics
#### As input
```xml
```
- (*mandatory*) `````` and its closing tag `````` enclose all data.
- (*mandatory*) `````` and its closing tag `````` enclose each agent. It contains the ```Id``` of the agent, which should be in the [Agents file](#agents):
- (*mandatory*) The `````` tag is the current state of the agent, and contains the following fields:
- (*mandatory*) ```Position``` (type ```std::pair```) is the position of the center of mass of the agent;
- (*mandatory*) ```Velocity``` (type ```std::pair```) is the velocity of the center of mass of the agent;
- (*mandatory*) ```Theta``` (type ```double```) is the angle between the direction of the body, ie the line of sight when looking straight, and the x-axis.
- (*mandatory*) ```Omega``` (type ```double```) is the angular speed of the body.
- (*mandatory*) The `````` tag is the driving forces given to the agent, and contains the following fields:
- (*mandatory*) ```Fp``` (type ```std::pair```) is the driving force;
- (*mandatory*) ```Mp``` (type ```double```) is the driving torque;
> Note: All angular quantities are given with the right-handed convention, ie a positive value is to be taken counterclockwise.
>
> Note2: The driving force and torque are related to the equations of motion of the unhindered agent, ie
```{math}
\frac{{\rm d}{\bf v}}{{\rm d}t}=\frac{{\bf v}^{\rm des}-{\bf v}}{\tau_{\rm mech}}\;,
```
> by {math}`{\bf F}_{\rm p}=m\frac{{\bf v}^{\rm des}}{\tau_{\rm mech}}.` Same goes for the angular version.
#### As output
The output of ```CrowdMechanics``` will have the same structure, except that the ```Dynamics``` tag will no longer be present. The ```Kinematics``` tag will contain the new state of the agent, after a time ```TimeStep```, eg:
```xml
```
### Agent Interactions
The library outputs information about collisions between agents, and between agents and walls. This serves two purposes:
- The total normal force on the agents allows computation of the pressure exerted on them;
- If the current execution of the library is a part of a series of consecutive runs in time, this file should remain as is since it will be used by the next execution to gather technical information about current existing contacts.
Since this file should not be "prepared" by the user, it will always have the same name ```AgentInteractions.xml``` and will always be stored in the current working directory.
```xml
```
> **Important note** The files give only one of the reciprocal interactions between two agents: it will only give the couples {math}`i,j` with {math}`i < j`.
- (*mandatory*) `````` and its closing tag `````` enclose all data.
- (*mandatory*) `````` and its closing tag `````` enclose each agent. It contains the ```Id``` of the agent, which should be in the [Agents file](#agents). It corresponds to the index {math}`i` in the note above and will be name the "Parent".
- (*optional*) `````` and its closing tag `````` enclose each "Child" agent. It contains the ```Id``` of the agent, which should be in the [Agents file](#agents), and corresponds to the index {math}`j` above.
- (*mandatory*) For each couple, we can have several `````` tags, as multiple shapes could touch each other. The tag contains the following:
- (*mandatory*) ```ParentShape``` refers to the ```Id``` of the shape of the Parent that is in touch with the Child, and that comes from the [Agents file](#agents);
- (*mandatory*) ```ChildShape``` refers to the ```Id``` of the shape of the Child that is in touch with ```ParentShape```, and that comes from the [Agents file](#agents);
- (*mandatory*) ```TangentialRelativeDisplacement``` (type ```std::pair```) is a technical field used by the library to know if there is a contact, that represents the relative displacement that has occurred during the contact;
- (*mandatory*) ```Fn``` (type ```std::pair```) is the normal force exerted on the ```ParentShape```, as a result of its contact with ```ChildShape```;
- (*mandatory*) ```Ft``` (type ```std::pair```) is the tangential force exerted on the ```ParentShape```, as a result of its contact with ```ChildShape```.
- (*optional*) There will be a `````` tag for each contact between the Parent and a wall face:
- (*mandatory*) ```ShapeId``` is the Id of the shape of the Parent that is in contact with a wall;
- (*mandatory*) ```WallId``` (type ```unsigned```) is a number attributed to the `````` tags coming from the [Geometry file](#geometry);
- (*mandatory*) ```CornerId``` (type ```unsigned```) is a number attributed to the `````` tags coming from the [Geometry file](#geometry). In this context, it represents the wall face joining corner ```CornerId``` to corner ```CornerId + 1``` ;
- (*mandatory*) The same 3 fields as for the agent/agent interactions complete the `````` tag.