Configure mobility¶
This guide shows you how to set the three parameters that drive inter-patch movement in laser.cholera: the per-patch outflow tau_i, the destination-population exponent mobility_omega, and the distance-decay exponent mobility_gamma. It assumes you already have a working multi-patch parameter set and just need to dial mobility in (or turn it off).
Prerequisites¶
laser-cholerainstalled in your environment.- A working multi-patch configuration —
npatches >= 2, with per-patchlongitude,latitude, andN_j_initialalready populated. - You have completed the multi-location-country tutorial or are otherwise comfortable building a
Modelfrom a parameter dict.
laser.cholera does not accept a precomputed pi_ij
The coupling matrix is computed internally each tick from latitude, longitude, N, mobility_omega, mobility_gamma, and tau_i via get_pi_from_lat_long in src/laser/cholera/metapop/utils.py. There is no parameter slot to inject your own matrix. For a canonical reference implementation of the same gravity kernel, see the gravity model shipped in laser.core — useful when verifying the math by hand or when writing tutorials.
Steps¶
-
Turn mobility off (optional). Set
tau_ito a zero vector. This is the canonical inert form — patches no longer exchange infectious or environmentally-exposed individuals, andpi_ijdrops out of the dynamics even though it is still assembled internally.import numpy as np params["tau_i"] = np.zeros(npatches, dtype=np.float32) params["mobility_omega"] = 1.0 params["mobility_gamma"] = 1.0mobility_omegaandmobility_gammaare still required byvalidate_parameters— there is no off-form for these two — so leave them at any sane float (e.g.1.0). They have no effect on the run whentau_i = 0. -
Set per-patch
tau_i. Each element is the proportion of the patch leaving per tick, constrained to[0, 1]. Typical values are0.001–0.05. A flat vector is fine for an illustrative configuration: -
Choose
mobility_omega. This scalar is the exponent applied to the destination population in the gravity kernel. Higher values bias flow toward more populous destinations. Typical range0.5–2.0: -
Choose
mobility_gamma. This scalar is the exponent applied to the distance penalty. Higher values make flow drop off faster with distance. Typical range1.0–3.0: -
Verify
pi_ijafter the run. Aftermodel.run(), inspectmodel.patches.pi_ij. Its shape is(npatches, npatches), the diagonal is zero, and each row sums to 1:
Full example¶
import numpy as np
from laser.cholera.metapop.model import run_model
from laser.cholera.metapop.params import get_parameters
# Start from the bundled defaults to discover npatches; the gravity-model
# `pi_ij` is a derived `(npatches, npatches)` matrix on `model.patches`.
defaults = get_parameters(None, do_validation=False)
npatches = len(defaults.location_name)
mods = {
"tau_i": np.full(npatches, 0.01, dtype=np.float32),
"mobility_omega": 1.0,
"mobility_gamma": 1.5,
}
model = run_model(None, **mods)
pi_ij = model.patches.pi_ij
assert pi_ij.shape == (npatches, npatches)
assert np.allclose(pi_ij.sum(axis=1), 1.0, atol=1e-4)
See also¶
- Geography & mobility parameter reference — full parameter spec, shapes, validator behaviour.
- Mobility explanation — the gravity-model derivation of
pi_ijand howtau_i,mobility_omega,mobility_gammaenter the force-of-infection. - Multi-location country tutorial — Step 8 shows mobility spreading a seeded outbreak via
pi_ij.