argos::CLoopFunctions Class Reference

A set of hook functions to customize an experimental run. More...

#include <loop_functions.h>

Inheritance diagram for argos::CLoopFunctions:
Collaboration diagram for argos::CLoopFunctions:

Public Member Functions

 CLoopFunctions ()
 Class constructor. More...
 
virtual ~CLoopFunctions ()
 Class destructor. More...
 
virtual void Init (TConfigurationNode &t_tree)
 Executes user-defined initialization logic. More...
 
virtual void Reset ()
 Executes user-defined reset logic. More...
 
virtual void Destroy ()
 Executes user-defined destruction logic. More...
 
virtual void PreStep ()
 Executes user-defined logic right before a control step is executed. More...
 
virtual void PostStep ()
 Executes user-defined logic right after a control step is executed. More...
 
virtual bool IsExperimentFinished ()
 Returns true if the experiment is finished. More...
 
virtual void PostExperiment ()
 Executes user-defined logic when the experiment finishes. More...
 
virtual CColor GetFloorColor (const CVector2 &c_pos_on_floor)
 Returns the color of the floor in the specified point. More...
 
CSimulatorGetSimulator ()
 Returns the simulator instance. More...
 
CSpaceGetSpace ()
 Returns a reference to the space state. More...
 
virtual void MoveEntity (CPositionalEntity &c_entity, const CVector3 &c_position, const CQuaternion &c_orientation)
 Moves the entity to the wanted position and orientation. More...
 
virtual bool MoveEntity (CEmbodiedEntity &c_entity, const CVector3 &c_position, const CQuaternion &c_orientation, bool b_check_only=false)
 Moves the entity to the wanted position and orientation. More...
 
virtual void AddEntity (CEntity &c_entity)
 Adds the passed entity to the simulation. More...
 
virtual void RemoveEntity (const std::string &str_entity_id)
 Removes an entity from the simulation. More...
 
virtual void RemoveEntity (CEntity &c_entity)
 Removes an entity from the simulation. More...
 
- Public Member Functions inherited from argos::CBaseConfigurableResource
virtual ~CBaseConfigurableResource ()
 Class destructor. More...
 

Detailed Description

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 68 of file loop_functions.h.

Constructor & Destructor Documentation

argos::CLoopFunctions::CLoopFunctions ( )
inline

Class constructor.

Definition at line 75 of file loop_functions.h.

virtual argos::CLoopFunctions::~CLoopFunctions ( )
inlinevirtual

Class destructor.

Definition at line 83 of file loop_functions.h.

Member Function Documentation

void argos::CLoopFunctions::AddEntity ( CEntity c_entity)
virtual

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.

Parameters
c_entityA reference to the entity to add.
Exceptions
CARGoSExceptionif an error occurs.

Definition at line 36 of file loop_functions.cpp.

virtual void argos::CLoopFunctions::Destroy ( )
inlinevirtual

Executes user-defined destruction logic.

This method should undo whatever is done in Init(). The default implementation of this method does nothing.

See also
Init()

Implements argos::CBaseConfigurableResource.

Definition at line 109 of file loop_functions.h.

virtual CColor argos::CLoopFunctions::GetFloorColor ( const CVector2 c_pos_on_floor)
inlinevirtual

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.

Parameters
c_pos_on_floorThe position on the floor.
Returns
The color of the floor in the specified point.
See also
CFloorEntity
CGroundSensorEquippedEntity
CGroundRotZOnlySensor

Definition at line 163 of file loop_functions.h.

CSimulator& argos::CLoopFunctions::GetSimulator ( )
inline

Returns the simulator instance.

Returns
The simulator instance.

Definition at line 171 of file loop_functions.h.

CSpace& argos::CLoopFunctions::GetSpace ( )
inline

Returns a reference to the space state.

Returns
A reference to the space state.

Definition at line 179 of file loop_functions.h.

virtual void argos::CLoopFunctions::Init ( TConfigurationNode t_tree)
inlinevirtual

Executes user-defined initialization logic.

The default implementation of this method does nothing.

Parameters
t_treeThe <loop_functions> XML configuration tree.
See also
Reset()
Destroy()

Implements argos::CBaseConfigurableResource.

Definition at line 92 of file loop_functions.h.

virtual bool argos::CLoopFunctions::IsExperimentFinished ( )
inlinevirtual

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.

Returns
true if the experiment is finished.
See also
CSimulator::IsExperimentFinished()

Definition at line 136 of file loop_functions.h.

void argos::CLoopFunctions::MoveEntity ( CPositionalEntity c_entity,
const CVector3 c_position,
const CQuaternion c_orientation 
)
virtual

Moves the entity to the wanted position and orientation.

Parameters
c_entityThe positional component of the entity to move.
c_positionThe wanted position.
c_orientationThe wanted orientation.

Definition at line 17 of file loop_functions.cpp.

bool argos::CLoopFunctions::MoveEntity ( CEmbodiedEntity c_entity,
const CVector3 c_position,
const CQuaternion c_orientation,
bool  b_check_only = false 
)
virtual

Moves the entity to the wanted position and orientation.

The movement is allowed only if the object does not collide with anything once in the new position.

Parameters
c_entityThe positional or embodied component of the entity to move.
c_positionThe wanted position.
c_orientationThe wanted orientation.
b_check_onlyIf false, the movement is executed; otherwise, the object is not actually moved.
Returns
true if no collisions were detected, false otherwise.

Definition at line 26 of file loop_functions.cpp.

virtual void argos::CLoopFunctions::PostExperiment ( )
inlinevirtual

Executes user-defined logic when the experiment finishes.

This method is called within CSimulator::IsExperimentFinished() as soon as its return value evaluates to true. This method is executed before Destroy(). You can use this method to perform final calculations at the end of an experiment. The default implementation of this method does nothing.

Definition at line 149 of file loop_functions.h.

virtual void argos::CLoopFunctions::PostStep ( )
inlinevirtual

Executes user-defined logic right after a control step is executed.

This function is executed before the actuators are updated for the next time step. The default implementation of this method does nothing.

See also
PreStep()

Definition at line 125 of file loop_functions.h.

virtual void argos::CLoopFunctions::PreStep ( )
inlinevirtual

Executes user-defined logic right before a control step is executed.

This function is executed before the sensors are updated for the current time step. The default implementation of this method does nothing.

See also
PostStep()

Definition at line 117 of file loop_functions.h.

void argos::CLoopFunctions::RemoveEntity ( const std::string &  str_entity_id)
virtual

Removes an entity from the simulation.

Parameters
str_entity_idThe id of the entity to remove.
Exceptions
CARGoSExceptionIf an entity with the specified id was not found.

Definition at line 43 of file loop_functions.cpp.

void argos::CLoopFunctions::RemoveEntity ( CEntity c_entity)
virtual

Removes an entity from the simulation.

Parameters
c_entityA reference to the entity to remove.

Definition at line 51 of file loop_functions.cpp.

virtual void argos::CLoopFunctions::Reset ( )
inlinevirtual

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.

See also
Init()

Implements argos::CBaseConfigurableResource.

Definition at line 101 of file loop_functions.h.