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

const CSpace &	GetSpace () const

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, bool b_ignore_collisions=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...

void	IterateOverControllableEntities (const CSpace::TControllableEntityIterCBType &c_cb) const
	Iterate over all controllable entities currently present in the arena (including those that are currently disabled) executing the specified callback on each. 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 70 of file loop_functions.h.

Constructor & Destructor Documentation

◆ CLoopFunctions()

argos::CLoopFunctions::CLoopFunctions ( )

inline

Class constructor.

Definition at line 77 of file loop_functions.h.

◆ ~CLoopFunctions()

virtual argos::CLoopFunctions::~CLoopFunctions ( )

inlinevirtual

Class destructor.

Definition at line 85 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 37 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 111 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 165 of file loop_functions.h.

◆ GetSimulator()

CSimulator& argos::CLoopFunctions::GetSimulator ( )

inline

Returns the simulator instance.

Returns: The simulator instance.

Definition at line 173 of file loop_functions.h.

◆ GetSpace() [1/2]

CSpace& argos::CLoopFunctions::GetSpace ( )

inline

Returns a reference to the space state.

Returns: A reference to the space state.

Definition at line 181 of file loop_functions.h.

◆ GetSpace() [2/2]

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

inline

Definition at line 185 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 94 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 138 of file loop_functions.h.

◆ IterateOverControllableEntities()

void argos::CLoopFunctions::IterateOverControllableEntities ( const CSpace::TControllableEntityIterCBType & c_cb ) const

inline

Iterate over all controllable entities currently present in the arena (including those that are currently disabled) executing the specified callback on each.

The specified callback can be executed in a multi-threaded context, depending on configuration (i.e. how many threads were specified in the input file) improving simulation efficiency by re-using ARGoS threads rather than the loop functions having to create/maintain its own thread pool(s). If multiple ARGoS threads are specified, the following operations CANNOT be safely performed on the entity passed to each callback:

Entity removal
Creating a new entity based on the current one

Furthermore, iteration over controllable entities can be performed AT MOST twice in one timestep: one time in PreStep(), and one time in PostStep(). Mutiple iteration attempts in either function will cause a deadlock due to how iteration is implemented.

See also: PostStep(); PreStep()

Definition at line 264 of file loop_functions.h.

◆ MoveEntity() [1/2]

bool argos::CLoopFunctions::MoveEntity	(	CEmbodiedEntity &	c_entity,
		const CVector3 &	c_position,
		const CQuaternion &	c_orientation,
		bool	b_check_only = `false`,
		bool	b_ignore_collisions = `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.
b_ignore_collisions	If `false`, collisions are considered; if `true`, collisions are ignored

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

Definition at line 26 of file loop_functions.cpp.

◆ MoveEntity() [2/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.

◆ 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 151 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 127 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 119 of file loop_functions.h.

◆ RemoveEntity() [1/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 52 of file loop_functions.cpp.

◆ RemoveEntity() [2/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 44 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 103 of file loop_functions.h.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CLoopFunctions()

◆ ~CLoopFunctions()

Member Function Documentation

◆ AddEntity()

◆ Destroy()

◆ GetFloorColor()

◆ GetSimulator()

◆ GetSpace() [1/2]

◆ GetSpace() [2/2]

◆ Init()

◆ IsExperimentFinished()

◆ IterateOverControllableEntities()

◆ MoveEntity() [1/2]

◆ MoveEntity() [2/2]

◆ PostExperiment()

◆ PostStep()

◆ PreStep()

◆ RemoveEntity() [1/2]

◆ RemoveEntity() [2/2]

◆ Reset()