Python package reference

Documentation for the Modelpy Python package.

AgentModel Class definition

By default, each instance of the AgentModel class is initialized with the following attributes and parameters:

class AgentModel:
    def __init__(self):
        self.__parameters = {
            "num_nodes": 3,
            "graph_type": "complete",
            "convergence_data_key": None,
            "convergence_std_dev": 100,
        }
        self.__graph: nx.Graph = None
        self.initial_data_function = None
        self.timestep_function = None

Note: you cannot remove any of the default parameters.

Model Parameters

Updating model parameters

update_parameters(self, parameters: dict) -> None

Description

Updates the parameters dictionary.

Example usage

model.update_parameters({"num_nodes": 7, "default_bias": 0.11})

You can also use Python subscript syntax to update or set individual parameter values. For example:

model["num_nodes"] = 7
model["default_bias"] = 0.11

Deleting model parameters

delete_parameters(self, parameters: list = None) -> None

Description

Takes a list of parameter keys and deletes each key from the parameters dictionary.
If no parameters are passed in, then this method will reset the model's parameters to its defaults. If a default parameter or non-existent parameter is passed in, this method will raise an exception. Returns true if the deletion was successful.

Example usage

model.delete_parameters(["default_bias])

Graph methods

Getting and setting the model's graph attribute

get_graph()
set_graph(graph: nx.Graph)

Example usage

graph = model.get_graph()
model.set_graph(graph)

Initial data & graph functions

Setting the model's initial data function

set_initial_data_function(initial_data_function: Callable)

Description

The Modelpy package enables users to write their own function to
set the initial data of each node in the graph.
Your function must:

• take your AgentModel object as a parameter
• return a dictionary representing the initial data of each node in the graph.

Example usage

# Define the function to generate each node's initial data
def genInitialData(model):
    return {"x_location": random.randint(-10, 10), "y_location": random.randint(-10, 10)}

# Set the initial_data function
model.set_initial_data_function(genInitialData)

Setting the model's timestep function

set_timestep_function(timestep_function: Callable)

Description

The Modelpy package also enables users to write their own function to
set the data for each node during the model's timesteps.
Your function must:

• take your AgentModel object as a parameter
• return a dictionary representing the node data of each node in the graph after it has been mutated

Example usage

# Define the function to mutate each node during the timestep.
def genTimestepData(model: AgentModel, nodeData: dict):
    nodeData["x_location"] += random.randint(-1, 1)
    nodeData["y_location"] += random.randint(-1, 1)
    return nodeData

Convergence

The Modelpy Python package also includes functionality for users to automatically run their model's timestep function until all of the values for a specified node data_key converge or until timestep t = 10000.

Running to convergence

Description

This function timesteps the model until Timesteps the model until time = 10000 or until the specified convergence_data_key variable has converged to within the specified convergence_std_dev for all nodes. Returns the timestep t of convergence. If you plan to run your model to convergence, be sure to:

• Set the convergence_data_key variable to a valid data_key for nodes in your model.
• Set the convergence_std_dev variable accordingly.

Example usage

model["convergence_data_key"] = "x_location"
model["convergence_std_dev"] = 2
t_convergence = model.run_to_convergence()
print(f"X position of all nodes converges at {t_convergence}.")