Skip to content

epymorph.params

Users may wish to express simulation parameters as functions of simulation dimensions and/or of other simulation attributes. These classes provide a way to do that. This module also defines the types of acceptable input values for simulation parameters.

ResultDType module-attribute 

ResultDType = TypeVar('ResultDType', bound=generic)

The result type of a ParamFunction.

ParamSymbol module-attribute 

ParamSymbol = Literal[
    "day", "node_index", "duration_days", "nodes"
]

The names of common symbols used in epymorph simulation expressions. For example, building a ParamExpressionTimeAndNode may make use of these symbols.

See Also

epymorph.rume.RUME.symbols and epymorph.params.simulation_symbols which are methods for using these names to obtain symbol references.

ParamFunction

Bases: SimulationFunction[NDArray[ResultDType]], ABC

Base class for parameter functions.

ParamFunctions are generic on the dtype of the numpy array that they produce (ResultDType).

ParamFunctionNumpy

Bases: ParamFunction[ResultDType]

Base class for param functions whose evaluate method produces the whole data series as a numpy array.

evaluate abstractmethod 

evaluate() -> NDArray[ResultDType]

Produce a numpy array containing all of this parameter's values. This method must assure the values are the appropriate shape and data type.

Returns:

ParamFunction1

Bases: ParamFunction[ResultDType], ABC

Base class for parameter functions which calculate results one at a time.

dtype class-attribute instance-attribute 

dtype: type[ResultDType] | None = None

The result type of this function. If specified, results will be coerced accordingly.

ParamFunctionScalar

Bases: ParamFunction1[ResultDType]

Base class for param functions whose evaluate method produces a scalar value (which is the full data series).

Implement by overriding evaluate1.

evaluate 

evaluate() -> NDArray[ResultDType]

Fully evaluate the parameter function in the current simulation context.

Returns:

evaluate1 abstractmethod 

evaluate1() -> AttributeValue

Produce a scalar value for this parameter in the given simulation context.

Returns:

ParamFunctionTime

Bases: ParamFunction1[ResultDType]

Base class for param functions whose evaluate method produces a time-series of data, one value at a time.

Implement by overriding evaluate1.

evaluate 

evaluate() -> NDArray[ResultDType]

Fully evaluate the parameter function in the current simulation context.

Returns:

evaluate1 abstractmethod 

evaluate1(day: int) -> AttributeValue

Produce the daily value for this parameter.

Parameters:

  • day (int) –

    The simulation day (0-indexed from the start of the simulation).

Returns:

ParamFunctionNode

Bases: ParamFunction1[ResultDType]

Base class for param functions whose evaluate method produces a node-series of data, one value at a time.

Implement by overriding evaluate1.

evaluate 

evaluate() -> NDArray[ResultDType]

Fully evaluate the parameter function in the current simulation context.

Returns:

evaluate1 abstractmethod 

evaluate1(node_index: int) -> AttributeValue

Produce the per-node value for this parameter.

Parameters:

  • node_index (int) –

    The node index for which to compute the value.

Returns:

ParamFunctionNodeAndNode

Bases: ParamFunction1[ResultDType]

Base class for param functions whose evaluate method produces a node-by-node matrix of data, one value at a time.

Often, this kind of data is posed as having an originating node and a destination node, for example: data describing the normal number of commuters between locations. For some data this relationship may be more figurative than literal.

Implement by overriding evaluate1.

evaluate 

evaluate() -> NDArray[ResultDType]

Fully evaluate the parameter function in the current simulation context.

Returns:

evaluate1 abstractmethod 

evaluate1(node_from: int, node_to: int) -> AttributeValue

Produce the per-node-pair value for this parameter.

Parameters:

  • node_from (int) –

    The origin node.

  • node_to (int) –

    The destination node.

Returns:

ParamFunctionNodeAndCompartment

Bases: ParamFunction1[ResultDType]

Base class for param functions whose evaluate method produces a node-by-disease-compartment matrix of data, one value at a time.

Implement by overriding 'evaluate1`.

evaluate 

evaluate() -> NDArray[ResultDType]

Fully evaluate the parameter function in the current simulation context.

Returns:

evaluate1 abstractmethod 

evaluate1(
    node_index: int, compartment_index: int
) -> AttributeValue

Produce the per-node and per-disease-compartment value for this parameter.

Parameters:

  • node_index (int) –

    The node index for which to compute the value.

  • compartment_index (int) –

    The disease compartment index for which to compute the value. This is taken from the IPM compartment definition order, indexed from 0.

Returns:

ParamFunctionTimeAndNode

Bases: ParamFunction1[ResultDType]

Base class for param functions whose evaluate method produces a time-by-node matrix of data, one value at a time.

Implement by overriding evaluate1.

evaluate 

evaluate() -> NDArray[ResultDType]

Fully evaluate the parameter function in the current simulation context.

Returns:

evaluate1 abstractmethod 

evaluate1(day: int, node_index: int) -> AttributeValue

Produce the per-day and per-node value for this parameter.

Parameters:

  • day (int) –

    The simulation day (0-indexed from the start of the simulation).

  • node_index (int) –

    The node index for which to compute the value.

Returns:

ParamExpressionTimeAndNode 

ParamExpressionTimeAndNode(expression: Expr)

Bases: ParamFunction[float64]

A param function based on a sympy expression for a time-by-node matrix of data.

Parameters:

  • expression (Expr) –

    The sympy expression to use.

See Also

epymorph.params.simulation_symbols which enables you to obtain symbols standing for simulation properties like "day" and "node_index"; you will likely make use of the symbols in writing the expression.

requirements class-attribute instance-attribute 

requirements = ()

Param expressions do not support data requirements, so this list must be empty.

evaluate 

evaluate() -> NDArray[float64]

Fully evaluate the parameter function in the current simulation context.

Returns:

simulation_symbols 

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

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

Parameters:

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

    The names of symbols to retrieve, as var-args.

Returns:

  • tuple[Symbol, ...] –

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