Simulation class

class defSim.Simulation.Simulation(network=None, topology: str = 'grid', network_modifiers: Optional[List[defSim.network_evolution_sim.network_evolution_sim.NetworkModifier]] = None, attributes_initializer: str = 'random_categorical', focal_agent_selector: str = 'random', neighbor_selector: str = 'random', influence_function: str = 'similarity_adoption', influenceable_attributes: Optional[List] = None, dissimilarity_measure: str = 'hamming', stop_condition: str = 'max_iteration', max_iterations: int = 100000, communication_regime: str = 'one-to-one', parameter_dict={}, seed=None, output_realizations=[], output_folder_path: Optional[str] = None, output_file_types: List[str] = [], tickwise: List[str] = [])

Bases: object

This class is responsible for initializing and running a single experiment until the desired stop criterion is reached. The Simulation class contains three different stop criterion implementations as methods, but more can be added. The class is initialized in a similar way as the Experiment class but it does not accept multiple parameter values per parameter and also all optional parameters are passed in one combined dictionary.

Parameters

network (str nx.Graph=None) – A NetworkX object that was created (e.g. from empirical data) or “list”. If “list”, the network is read from the parameter dict under the ‘network’ parameter.
topology (String = "grid") – Options are “grid”, “ring” and “spatial_random_graph”, or you could give the name of one of the generators included in the NetworkX package..
network_modifiers (NetworkModifier or List = None) – A modifier or list of modifiers to apply to the network after initialization. Each modifier should be derived from the NetworkModifier base class.
attributes_initializer (String = “random_categorical” or AttributesInitializer) – Either be a custom AttributesInitializer or a string that selects from the predefined choices: [“random_categorical”, “random_continuous”…]
focal_agent_selector (str = “random” or FocalAgentSelector) – Either a custom FocalAgentSelector or a string that selects from the predefined options [“random”, …]
neighbor_selector (str = “random” or NeighborSelector) – Either a custom NeighborSelector or a string that selects from the predefined options [“random”, “similar” …}
influence_function (str = “similarity_adoption” or InfluenceOperator) – Either a custom influence function or a string that selects from the predefined options [“similarity_adoption”, “bounded_confidence”, “weighted_linear”, …}
influenceable_attributes (List = None) – This is a list of the attribute names, that may be changed in the influence step
dissimilarity_measure (String = “hamming” or DissimilarityCalculator) – Either a custom DissimilarityCalculator or a string that selects from the predefined options [“hamming”, “euclidean”, …}
stop_condition (str = "max_iteration") – Determines at what point a simulation is supposed to stop. Options include “strict_convergence”, which means that it is theoretically not possible anymore for any agent to influence another, “pragmatic_convergence”, which means that it is assumed that little change is possible anymore, and “max_iteration” which just stops the simulation after a certain amount of time steps.
communication_regime (str = "one-to-one") – Options are “one-to-one”, “one-to-many” and “many-to-one”.
parameter_dict – A dictionary with all parameters that will be passed to the specific component implementations.
seed (str = None) – A seed for stable replication
output_realizations (list = [str or CreateOutputTable.OutputTableCreator]) – This optional list should contain all output to generate at the end of each run, by name for defaults or as class inheriting from OutputTableCreator
output_folder_path (str or pathlib.Path) – If not None, the output table is saved to file(s) in this location.
output_file_types (List[str or DataFileCreator]) – Determines which types of output files will be saved at output_folder_path. See tools.CreateDataFiles for options.
tickwise (List = [str]) – A list of strings with the names of agent attributes that need to be recorded at every timestep

__init__(network=None, topology: str = 'grid', network_modifiers: Optional[List[defSim.network_evolution_sim.network_evolution_sim.NetworkModifier]] = None, attributes_initializer: str = 'random_categorical', focal_agent_selector: str = 'random', neighbor_selector: str = 'random', influence_function: str = 'similarity_adoption', influenceable_attributes: Optional[List] = None, dissimilarity_measure: str = 'hamming', stop_condition: str = 'max_iteration', max_iterations: int = 100000, communication_regime: str = 'one-to-one', parameter_dict={}, seed=None, output_realizations=[], output_folder_path: Optional[str] = None, output_file_types: List[str] = [], tickwise: List[str] = []): Initialize self. See help(type(self)) for accurate signature.

_run_until_convergence(show_progress: bool = False)

The convergence of the simulation is periodically checked using a custom convergence check set in self.stop_condition. Every step_size steps (defaults to 100), the check_convergence method of this custom stop condition is called. The simulation terminates if this method returns true or self.max_iterations is reached.

Parameters

step_size (int=100) – determines how often it should be checked for a change in the network.
show_progress (bool) – bool determines whether to show progress bar

_run_until_max_iteration(show_progress: bool = False)

Parameters: show_progress (bool) – bool determines whether to show progress bar

_run_until_pragmatic_convergence(show_progress: bool = False)

Pragmatic convergence means that each “step_size” time steps it is checked whether the structure of the network and all attributes are still the same. If thats the case, it is assumed that the simulation converged and it stops.

Parameters

step_size (int=100) – determines how often it should be checked for a change in the network.
show_progress (bool) – bool determines whether to show progress bar

_run_until_strict_convergence(show_progress: bool = False)

Here the convergence of the simulation is periodically checked by assessing the distance between each neighbor in the network. Unless there is no single pair left that can theoretically influence each other, the simulation continues.

Parameters

maximum (float=inf) – A value that determines above what maximum distance two agents can’t influence each other anymore.
minimum (float=inf) – A value that determines below what minimum distance two agents can’t influence each other anymore.
step_size (int=100) – determines how often it should be checked for a change in the network.
show_progress (bool) – bool determines whether to show progress bar

create_output_table() → pandas.core.frame.DataFrame

This method measures multiple characteristics of the network in its current state and writes them to a Pandas DataFrame. It contains the following columns:

Seed: The random seed that was used.

Topology: Which network topology was used.

Ticks: For how many iterations the simulation ran (so far).

SuccessfulInfluence: How often an agent was successfully influenced by another agent.

All basic columns included in create_output_table()

Saves the output table to file(s) indicated by self.output_file_types if self.output_folder_path is not None.

Returns: A Pandas DataFrame with one row.

initialize(): This method initializes the network if none is given, applies network modifiers, initializes the attributes of the agents, and also computes and sets the distances between each neighbor.

initialize_simulation(): Will be deprecated in favor of Simulation.initialize(). Replace in code, will be removed at or before v1.0.0

initialize_tickwise_output()

return_values() → pandas.core.frame.DataFrame

This method returns the values stored in the Simulation object. Both default, and user-specified values are returned to the console to make the Simulation object more transparent.

Returns: A Pandas DataFrame with the parameter settings

run(initialize: bool = True, show_progress: bool = True) → pandas.core.frame.DataFrame

This method initializes the network if none is given, initializes the attributes of the agents, and also computes and sets the distances between each neighbor. It then calls different functions that execute the simulation based on which stop criterion was selected.

Parameters

initialize (bool=True) – Initialize the simulation before running (disable if initialization was done separately)
show_progress (bool=True) – Whether to show progress bar

Returns

A Pandas DataFrame that contains one row of data. To see what output the output contains see create_output_table()

run_simulation(initialize: bool = True) → pandas.core.frame.DataFrame: Will be deprecated in favor of Simulation.run(). Replace in code, will be removed at or before v1.0.0

run_simulation_step(): Will be deprecated in favor of Simulation.run_step(). Replace in code, will be removed at or before v1.0.0

run_step(): Executes one iteration of the simulation step which includes the selection of a focal agent, the selection of the neighbors and the influence step. If the user passed their own implementations of those components, they will be called to execute these steps, otherwise the respective factory functions will be called.