GravityMixing

class GravityMixing(scenario=None, params=None)

Bases: BaseMixing

Gravity migration model.

Computes a spatial mixing matrix based on patch populations and distances:

\[M_{i,j} = k \cdot p_i^{a-1} \cdot p_j^b \cdot d_{i,j}^{-c}\]

The scenario argument is optional. When this mixer is attached to a model via InfectionParams(mixer=...) the model automatically sets the scenario before the mixing matrix is first computed (lazy initialisation). You only need to pass scenario explicitly when using the mixer standalone (e.g. to inspect the matrix before running a simulation).

Parameters:

• scenario (DataFrame | None) – Patch data with id, lat, lon, pop, and mcv1 columns. If None, must be set before the mixing matrix is accessed (happens automatically when the mixer is attached to a model component).

• params (GravityParams | None) – Gravity model parameters. Uses GravityParams defaults if None.

Examples

Typical usage — let the model set the scenario automatically:

from laser.measles.mixing.gravity import GravityMixing, GravityParams
from laser.measles.compartmental import components
from laser.measles import create_component

mixer = GravityMixing(params=GravityParams(a=1.0, b=1.0, c=2.0, k=0.01))
infection_params = components.InfectionParams(beta=0.8, mixer=mixer)
model.components = [create_component(components.InfectionProcess, infection_params)]

Standalone usage (inspect the matrix before running):

mixer = GravityMixing(scenario=scenario, params=GravityParams(c=2.0, k=0.01))
print(mixer.mixing_matrix)

get_migration_matrix()

Initialize a migration/diffusion matrix for population mixing. The diffusion matrix is a square matrix where each row represents the outbound migration from a given patch to all other patches e.g., [i,j] = [from_i, to_j].

Convention is: - Trips into node j: N_i @ M[i,j] - Trips out of node i: np.sum(M[i,j] * N_i[:,np.newaxis], axis=1)

Returns:

The diffusion matrix: (N, N)

Return type:

ndarray