ARGoS
3
A parallel, multi-engine simulator for swarm robotics
|
A set of hook functions to customize an experimental run. More...
#include <loop_functions.h>
Public Member Functions | |
CLoopFunctions () | |
Class constructor. | |
virtual | ~CLoopFunctions () |
Class destructor. | |
virtual void | Init (TConfigurationNode &t_tree) |
Executes user-defined initialization logic. | |
virtual void | Reset () |
Executes user-defined reset logic. | |
virtual void | Destroy () |
Executes user-defined destruction logic. | |
virtual void | PreStep () |
Executes user-defined logic right before a simulation step is executed. | |
virtual void | PostStep () |
Executes user-defined logic right after a simulation step is executed. | |
virtual bool | IsExperimentFinished () |
Returns true if the experiment is finished. | |
virtual CColor | GetFloorColor (const CVector2 &c_pos_on_floor) |
Returns the color of the floor in the specified point. | |
CSimulator & | GetSimulator () |
Returns the simulator instance. | |
CSpace & | GetSpace () |
Returns a reference to the space state. | |
bool | MoveEntity (CPositionalEntity &c_entity, const CVector3 &c_position, const CQuaternion &c_orientation, bool b_check_only) |
Moves the entity to the wanted position and orientation. | |
void | AddEntity (CEntity &c_entity) |
Adds the passed entity to the simulation. | |
void | RemoveEntity (const std::string &str_entity_id) |
Removes an entity from the simulation. | |
void | RemoveEntity (CEntity &c_entity) |
Removes an entity from the simulation. |
A set of hook functions to customize an experimental run.
It is very difficult to identify a set of features that can cover all the possible use cases of multi-robot systems. Even though some features, such as robot motion, are almost always necessary, many other features depend on the type of experiment considered. For instance, the metrics against which statistics must be calculated depend on the experiment. Also, if the environment presents custom dynamics, such as objects being added or removed as a result of the actions of the robots, these mechanisms need to be implemented in the simulator. The need for specific and often divergent features renders the design of a generic simulator extremely complex. Furthermore, the approach of trying to add a myriad of features in the attempt to cover every possible use case usually renders the learning curve of a tool much steeper, hindering usability and maintainability.
To cope with these issues, we followed the common approach of providing user-defined function hooks in strategic points of the simulation loop. In ARGoS, these hooks are called loop functions. The user can customize the initialization and the end of an experiment, and add custom functionality executed before and/or after each simulation step. It is also possible to define custom end conditions for an experiment.
Loop functions allow one to access and modify the entire simulation. In this way, the user can collect figures and statistics, and store complex data for later analysis. It is also possible to interact with the simulation by moving, adding or removing entities in the environment, or by changing their internal state.
Finally, loop functions can be used to prototype new features before they are promoted to the core ARGoS code.
Definition at line 66 of file loop_functions.h.
argos::CLoopFunctions::CLoopFunctions | ( | ) | [inline] |
Class constructor.
Definition at line 73 of file loop_functions.h.
virtual argos::CLoopFunctions::~CLoopFunctions | ( | ) | [inline, virtual] |
Class destructor.
Definition at line 81 of file loop_functions.h.
void argos::CLoopFunctions::AddEntity | ( | CEntity & | c_entity | ) |
Adds the passed entity to the simulation.
Important: the entity must be created with a new
statement or a CFactory::New() statement. In other words, the entity must be stored in the heap. If this is not the case, memory corruption will occur.
c_entity | A reference to the entity to add. |
CARGoSException | if an error occurs. |
Definition at line 25 of file loop_functions.cpp.
virtual void argos::CLoopFunctions::Destroy | ( | ) | [inline, virtual] |
Executes user-defined destruction logic.
This method should undo whatever is done in Init(). The default implementation of this method does nothing.
Implements argos::CBaseConfigurableResource.
Definition at line 107 of file loop_functions.h.
virtual CColor argos::CLoopFunctions::GetFloorColor | ( | const CVector2 & | c_pos_on_floor | ) | [inline, virtual] |
Returns the color of the floor in the specified point.
This function is called if the floor entity was configured to take the loop functions as source. The floor color is used by the ground sensors to calculate their readings, and by the graphical visualization to create a texture to display on the arena floor.
c_pos_on_floor | The position on the floor. |
Definition at line 147 of file loop_functions.h.
CSimulator& argos::CLoopFunctions::GetSimulator | ( | ) | [inline] |
Returns the simulator instance.
Definition at line 155 of file loop_functions.h.
CSpace& argos::CLoopFunctions::GetSpace | ( | ) | [inline] |
Returns a reference to the space state.
Definition at line 163 of file loop_functions.h.
virtual void argos::CLoopFunctions::Init | ( | TConfigurationNode & | t_tree | ) | [inline, virtual] |
Executes user-defined initialization logic.
The default implementation of this method does nothing.
t_tree | The <loop_functions> XML configuration tree. |
Implements argos::CBaseConfigurableResource.
Definition at line 90 of file loop_functions.h.
virtual bool argos::CLoopFunctions::IsExperimentFinished | ( | ) | [inline, virtual] |
Returns true
if the experiment is finished.
This method allows the user to specify experiment-specific ending conditions. The default implementation of this method returns always false
. This means that the only ending conditions for an experiment are time limit expiration or GUI shutdown.
true
if the experiment is finished. Definition at line 132 of file loop_functions.h.
bool argos::CLoopFunctions::MoveEntity | ( | CPositionalEntity & | c_entity, |
const CVector3 & | c_position, | ||
const CQuaternion & | c_orientation, | ||
bool | b_check_only | ||
) |
Moves the entity to the wanted position and orientation.
If the entity is embodied, the movement is allowed only if the object does not collide with anything once in the new position. If the entity is just positional, the movement is always allowed. c_entity The positional or embodied component of the entity to move.
c_position | The wanted position. |
c_orientation | The wanted orientation. |
b_check_only | If false , the movement is executed; otherwise, the object is not actually moved. |
true
if no collisions were detected, false
otherwise. Definition at line 15 of file loop_functions.cpp.
virtual void argos::CLoopFunctions::PostStep | ( | ) | [inline, virtual] |
Executes user-defined logic right after a simulation step is executed.
The default implementation of this method does nothing.
Definition at line 121 of file loop_functions.h.
virtual void argos::CLoopFunctions::PreStep | ( | ) | [inline, virtual] |
Executes user-defined logic right before a simulation step is executed.
The default implementation of this method does nothing.
Definition at line 114 of file loop_functions.h.
void argos::CLoopFunctions::RemoveEntity | ( | const std::string & | str_entity_id | ) |
Removes an entity from the simulation.
str_entity_id | The id of the entity to remove. |
CARGoSException | If an entity with the specified id was not found. |
Definition at line 32 of file loop_functions.cpp.
void argos::CLoopFunctions::RemoveEntity | ( | CEntity & | c_entity | ) |
Removes an entity from the simulation.
c_entity | A reference to the entity to remove. |
Definition at line 40 of file loop_functions.cpp.
virtual void argos::CLoopFunctions::Reset | ( | ) | [inline, virtual] |
Executes user-defined reset logic.
This method should restore the state of the simulation at it was right after Init() was called. The default implementation of this method does nothing.
Implements argos::CBaseConfigurableResource.
Definition at line 99 of file loop_functions.h.