laser.measles.mixing.gravity

laser.measles.mixing.gravity

laser.measles.mixing.gravity.GravityMixing(scenario=None, params=None)

Bases: BaseMixing

Gravity migration model for spatial mixing.

Computes a spatial mixing matrix where travel probability between patches is proportional to population sizes and inversely proportional to distance:

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

The scenario is optional at construction time. When attached to a model via InfectionParams(mixer=...), the model sets the scenario automatically before the mixing matrix is first computed.

Parameters:

Name	Type	Description	Default
scenario	DataFrame | None	Patch data with pop, lat, and lon columns. None when the model will set it.	None
params	GravityParams | None	Gravity model parameters. Uses GravityParams defaults if None.	None

Example:

```python
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)]
```

laser.measles.mixing.gravity.GravityMixing.get_migration_matrix()

Compute the gravity-based migration matrix.

Returns:

Type	Description
ndarray	Migration matrix of shape (N, N) where entry [i, j] is the probability of travel from patch i to patch j.

laser.measles.mixing.gravity.GravityParams

Bases: BaseModel

Parameters for the gravity migration model.

The gravity kernel computes migration flow as:

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

Parameters:

Name	Type	Description	Default
a	float	Population source exponent (applied as a − 1 inside the kernel).	required
b	float	Population destination exponent.	required
c	float	Distance decay exponent — larger values suppress long-distance travel.	required
k	float	Average trip probability (scales the overall matrix).	required

Example:

```python
from laser.measles.mixing.gravity import GravityParams

params = GravityParams(a=1.0, b=1.0, c=2.0, k=0.01)
```