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

CSimulator &	GetSimulator ()
	Returns the simulator instance. More...

CSpace &	GetSpace ()
	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

◆ CLoopFunctions()

argos::CLoopFunctions::CLoopFunctions ( )

inline

Class constructor.

Definition at line 75 of file loop_functions.h.

◆ ~CLoopFunctions()

virtual argos::CLoopFunctions::~CLoopFunctions ( )

inlinevirtual

Class destructor.

Definition at line 83 of file loop_functions.h.

Member Function Documentation

◆ AddEntity()

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_entity A reference to the entity to add.

Exceptions

CARGoSException if an error occurs.

Definition at line 36 of file loop_functions.cpp.

◆ Destroy()

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.

◆ GetFloorColor()

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

◆ GetSimulator()

CSimulator& argos::CLoopFunctions::GetSimulator ( )

inline

Returns the simulator instance.

Returns: The simulator instance.

Definition at line 171 of file loop_functions.h.

◆ GetSpace()

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.

◆ Init()

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

inlinevirtual

Executes user-defined initialization logic.

The default implementation of this method does nothing.

Parameters

t_tree The <loop_functions> XML configuration tree.

See also: Reset(); Destroy()

Implements argos::CBaseConfigurableResource.

Definition at line 92 of file loop_functions.h.

◆ IsExperimentFinished()

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.

◆ MoveEntity() [1/2]

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_entity	The positional component of the entity to move.
c_position	The wanted position.
c_orientation	The wanted orientation.

Definition at line 17 of file loop_functions.cpp.

◆ MoveEntity() [2/2]

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

Returns: true if no collisions were detected, false otherwise.

Definition at line 26 of file loop_functions.cpp.

◆ PostExperiment()

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.

◆ PostStep()

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.

◆ PreStep()

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.

◆ RemoveEntity() [1/2]

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

virtual

Removes an entity from the simulation.

Parameters

str_entity_id The id of the entity to remove.

Exceptions

CARGoSException If an entity with the specified id was not found.

Definition at line 43 of file loop_functions.cpp.

◆ RemoveEntity() [2/2]

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

virtual

Removes an entity from the simulation.

Parameters

c_entity A reference to the entity to remove.

Definition at line 51 of file loop_functions.cpp.

◆ Reset()

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.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CLoopFunctions()

◆ ~CLoopFunctions()

Member Function Documentation

◆ AddEntity()

◆ Destroy()

◆ GetFloorColor()

◆ GetSimulator()

◆ GetSpace()

◆ Init()

◆ IsExperimentFinished()

◆ MoveEntity() [1/2]

◆ MoveEntity() [2/2]

◆ PostExperiment()

◆ PostStep()

◆ PreStep()

◆ RemoveEntity() [1/2]

◆ RemoveEntity() [2/2]

◆ Reset()