ARGoS  3
A parallel, multi-engine simulator for swarm robotics
argos::CLoopFunctions Class Reference

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

#include <loop_functions.h>

+ Inheritance diagram for argos::CLoopFunctions:

List of all members.

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.
CSimulatorGetSimulator ()
 Returns the simulator instance.
CSpaceGetSpace ()
 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.

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


Constructor & Destructor Documentation

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.


Member Function Documentation

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 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.

See also:
Init()

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.

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

Returns the simulator instance.

Returns:
The simulator instance.

Definition at line 155 of file loop_functions.h.

Returns a reference to the space state.

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.

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

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.

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

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.

Parameters:
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 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.

See also:
PreStep()

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.

See also:
PostStep()

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.

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

Definition at line 32 of file loop_functions.cpp.

Removes an entity from the simulation.

Parameters:
c_entityA 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.

See also:
Init()

Implements argos::CBaseConfigurableResource.

Definition at line 99 of file loop_functions.h.


The documentation for this class was generated from the following files: