Utils

Utility functions for constructing agent gain vectors, the forward interaction matrix, and the external task cue vector used in the experiment.

------------------------------------

gaussian_g_vector(average,
                  deviation,
                  number_of_agents)

Create a vector of g values following Gaussian distribution. The average value of the vector is forced to be the average value given as input.

Parameters

• average : float

  • The average value of the Gaussian distribution.

    The average should be greater than 0.0.

• deviation : float

  • The standard deviation of the Gaussian distribution.

    The deviation should be non-negative.

• number_of_agents : int

  • The number of agents in the system.

Return

• g : 1D numpy array

  • A numpy array of size (number_of_agents,) with the g values for all agents in the system.

------------------------------------

uniform_g_vector(average,
                 delta,
                 number_of_agents)

Create a vector of g values following uniform distribution. The average value of the vector is forced to be the average value given as input.

Parameters

• average : float

  • The average value of the uniform distribution.

    The average should be greater than 0.0.

• delta : float

  • The deviation of the uniform distribution.

    The deviation should be non-negative. The deviation should be less or equal to the average.

• number_of_agents : int

  • The number of agents in the system.

Return

• g : 1D numpy array

  • A numpy array of size (number_of_agents,) with the g values for all agents in the system.

------------------------------------

build_forward_matrix(number_of_agent,
                     number_of_tasks,
                     alpha,
                     beta,
                     gamma,
                     delta,
                     task_graph,
                     communication_graph)

Build the forward matrix of the homogeneous system, where the parameter alpha, beta, gamma and delta are the same for all the agents.

Parameters

• number_of_agent : int

  • Number of agents in the system. The number of agents should be greater than 0.

• number_of_tasks : int

  • Number of tasks the agents have to perform. The number of tasks should be greater than 0.

• alpha : float

  • The scalar value that weights the same agent-same task interaction. The value should be non-negative.

• beta : float

  • The scalar value that weights the same agent-different task interaction.

    The value should be non-negative.

• gamma : float

  • The scalar value that weights the different agent-same task interaction.

    The value should be non-negative.

• delta : float

  • The scalar value that weights the different agent-different task interaction. The value should be non-negative.

• task_graph : 2D numpy array

  • The graph between tasks. A positive value means that the tasks are positively correlated, a negative value means that the tasks are negatively correlated. A null value means that the tasks are not correlated.

    The task graph should be of size (No, No).

• communication_graph : 2D numpy array

  • The graph between agents. A positive value means that the agents have a positive interaction, a negative value means that the agents have a negative interaction. A null value means that the agents can not communicate.

    The communication graph should be of size (Na, Na).

Return

• F : 2D numpy array

  • The forward matrix of the system representing the interactions between agents and tasks. The forward matrix is of size (Na * No, Na * No).

------------------------------------

build_cue_vector(number_of_agents,
                 number_of_tasks,
                 number_of_informed,
                 number_of_switches,
                 total_time,
                 initial_steps=0,
                 reversed=False)

Build the cue vector for the experiment. The cue vector is a 2D vector of size (total_time, Na * No) that informs the agents about the tasks they should perform at each time unit. Na is the number of agents and No is the number of tasks. The cue vector has the following characteristics. - The first initial_steps time units are vectors of zero, meaning no tasks are prioritized for all agents. - After, the cue vector has a step function shape with n_switches regular steps, indeed leading agents to switch tasks at regular intervals. Every step has the same length given by (total_time - initial_steps) // number_of_switches. - The first switching step is a vector of 1 for the first task and -1 for all the other tasks, meaning that Task 1 is prioratized. - The vector is then rotated by one position for each step, meaning that now Task 2 is prioratized. etc. - When reversed is True, the cue vector is reversed. - The informed agents are the first number_of_informed agents in the system and are the only ones receiving the task cue. For the other agents, the cue vector elements are zeros.

Parameters

• number_of_agents : int

  • Number of agents in the system. The number of agents should be greater than 0.

• number_of_tasks : int

  • Number of tasks the agents have to perform. The number of tasks should be greater than 0.

• number_of_informed : int

  • Number of agents that are informed about the tasks (that receive the task cue). The number of informed agents should be non-negative and less than or equal to the number of agents.

• number_of_switches : int

  • Number of switches in the cue vector.

    The number of switches should be non-negative.

    The number of switches should be less than or equal to total_time - initial_steps.

• total_time : int

  • Total time of the experiment. The total time should be greater than 0.

• initial_steps : int, optional

  • Number of initial time steps where no task is prioritized. The number of initial steps should be non-negative.

    The number of initial steps should be less than or equal to total_time.

    Default is 0.

• reversed : bool, optional

  • This options is used to reverse the cue vector. If True, the cue vector is reversed.

    Default is False.

Return

• cue_vector : 2D numpy array

  • The cue vector of the experiment. The cue vector is of size (total_time, Na * No).