Skip to content

epymorph.simulator.world_list

A World implementation -- ListWorld -- which tracks the simulation state's movement cohorts in a Python list-of-lists.

Cohort 

Cohort(
    compartments: NDArray[SimDType],
    return_location: int,
    return_tick: int,
)

Represents a group of individuals, divided into IPM compartments as appropriate for the simulation. These individuals share the same "home location" and a time at which they should return there.

These are somewhat abstract concepts, however; a completely nomadic group doesn't really have a home location, merely the next location in a chain of movements.

Parameters:

  • compartments (NDArray[SimDType]) –

    The group membership by compartment. A (C,)-shaped array.

  • return_location (int) –

    The location to which this cohort will return, or if they are home, the location where they currently are.

  • return_tick (int) –

    The simulation tick on which they will return. -1 implies never.

SORT_KEY class-attribute instance-attribute 

SORT_KEY: ClassVar = attrgetter(
    "return_tick", "return_location"
)

The natural sort order of a Cohort.

compartments instance-attribute 

compartments: NDArray[SimDType] = compartments

The group membership by compartment. A (C,)-shaped array.

return_location instance-attribute 

return_location: int = return_location

The location to which this cohort will return, or if they are home, the location where they currently are.

return_tick instance-attribute 

return_tick: int = return_tick

The simulation tick on which they will return. -1 implies never.

can_merge_with 

can_merge_with(other: Self) -> bool

Check if two cohorts can be merged.

Cohorts at the same location with the same return location and tick can act as a single group.

Parameters:

  • other (Self) –

    The other cohort to consider.

Returns:

  • bool –

    True if these cohorts can be merged.

merge_from 

merge_from(from_cohort: Self) -> None

Merge another cohort into this one, modifying in-place.

Parameters:

  • from_cohort (Self) –

    The other cohort to be "absorbed" into this one.

ListWorld 

ListWorld(locations: list[list[Cohort]])

Bases: World

A world model which which tracks the simulation state's movement cohorts in a Python list-of-lists. That is, the world is a list of locations, and each location is a list of cohorts.

Parameters:

  • locations (list[list[Cohort]]) –

    The initial state of the world. It is assumed there is at least one location and at least one cohort at each.

HOME_TICK class-attribute instance-attribute 

HOME_TICK: ClassVar = -1

The value of a population's return_tick when the population is home.

nodes instance-attribute 

nodes: int = len(locations)

The number of simulation nodes.

compartments instance-attribute 

compartments: int = shape[0]

The number of disease compartments.

locations instance-attribute 

locations: list[list[Cohort]] = locations

All locations and all cohorts at each location.

from_initials classmethod 

from_initials(
    initial_compartments: NDArray[SimDType],
) -> Self

Create a world with the given initial state given as a numpy array.

Everyone is assumed to be in their home location, there are no travelers.

Parameters:

  • initial_compartments (NDArray[SimDType]) –

    An (N,C)-shaped array of the compartment population at each node.

Returns:

  • Self –

    The new world instance.

normalize 

normalize() -> None

Sorts all cohorts within each location and combines mergeable cohorts (in place). The world should be normalized after any modification.

get_cohorts 

get_cohorts(location_idx: int) -> Sequence[Cohort]

Iterate over the cohorts present in a single location.

Parameters:

  • location_idx (int) –

    The index of the location.

Returns:

get_cohort_array 

get_cohort_array(location_idx: int) -> NDArray[SimDType]

Retrieve the cohorts in a single location as a numpy array.

Parameters:

  • location_idx (int) –

    The index of the location.

Returns:

  • NDArray[SimDType] –

    The cohorts at the location. This is an (X,C)-shaped array where X is the number of cohorts, which can be arbitrarily long.

get_local_array 

get_local_array() -> NDArray[SimDType]

Get the local populations of each node.

This is the individuals which are theoretically eligible for movement.

Returns:

get_local_cohorts 

get_local_cohorts() -> Iterable[Cohort]

Iterate over all locations returning just the local cohort from each.

Returns:

apply_cohort_delta 

apply_cohort_delta(
    location_idx: int, delta: NDArray[SimDType]
) -> None

Apply a transition delta for all cohorts at the given location, updating the populations in each compartment.

Parameters:

  • location_idx (int) –

    The index of the location.

  • delta (NDArray[SimDType]) –

    The transitions delta, an (X,C)-shape array where X is the number of cohorts and each value is the net positive or negative change to the compartment's population.

apply_travel 

apply_travel(
    travelers: NDArray[SimDType], return_tick: int
) -> None

Apply travel flows to the entire world, updating the cohorts at each location.

Parameters:

  • travelers (NDArray[SimDType]) –

    An (N,N,C)-shaped array determining who should travel -- from-source-to-destination-by-compartment.

  • return_tick (int) –

    The tick on which any newly-moved cohort should return home.

apply_return 

apply_return(
    tick: Tick, *, return_stats: bool
) -> NDArray[SimDType] | None

Apply return-home flows to the entire world, updating the cohorts at each location. This finds cohorts which should return home (by looking at their return tick) and does so.

Parameters:

  • tick (Tick) –

    The current simulation tick.

  • return_stats (bool) –

    True to collect movement statistics and provide them as the function's return value.

Returns:

  • NDArray[SimDType] | None –

    If return_stats is True, an (N,N,C)-shaped array containing the number of individuals moved during this return phase. Otherwise returns None.