Skip to content

epymorph.rume

A RUME (Runnable Modeling Experiment) is a package containing the critical components of an epymorph experiment. Particular simulation tasks may require more information, but will certainly not require less. A GPM (Geo-Population Model) is a subset of this configuration, and it is possible to combine multiple GPMs into one multi-strata RUME.

GEO_LABELS module-attribute 

GEO_LABELS = KeyValue(
    AbsoluteName(META_STRATA, "geo", "label"),
    AttributeDef(
        "label",
        str,
        N,
        comment="Labels to use for each geo node.",
    ),
)

A special attribute which, if provided to a RUME ("meta::geo::label"), will be used as labels for the geo node. Otherwise labels will be taken from the geo scope.

GeoScopeT module-attribute 

GeoScopeT = TypeVar('GeoScopeT', bound=GeoScope)

A type of GeoScope.

GeoScopeT_co module-attribute 

GeoScopeT_co = TypeVar(
    "GeoScopeT_co", covariant=True, bound=GeoScope
)

A type of GeoScope, covariant.

GPM dataclass 

GPM(
    name: str,
    ipm: CompartmentModel,
    mm: MovementModel,
    init: Initializer,
    params: Mapping[ModuleNamePattern, ParamValue]
    | None = None,
)

A GPM (short for Geo-Population Model) combines an IPM, MM, and initialization scheme. Most often, a GPM is used to define one strata in a multi-strata RUME.

Parameters:

  • name (str) –

    The name to use to identify the GPM.

  • ipm (CompartmentModel) –

    The IPM for the GPM.

  • mm (MovementModel) –

    The MM for the GPM.

  • init (Initializer) –

    The initializer for the GPM.

  • params (Mapping[ModuleNamePattern, ParamValue] | None, default: None ) –

    Parameter values specific to this GPM. When a GPM is used in a RUME, RUME parameters will override GPM parameters if there's overlap.

See Also

epymorph.rume.MultiStrataRUME.build which uses GPMs.

name instance-attribute 

name: str

The name to use to identify the GPM.

ipm instance-attribute 

ipm: CompartmentModel

The IPM for the GPM.

mm instance-attribute 

mm: MovementModel

The MM for the GPM.

init instance-attribute 

init: Initializer

The initializer for the GPM.

params class-attribute instance-attribute 

params: Mapping[ModuleNamePattern, ParamValue] | None = (
    field(default=None)
)

Parameter values specific to this GPM. When a GPM is used in a RUME, RUME parameters will override GPM parameters if there's overlap.

CombineTauStepsResult

Bases: NamedTuple

The result of the combine_tau_steps function.

new_tau_steps instance-attribute 

new_tau_steps: tuple[float, ...]

The lengths of the output tau steps.

start_mapping instance-attribute 

start_mapping: dict[str, dict[int, int]]

A per-strata mapping for the start of tau step bounds; from original tau step index to new tau step index.

stop_mapping instance-attribute 

stop_mapping: dict[str, dict[int, int]]

A per-strata mapping for the end of tau step bounds; from original tau step index to new tau step index.

RUME dataclass 

RUME(
    strata: Sequence[GPM],
    ipm: BaseCompartmentModel,
    mms: OrderedDict[str, MovementModel],
    scope: GeoScopeT_co,
    time_frame: TimeFrame,
    params: Mapping[NamePattern, ParamValue],
)

Bases: ABC, Generic[GeoScopeT_co]

A RUME (or Runnable Modeling Experiment) contains the configuration of an epymorph-style simulation. It brings together one or more IPMs, MMs, initialization routines, and a geo-temporal scope. Model parameters can also be specified.

RUMEs are often used to construct a simulation -- in the most basic case, running a forward simulation and producing time-series results of disease progression.

RUME is generic on the type of GeoScope used to construct it (GeoScopeT_co).

See Also

RUME is an abstract parent class; users will typically use epymorph.rume.SingleStrataRUME.build and epymorph.rume.MultiStrataRUMEBuilder to construct concrete RUMEs.

strata instance-attribute 

strata: Sequence[GPM]

The strata for the RUME expressed as GPMs.

ipm instance-attribute 

ipm: BaseCompartmentModel

The effective IPM for the RUME, made by combining all strata IPMs.

mms instance-attribute 

mms: OrderedDict[str, MovementModel]

The effective MMs for the RUME by strata, made by combining all strata MMs.

scope instance-attribute 

scope: GeoScopeT_co

The geo scope. This is shared by all strata.

time_frame instance-attribute 

time_frame: TimeFrame

The simulation time frame.

params instance-attribute 

params: Mapping[NamePattern, ParamValue]

Parameter values for the RUME.

tau_step_lengths class-attribute instance-attribute 

tau_step_lengths: list[float] = field(init=False)

The lengths of each tau step in the simulation as fractions of a day.

num_tau_steps class-attribute instance-attribute 

num_tau_steps: int = field(init=False)

The number of tau steps per day in the simulation.

num_ticks class-attribute instance-attribute 

num_ticks: int = field(init=False)

The number of total simulation ticks, the product of multiplying the number of simulation days from the time frame by the number of tau steps per day.

requirements cached property 

requirements: Mapping[AbsoluteName, AttributeDef]

The attributes required by the RUME.

compartment_mask cached property 

compartment_mask: Mapping[str, NDArray[bool_]]

Masks that describe which compartments belong in the given strata. For example: if the model has three strata ('a', 'b', and 'c') with three compartments each, strata_compartment_mask('b') returns [F F F T T T F F F].

compartment_mobility cached property 

compartment_mobility: Mapping[str, NDArray[bool_]]

Masks that describe which compartments should be considered subject to movement in a particular strata.

Currently a compartment is exempted from movement calculations if it is tagged "immobile".

name_display_formatter abstractmethod 

name_display_formatter() -> Callable[
    [AbsoluteName | NamePattern], str
]

Returns a function for formatting attribute/parameter names.

params_description 

params_description() -> str

Provide a description of all attributes required by the RUME.

generate_params_dict 

generate_params_dict() -> str

Generate a skeleton dictionary you can use to provide parameter values to the RUME.

symbols staticmethod 

symbols(*symbols: ParamSymbol) -> tuple[Symbol, ...]

Convenient function to retrieve the sympy symbols used to represent simulation quantities.

Parameters:

  • *symbols (ParamSymbol, default: () ) –

    The symbols to retrieve, as var-args.

Returns:

  • tuple[Symbol, ...] –

    A tuple containing the symbols requested, in the order requested.

estimate_data 

estimate_data(*, max_bandwidth: int = 1000 ** 2) -> None

Prints a report estimating the data requirements of this RUME.

Includes data which must be downloaded and how much will be added to the file cache. Provides a projected download time based on the given assumed maximum network bandwidth.

Parameters:

  • max_bandwidth (int, default: 1000 ** 2 ) –

    The assumed maximum network download speed in bytes per second. Default is 1 MB/s.

requirements_tree 

requirements_tree(
    override_params: CovariantMapping[
        str | NamePattern, ParamValue
    ]
    | None = None,
) -> ReqTree

Compute the requirements tree for the given RUME.

Parameters:

  • override_params (CovariantMapping[str | NamePattern, ParamValue] | None, default: None ) –

    When computing requirements, use these values to override any that are provided by the RUME itself. If keys are provided as strings, they must be able to be parsed as NamePatterns.

Returns:

  • ReqTree –

    The requirements tree.

Raises:

  • DataAttributeError –

    If the tree cannot be evaluated, for instance, due to containing circular dependencies.

evaluate_params 

evaluate_params(
    rng: Generator,
    override_params: CovariantMapping[
        str | NamePattern, ParamValue
    ]
    | None = None,
) -> DataResolver

Evaluates the parameters of this RUME.

Parameters:

  • rng (Generator) –

    The random number generator to use during evaluation

  • override_params (CovariantMapping[str | NamePattern, ParamValue] | None, default: None ) –

    Use these values to override any that are provided by the RUME itself. If keys are provided as strings, they must be able to be parsed as NamePatterns.

Returns:

  • DataResolver –

    The resolver containing the evaluated values.

Raises:

  • DataAttributeError –

    If the parameters cannot be evaluated for any reason, such as missing or invalid parameter values.

initialize 

initialize(data: DataResolver, rng: Generator) -> SimArray

Evaluates the Initializer(s) for this RUME.

Parameters:

  • data (DataResolver) –

    The resolved parameters for this RUME.

  • rng (Generator) –

    The random number generator to use. Generally this should be the same RNG used to evaluate parameters.

Returns:

  • SimArray –

    the initial values ((N,C)-shaped array) for all geo scope nodes and IPM compartments

Raises:

  • InitError –

    If initialization fails for any reason or produces invalid values.

SingleStrataRUME dataclass 

SingleStrataRUME(
    strata: Sequence[GPM],
    ipm: CompartmentModel,
    mms: OrderedDict[str, MovementModel],
    scope: GeoScopeT_co,
    time_frame: TimeFrame,
    params: Mapping[NamePattern, ParamValue],
)

Bases: RUME[GeoScopeT_co]

A RUME with a single strata. We recommend using the more-convenient static method SingleStrataRUME.build instead of the normal class constructor.

SingleStrataRUME is generic on the type of GeoScope used to construct it (GeoScopeT_co).

ipm instance-attribute 

ipm: CompartmentModel

The effective IPM for the RUME, made by combining all strata IPMs.

build staticmethod 

build(
    ipm: CompartmentModel,
    mm: MovementModel,
    init: Initializer,
    scope: GeoScopeT,
    time_frame: TimeFrame,
    params: CovariantMapping[str | NamePattern, ParamValue],
) -> SingleStrataRUME[GeoScopeT]

Create a RUME with a single strata.

This method is generic on the type of GeoScope used (GeoScopeT).

Parameters:

Returns:

name_display_formatter 

name_display_formatter() -> Callable[
    [AbsoluteName | NamePattern], str
]

Returns a function for formatting attribute/parameter names.

MultiStrataRUME dataclass 

MultiStrataRUME(
    strata: Sequence[GPM],
    ipm: CombinedCompartmentModel,
    mms: OrderedDict[str, MovementModel],
    scope: GeoScopeT_co,
    time_frame: TimeFrame,
    params: Mapping[NamePattern, ParamValue],
)

Bases: RUME[GeoScopeT_co]

A RUME with multiple strata.

MultiStrataRUME is generic on the type of GeoScope used to construct it (GeoScopeT_co).

See Also

epymorph.rume.MultiStrataRUMEBuilder for a more user-friendly way to construct multistrata RUMEs.

ipm instance-attribute 

ipm: CombinedCompartmentModel

The effective IPM for the RUME, made by combining all strata IPMs.

build staticmethod 

build(
    strata: Sequence[GPM],
    meta_requirements: Sequence[AttributeDef],
    meta_edges: MetaEdgeBuilder,
    scope: GeoScopeT,
    time_frame: TimeFrame,
    params: CovariantMapping[str | NamePattern, ParamValue],
) -> MultiStrataRUME[GeoScopeT]

Create a multistrata RUME by combining one GPM per strata.

This function is not the recommended way to create multistrata RUMEs; see MultiStrataRUMEBuilder instead.

This method is generic on the type of GeoScope used (GeoScopeT).

Parameters:

  • strata (Sequence[GPM]) –

    Define the strata for this RUME by providing a GPM for each.

  • meta_requirements (Sequence[AttributeDef]) –

    Define any data requirements used for the meta-edges of the combined IPM.

  • meta_edges (MetaEdgeBuilder) –

    A function which constructs the meta-edges of the combined IPM.

  • scope (GeoScopeT) –

    The geo scope.

  • time_frame (TimeFrame) –

    The time frame to simulate.

  • params (CovariantMapping[str | NamePattern, ParamValue]) –

    Parameter values that will be used to fulfill the data requirements of the various modules of the RUME.

Returns:

name_display_formatter 

name_display_formatter() -> Callable[
    [AbsoluteName | NamePattern], str
]

Returns a function for formatting attribute/parameter names.

MultiStrataRUMEBuilder

Bases: ABC

The recommended way to define and create multistrata RUMEs. Implement this class and then call build to obtain an instance.

strata instance-attribute 

strata: Sequence[GPM]

The strata that are part of this RUME.

meta_requirements instance-attribute 

meta_requirements: Sequence[AttributeDef]

A set of additional requirements which are needed by the meta-edges in our combined compartment model.

meta_edges abstractmethod 

meta_edges(
    symbols: MultiStrataModelSymbols,
) -> Sequence[TransitionDef]

When implementing a MultiStrataRumeBuilder, override this method to define the meta-transition-edges -- the edges which represent cross-strata interactions.

Parameters:

  • symbols (MultiStrataModelSymbols) –

    The model's symbols library, to obtain compartment and parameter symbols needed to build transition rate expressions.

Returns:

build 

build(
    scope: GeoScopeT,
    time_frame: TimeFrame,
    params: CovariantMapping[str | NamePattern, ParamValue],
) -> MultiStrataRUME[GeoScopeT]

Complete the RUME definition and construct an instance.

This method is generic on the type of GeoScope used (GeoScopeT).

Parameters:

Returns:

combine_tau_steps 

combine_tau_steps(
    strata_tau_lengths: dict[str, Sequence[float]],
) -> CombineTauStepsResult

Combines multiple tau step schemes to calculate a unified scheme which is compatible with all of them while using the fewest possible number of tau steps.

Parameters:

  • strata_tau_lengths (dict[str, Sequence[float]]) –

    A mapping containing each strata name (key) and the list of tau lengths (value).

Returns:

  • CombineTauStepsResult –

    A tuple containing the information required to adjust movement models to the combined tau step scheme.

Examples:

For tau steps [1/3, 2/3] and tau steps [1/2, 1/2] -- the combined tau steps are [1/3, 1/6, 1/2].

remap_taus 

remap_taus(
    strata_mms: list[tuple[str, MovementModel]],
) -> OrderedDict[str, MovementModel]

Adjusts a set of movement models which may use different tau step schemes such that they all use a unified tau step scheme which is compatible with all of them.

This step is performed automatically when constructing a multi-strata RUME.

Parameters:

Returns: