Topology Generators

3.2 Topology Generators

The SDK provides six deterministic topology generators that create standard graph structures by wiring agents with links. All generators are pure functions that take a model, agent type name, and link type name, and return the number of links created. They use the model's SeedManager for any stochastic choices, ensuring reproducibility.

from simudyne.engine.topology import (
    fully_connected, ring, small_world, scale_free, grid, from_data,
)

Generator	Signature	Graph Structure
fully_connected	(model, agent_type, link_type) -> int	Complete graph: every agent linked to every other. O(N^2) links.
ring	(model, agent_type, link_type) -> int	Ring lattice: each agent linked to its two immediate neighbours. O(N) links.
small_world	(model, agent_type, link_type, k=4, p=0.1) -> int	Watts-Strogatz: start with k-nearest ring, rewire each edge with probability p. Produces high clustering + short path lengths.
scale_free	(model, agent_type, link_type, m=2) -> int	Barabasi-Albert preferential attachment: each new node attaches to m existing nodes with probability proportional to degree. Produces power-law degree distribution.
grid	(model, agent_type, link_type, rows, cols, wrap=False) -> int	2D grid lattice: 4-connected (Von Neumann). Optional toroidal wrapping.
from_data	(model, link_type, edges: Sequence[Tuple[str, str, float]]) -> int	User-provided edge list: each tuple is (source_id, target_id, weight). For loading empirical networks.

Usage example --- creating an interbank network:

from simudyne.engine.topology import scale_free

class GaiKapadiaModel(ABMModel):
    def setup(self, config):
        super().setup(config)
        banks = self.create_agents("Bank", config["num_banks"])
        # Barabasi-Albert scale-free network: each bank connects to m=2 existing banks
        num_links = scale_free(self, "Bank", "interbank", m=2)
        # Result: power-law degree distribution where a few "too-big-to-fail" banks
        # have many connections, and most banks have few.

The from_data() generator is particularly useful for empirical network models where the topology comes from real-world data (e.g., interbank lending networks from central bank datasets, supply chain relationships from trade data, or social contact networks from mobility data).

---