Skip to content

epymorph.movement_model

The basis of the movement system in epymorph.

Movement models are responsible for dividing up the day into one or more parts, in accordance with their desired tempo of movement. For example, commuting patterns of work day versus night.

Movement mechanics are expressed as a set of clauses which calculate the "requested" number of individuals that should move between geospatial nodes at a particular time step of the simulation. This is "requested" movement because fewer individuals may wind up moving if there are not enough to satisfy the request.

DayOfWeek module-attribute 

DayOfWeek = Literal['M', 'T', 'W', 'Th', 'F', 'Sa', 'Su']

Type for days of the week values.

ALL_DAYS module-attribute 

ALL_DAYS: tuple[DayOfWeek, ...] = (
    "M",
    "T",
    "W",
    "Th",
    "F",
    "Sa",
    "Su",
)

All days of the week values.

MovementPredicate

Bases: ABC

Checks the current tick and responds with true or false. Movement predicates are used to determine whether a movement clause should be applied for this simulation tick or not.

evaluate abstractmethod 

evaluate(tick: Tick) -> bool

Check the given tick.

Parameters:

  • tick (Tick) –

    The current simulation tick.

Returns:

  • bool –

    The result of the predicate.

EveryDay

Bases: MovementPredicate

Return true for every day.

evaluate 

evaluate(tick: Tick) -> bool

Check the given tick.

Parameters:

  • tick (Tick) –

    The current simulation tick.

Returns:

  • bool –

    The result of the predicate.

DayIs 

DayIs(week_days: Sequence[DayOfWeek] | str)

Bases: MovementPredicate

Checks that the day is in the given set of days of the week.

Parameters:

  • week_days (Sequence[DayOfWeek] | str) –

    The week days for which this predicate should evaluate true. Either a list of DayOfWeek or a string which will be parsed as in parse_days_of_week.

week_days instance-attribute 

week_days: tuple[DayOfWeek, ...]

evaluate 

evaluate(tick: Tick) -> bool

Check the given tick.

Parameters:

  • tick (Tick) –

    The current simulation tick.

Returns:

  • bool –

    The result of the predicate.

MovementClauseClass

Bases: SimulationFunctionClass

The metaclass for MovementClause classes; enforces proper implementation.

MovementClause

Bases: SimulationTickFunction[NDArray[SimDType]], ABC

A movement clause is basically a function which calculates how many individuals should move between all of the geo nodes.

It's up to epymorph's internal mechanisms to decide by random draw which individuals move (as identified by their disease status, or IPM compartment).

The clause also has various settings which determine when the clause is active (for example, only move people Monday-Friday at the start of the day) and when the individuals that were moved by the clause should return home (for example, stay for two days and then return at the end of the day).

predicate instance-attribute 

predicate: MovementPredicate

When does this movement clause apply?

leaves instance-attribute 

leaves: TickIndex

On which tau step does this movement clause apply?

returns instance-attribute 

returns: TickDelta

When do the movers from this clause return home?

clause_name property 

clause_name: str

A display name to use for the clause.

is_active 

is_active(tick: Tick) -> bool

Should this movement clause be applied this tick?

Parameters:

  • tick (Tick) –

    The current simulation tick.

Returns:

  • bool –

    True if the clause should be applied this tick.

evaluate abstractmethod 

evaluate(tick: Tick) -> NDArray[SimDType]

Implement this method to provide logic for the clause. Use self methods and properties to access the simulation context or defer processing to another function.

Parameters:

  • tick (Tick) –

    The simulation tick being evaluated.

Returns:

  • NDArray[SimDType] –

    An array describing the requested number of individuals to move from origin location (row; axis 0) to destination location (column; axis 1).

MovementModelClass

Bases: ABCMeta

The metaclass for MovementModel classes; enforces proper implementation.

MovementModel

Bases: ABC

A MovementModel (MM) describes a pattern of geospatial movement for individuals in the model.

The MM defines the tau steps which chop the day up into one or more parts, as well as the set of movement clauses which may apply throughout each day.

To create a custom MM, you will write an implementation of this class and of any required clause classes.

steps instance-attribute 

steps: Sequence[float]

The length and order of tau steps.

clauses instance-attribute 

clauses: Sequence[MovementClause]

The movement clauses that make up the model.

requirements property 

requirements: Sequence[AttributeDef]

The combined requirements of all of the clauses in this model.

parse_days_of_week 

parse_days_of_week(dow: str) -> tuple[DayOfWeek, ...]

Parses a list of days of the week using our standard abbreviations: M, T, W, Th, F, Sa, Su.

Parameters:

  • dow (str) –

    A string containing a list of days of the week. The parser is pretty permissive; it ignores invalid parts of the input while keeping the valid parts. Any separator is allowed between the day of the week themselves.

Returns:

  • tuple[DayOfWeek, ...] –

    The days of the week parsed from the string. Empty if there are none.

Examples:

1
2
>>> parse_days_of_week("M,W,F")
('M', 'W', 'F')