pyGD.agents module

Agents that act on graph dynamics.

Yokai

The mobile feedback-control agent of Sowinski, Frank & Ghoshal, PRR 6, 043188 (2024). It hops node-to-node on the graph, estimates the local mean field at each node it visits, and kicks that oscillator’s phase to oppose local synchrony – a Maxwell’s-demon-style desynchronizer. Ported from Yokai.m; evolve mutates the passed environment in place, matching the MATLAB handle-class semantics.

class pyGD.agents.Yokai(strength, beta, env, noise=0.0, rng=None)[source]

Bases: object

A localized, mobile perturbation living on a Kuramoto environment.

Ported from Yokai.m. Per environment step the agent performs speed sub-steps; in each it estimates the neighborhood mean-field angle at its current node, kicks the node’s phase by +/- strength (opposing the sign of sin(theta_loc - phi_est)), then hops to a uniformly random neighbor.

Parameters:

  • strength (float) – Kick magnitude (alpha), applied with sign sign(sin(theta - phi_est)).

  • beta (float) – Hop-speed parameter; speed = max(1, ceil(beta * env.N)) sub-steps per environment step.

  • env (Kuramoto) – The environment the agent lives on (used here to size speed and to pick the initial location).

  • noise (float, optional) – Sensor noise (eta) in [0, 1]. When > 0 the mean-field estimate is perturbed by noise * (2*U - 1) * pi. Default 0.

  • rng (numpy.random.Generator, optional) – Random source; defaults to numpy.random.default_rng().

speed

Number of sub-steps per environment step.

Type:

int

loc

Current node index.

Type:

int

T

Accumulated agent time (incremented by env.dt each evolve()).

Type:

float

Examples

>>> import networkx as nx, numpy as np
>>> from pyGD.dynamics import Kuramoto
>>> G = nx.erdos_renyi_graph(50, 0.1, seed=0)
>>> rng = np.random.default_rng(0)
>>> env = Kuramoto(0.5, G, rng.standard_normal(50), rng=rng)
>>> yok = Yokai(0.5, 0.16, env, rng=rng)
>>> for _ in range(10):
...     _ = yok.evolve(env)
...     _ = env.evolve()
>>> bool(0 <= yok.loc < env.N)
True
evolve(env)[source]

Advance the agent over one environment step, mutating env.

Performs speed measure-kick-hop sub-steps on env.thetas.