Complete Api Reference

This module provides the main interface to the pyseldonlib package.

It includes the following classes and functions: - DeGrootModel - Deffuant_Model - Deffuant_Vector_Model - Inertial_Model - Activity_Driven_Model - Other_Settings - Network - run_simulation_from_config_file - run_simulation_from_options - parse_config_file

class pyseldonlib.__init__.Activity_Driven_Model(max_iterations: int = None, dt: float = 0.01, m: int = 10, eps: float = 0.01, gamma: float = 2.1, alpha: float = 3.0, homophily: float = 0.5, reciprocity: float = 0.5, K: float = 3.0, mean_activities: bool = False, mean_weights: bool = False, n_bots: int = 0, bot_m: list[int] = [], bot_activity: list[float] = [], bot_opinion: list[float] = [], bot_homophily: list[float] = [], use_reluctances: int = False, reluctance_mean: float = 1.0, reluctance_sigma: float = 0.25, reluctance_eps: float = 0.01, covariance_factor: float = 0.0, rng_seed: int | None = None, agent_file: str | None = None, network_file: str | None = None, other_settings: Other_Settings = None)

Bases: Base_Model

Activity Driven Model base class for Simulation.

Parameters:

• max_iterations (int, default=None) – The maximum number of iterations to run the simulation. If None, the simulation runs infinitely.

• dt (float, default=0.01) – The time step for the simulation.

• m (int, default=10) – Number of agents contacted, when the agent is active.

• eps (float, default=0.01) – The minimum activity epsilon.

• gamma (float, default=2.1) – Exponent of activity power law distribution of activities.

• alpha (float default=3.0) – Controversialness of the issue, must be greater than 0.

• homophily (float, default=0.5) –

  The extent to which similar agents interact with similar other. Example: If 0.0, agents pick their interaction partners at random.

  If 1.0, agents interact only with agents of the same opinion.

• reciprocity (float, default=0.5) –

  The extent to which agents reciprocate interactions. Example: If 0.0, agents do not reciprocate interactions.

  If 1.0, agents reciprocate all interactions.

• K (float, default=3.0) – Social interaction strength.

• mean_activities (bool, default=False) – Whether use the mean value of the powerlaw distribution for the activities of all agents.

• mean_weights (bool, default=False) – Whether use the meanfield approximation of the network edges, by default is False.

• n_bots (int, default=0) – Number of bots in the simulation.

• note:: (..) – Bots are agents that are not influenced by the opinions of other agents, but they can influence the opinions of other agents. So they have fixed opinions and different parameters, the parameters are specified in the following lists.

• bot_m (list[int], default=[]) – Value of m for the bots, If not specified, defaults to m.

• bot_activity (list[float], default=[],) – The list of bot activities, If not specified, defaults to 0.

• bot_opinion (list[float], default=[]) – The fixed opinions of the bots.

• bot_homophily (list[float], default=[]) – The list of bot homophily, If not specified, defaults to homophily.

• use_reluctances (int, default=False) – Whether use reluctances, by default is False and every agent has a reluctance of 1.

• reluctance_mean (float, default=1.0) – Mean of distribution before drawing from a truncated normal distribution.

• reluctance_sigma (float, default=0.25) – Width of normal distribution (before truncating).

• reluctance_eps (float, default=0.01) – Minimum such that the normal distribution is truncated at this value.

• covariance_factor (float, default=0.0) – Covariance Factor, defines the correlation between reluctances and activities.

• rng_seed (int, default=None) – The seed for the random number generator. If not provided, a random seed is picked.

• agent_file (str, default=None) – The file to read the agents from. If None, the agents are generated randomly.

• network_file (str, default=None) – The file to read the network from. If None, the network is generated randomly

• other_settings (Other_Settings, default=None) – The other settings for the simulation. If None, the default settings are used.

Network

The network generated by the simulation.

Type:

Network (Object)

Opinion

The opinions of the agents or nodes of the network.

Type:

Float

property Network

Access the network generated by the simulation.

Returns:

The network generated by the simulation.

Return type:

seldoncore.Network

agent_activity(index: int = None)

Access the agents activity data from the simulated network.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

agent_opinion(index: int = None)

Access the agents data from the simulation.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

agent_reluctance(index: int = None)

Access the agents reluctance data from the simulated network.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

print_settings()

Print the settings of the simulation.

run(output_dir: str = None)

Run the simulation.

Parameters:

output_dir (str, default="./output") – The directory to output the files to.

set_agent_activity(index: int, activity: float)

Set the activity of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• activity (float) – The new activity value for the agent.

set_agent_opinion(index: int, opinion: float)

Set the opinion of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• opinion (float) – The new opinion value for the agent.

set_agent_reluctance(index: int, reluctance: float)

Set the reluctance of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• reluctance (float) – The new reluctance value for the agent.

class pyseldonlib.__init__.DeGroot_Model(max_iterations: int = None, convergence_tol: float = 1e-06, rng_seed: int | None = None, agent_file: str | None = None, network_file: str | None = None, other_settings: Other_Settings = None)

Bases: Base_Model

DeGroot Model base class for Simulation.

Parameters:

• max_iterations (int, default=None) – The maximum number of iterations to run the simulation. If None, the simulation runs infinitely.

• convergence_tol (float, default=1e-6) – The tolerance for convergence of the simulation.

• rng_seed (int, default=None) – The seed for the random number generator. If not provided, a random seed is picked.

• agent_file (str, default=None) – The file to read the agents from. If None, the agents are generated randomly.

• network_file (str, default=None) – The file to read the network from. If None, the network is generated randomly

• other_settings (Other_Settings, default=None) – The other settings for the simulation. If None, the default settings are used.

Network

The network generated by the simulation.

Type:

Network (Object)

Opinion

The opinions of the agents or nodes of the network.

Type:

Float

see also

Type:

seldoncore.Network

property Network

Access the network generated by the simulation.

Returns:

The network generated by the simulation.

Return type:

seldoncore.Network

agent_opinion(index: int = None)

Access the agents data from the simulation.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

print_settings()

Print the settings of the simulation.

run(output_dir: str = None)

Run the simulation.

Parameters:

output_dir (str, default="./output") – The directory to output the files to.

set_agent_opinion(index: int, opinion: float)

Set the opinion of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• opinion (float) – The new opinion value for the agent.

class pyseldonlib.__init__.Deffuant_Model(max_iterations: int = None, homophily_threshold: float = 0.2, mu: float = 0.5, use_network: bool = False, rng_seed: int | None = None, agent_file: str | None = None, network_file: str | None = None, other_settings: Other_Settings = None)

Bases: Base_Model

Deffuant Model base class for Simulation.

Parameters:

• max_iterations (int, default=None) – The maximum number of iterations to run the simulation. If None, the simulation runs infinitely.

• homophily_threshold (float, default=0.2) – The threshold for homophily. If the difference in opinions between two agents is less than this value, they interact.

• mu (float, default=0.5) – The convergence rate of the agents.

• use_network (bool, default=False) – For using a square lattice network. Will throw error if sqrt(n_agents) is not an integer.

• rng_seed (int, default=None) – The seed for the random number generator. If not provided, a random seed is picked.

• agent_file (str, default=None) – The file to read the agents from. If None, the agents are generated randomly.

• network_file (str, default=None) – The file to read the network from. If None, the network is generated randomly

• other_settings (Other_Settings, default=None) – The other settings for the simulation. If None, the default settings are used.

Network

The network generated by the simulation.

Type:

Network (Object)

Opinion

The opinions of the agents or nodes of the network.

Type:

Float

property Network

Access the network generated by the simulation.

Returns:

The network generated by the simulation.

Return type:

seldoncore.Network

agent_opinion(index: int = None)

Access the agents data from the simulation.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

print_settings()

Print the settings of the simulation.

run(output_dir: str = None)

Run the simulation.

Parameters:

output_dir (str, default="./output") – The directory to output the files to.

set_agent_opinion(index: int, opinion: float)

Set the opinion of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• opinion (float) – The new opinion value for the agent.

class pyseldonlib.__init__.Deffuant_Vector_Model(max_iterations: int = None, homophily_threshold: float = 0.2, mu: float = 0.5, use_network: bool = False, dim: int = 1, rng_seed: int | None = None, agent_file: str | None = None, network_file: str | None = None, other_settings: Other_Settings = None)

Bases: Base_Model

Deffuant Vector Model base class for Simulation.

Parameters:

• max_iterations (int, default=None) – The maximum number of iterations to run the simulation. If None, the simulation runs infinitely.

• homophily_threshold (float, default=0.2) – The threshold for homophily. If the difference in opinions between two agents is less than this value, they interact.

• mu (float, default=0.5) – The convergence rate of the agents.

• use_network (bool, default=False) – For using a square lattice network. Will throw if sqrt(n_agents) is not an integer.

• dim (int, default=1) – For the multi-dimensional binary vector Deffuant model, define the number of dimensions in each opinion vector

• rng_seed (int, default=None) – The seed for the random number generator. If not provided, a random seed is picked.

• agent_file (str, default=None) – The file to read the agents from. If None, the agents are generated randomly.

• network_file (str, default=None) – The file to read the network from. If None, the network is generated randomly

• other_settings (Other_Settings, default=None) – The other settings for the simulation. If None, the default settings are used.

Network

The network generated by the simulation.

Type:

Network (Object)

Opinion

The opinions of the agents or nodes of the network.

Type:

Float

property Network

Access the network generated by the simulation.

Returns:

The network generated by the simulation.

Return type:

seldoncore.Network

agent_opinion(index: int = None)

Access the agents data from the simulation.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

print_settings()

Print the settings of the simulation.

run(output_dir: str = None)

Run the simulation.

Parameters:

output_dir (str, default="./output") – The directory to output the files to.

set_agent_opinion(index: int, opinion: float)

Set the opinion of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• opinion (float) – The new opinion value for the agent.

class pyseldonlib.__init__.Inertial_Model(max_iterations: int = None, dt: float = 0.01, m: int = 10, eps: float = 0.01, gamma: float = 2.1, alpha: float = 3.0, homophily: float = 0.5, reciprocity: float = 0.5, K: float = 3.0, mean_activities: bool = False, mean_weights: bool = False, n_bots: int = 0, bot_m: list[int] = [], bot_activity: list[float] = [], bot_opinion: list[float] = [], bot_homophily: list[float] = [], use_reluctances: int = False, reluctance_mean: float = 1.0, reluctance_sigma: float = 0.25, reluctance_eps: float = 0.01, covariance_factor: float = 0.0, friction_coefficient: float = 1.0, rng_seed: int | None = None, agent_file: str | None = None, network_file: str | None = None, other_settings: Other_Settings = None)

Bases: Activity_Driven_Model

Inertial Model base class for Simulation.

Parameters:

• max_iterations (int, default=None) – The maximum number of iterations to run the simulation. If None, the simulation runs infinitely.

• dt (float, default=0.01) – The time step for the simulation.

• m (int, default=10) – Number of agents contacted, when the agent is active.

• eps (float, default=0.01) – The minimum activity epsilon.

• gamma (float, default=2.1) – Exponent of activity power law distribution of activities.

• alpha (float default=3.0) – Controversialness of the issue, must be greater than 0.

• homophily (float, default=0.5) –

  The extent to which similar agents interact with similar other. Example: If 0.0, agents pick their interaction partners at random.

  If 1.0, agents interact only with agents of the same opinion.

• reciprocity (float, default=0.5) –

  The extent to which agents reciprocate interactions. Example: If 0.0, agents do not reciprocate interactions.

  If 1.0, agents reciprocate all interactions.

• K (float, default=3.0) – Social interaction strength.

• mean_activities (bool, default=False) – Whether use the mean value of the powerlaw distribution for the activities of all agents.

• mean_weights (bool, default=False) – Whether use the meanfield approximation of the network edges, by default is False.

• n_bots (int, default=0) – Number of bots in the simulation.

• note:: (..) – Bots are agents that are not influenced by the opinions of other agents, but they can influence the opinions of other agents. So they have fixed opinions and different parameters, the parameters are specified in the following lists.

• bot_m (list[int], default=[]) – Value of m for the bots, If not specified, defaults to m.

• bot_activity (list[float], default=[],) – The list of bot activities, If not specified, defaults to 0.

• bot_opinion (list[float], default=[]) – The fixed opinions of the bots.

• bot_homophily (list[float], default=[]) – The list of bot homophily, If not specified, defaults to homophily.

• use_reluctances (int, default=False) – Whether use reluctances, by default is False and every agent has a reluctance of 1.

• reluctance_mean (float, default=1.0) – Mean of distribution before drawing from a truncated normal distribution.

• reluctance_sigma (float, default=0.25) – Width of normal distribution (before truncating).

• reluctance_eps (float, default=0.01) – Minimum such that the normal distribution is truncated at this value.

• covariance_factor (float, default=0.0) – Covariance Factor, defines the correlation between reluctances and activities.

• rng_seed (int, default=None) – The seed for the random number generator. If not provided, a random seed is picked.

• agent_file (str, default=None) – The file to read the agents from. If None, the agents are generated randomly.

• network_file (str, default=None) – The file to read the network from. If None, the network is generated randomly

• other_settings (Other_Settings, default=None) – The other settings for the simulation. If None, the default settings are used.

• friction_coefficient (float, default=1.0) – The friction coefficient for the inertial model.

Network

The network generated by the simulation.

Type:

Network (Object)

Opinion

The opinions of the agents or nodes of the network.

Type:

Float

Activity

The activity of the agents or nodes of the network.

Type:

Float

Reluctance

The reluctance of the agents or nodes of the network.

Type:

Float

property Network

Access the network generated by the simulation.

Returns:

The network generated by the simulation.

Return type:

seldoncore.Network

agent_activity(index: int = None)

Access the agents activity data from the simulated network.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

agent_opinion(index: int = None)

Access the agents data from the simulation.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

agent_reluctance(index: int = None)

Access the agents reluctance data from the simulated network.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

agent_velocity(index: int = None)

Access the agents reluctance data from the simulated network.

Parameters:

index (int) – The index of the agent to access. The index is 0-based. If not provided, all agents are returned.

print_settings()

Print the settings of the simulation.

run(output_dir: str = None)

Run the simulation.

Parameters:

output_dir (str, default="./output") – The directory to output the files to.

set_agent_activity(index: int, activity: float)

Set the activity of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• activity (float) – The new activity value for the agent.

set_agent_opinion(index: int, opinion: float)

Set the opinion of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• opinion (float) – The new opinion value for the agent.

set_agent_reluctance(index: int, reluctance: float)

Set the reluctance of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• reluctance (float) – The new reluctance value for the agent.

set_agent_velocity(index: int, velocity: float)

Set the velocity of a specific agent.

Parameters:

• index (int) – The index of the agent whose opinion is to be set.

• velocity (float) – The new velocity value for the agent.

class pyseldonlib.__init__.Network(model_string: str = None, n_agents: int = None, agents: int = None, neighbour_list: list[int] = [], weight_list: list[float] = [], direction: str = 'Incoming')

Bases: object

property clear

Clears the network.

property get_direction

The direction of the network.

get_neighbours(index: int)

The neighbours of the node/agent in the network.

Parameters:

index (int) – The index of the agent.

get_weights(index: int)

The weights of the agent.

Parameters:

index (int) – The index of the agent.

property n_agents

The number of nodes/agents in the network.

n_edges(agent_idx: int)

The number of edges going out/coming in at agent_idx in the network.

Parameters:

agent_idx (int) – The index of the agent. If not provided, the total number of edges in the network is returned.

push_back_neighbour_and_weight(agent_idx_i: int, agent_idx_j: int, weight: float)

Adds an edge between agent_idx_i and agent_idx_j with weight w

Parameters:

• agent_idx_i (int) – The index of the agent.

• agent_idx_j (int) – The index of the agent.

• weight (float) – The weight of the agent.

property remove_double_counting

Sorts the neighbours by index and removes doubly counted edges by summing the weights of the corresponding edges.

set_neighbours_and_weights(agent_idx: int, buffer_neighbours: list[int], weight: float)

Sets the neighbour indices and sets the weight to a constant value at agent_idx in the network.

Parameters:

• agent_idx (int) – The index of the agent.

• buffer_neighbours (list[int]) – The list of neighbours.

• weight (float) – The weight of the agent.

set_weights(agent_idx: int, weights: list)

Set the weights of the agent.

Parameters:

• index (int) – The index of the agent.

• weights (list[float]) – The weights of the agent.

property strongly_connected_components

The strongly connected components of the network.

Returns

list: The strongly connected components of the network.

property switch_direction_flag

Only switches the direction flag. This effectively transposes the network and, simultaneously, changes its representation.

property toggle_incoming_outgoing

Switches the direction flag without transposing the network (expensive)

property transpose

Transposes the network, without switching the direction flag (expensive).

class pyseldonlib.__init__.Other_Settings(n_output_agents: int | None = None, n_output_network: int | None = None, print_progress: bool = False, output_initial: bool = True, start_output: int = 1, start_numbering_from: int = 0, number_of_agents: int = 200, connections_per_agent: int = 10)

Bases: object

All other settings for the simulation.

Parameters:

• n_output_agents (int, default=None) – Write out the agents every n iterations.

• n_output_network (int, default=None) – Write out the network every n iterations.

• print_progress (bool, default=False) – Print the progress of the simulation.

• output_initial (bool, default=True) – Output initial opinions and network.

• start_output (int, default=1) – Start printing opinion and/or network files from this iteration number.

• start_numbering_from (int, default=0) – The initial step number, before the simulation runs, is this value. The first step would be (1+start_numbering_from).

• number_of_agents (int, default=200) – The number of agents in the network.

• connections_per_agent (int, default=10) – The number of connections per agent.

pyseldonlib.__init__.parse_config_file(file_path: str)

Parse the toml file and create the simulation options object.

Parameters:

file_path (str) – The path to the toml file.

Returns:

Simulation

Return type:

The simulation object.

pyseldonlib.__init__.run_simulation_from_config_file(config_file_path: str, agent_file_path: str | None = None, network_file_path: str | None = None, output_dir_path: str | None = None)

Run the simulation using the configuration(toml) file.

Parameters:

• config_file_path (str) – The path to the configuration(toml) file.

• agent_file_path (str, optional) – The path to the agent file.

• network_file_path (str, optional) – The path to the network file.

• output_dir_path (str, deafult="./output")

pyseldonlib.__init__.run_simulation_from_options(options: object, agent_file_path: str | None = None, network_file_path: str | None = None, output_dir_path: str | None = None)

Run the simulation using the simulation options object.

Note

The options object must be created using the SimulationOptions class.

Parameters:

• options (object) – The simulation options object.

• agent_file_path (str, optional) – The path to the agent file.

• network_file_path (str, optional) – The path to the network file.

• output_dir_path (str, optional) – The path to the output directory.