atomica.programs.ProgramInstructions

class atomica.programs.ProgramInstructions(start_year, stop_year=None, alloc=None, coverage=None, capacity=None)[source]

Bases: object

Store instructions for applying programs

A ProgramSet contains a Python representation of the program book, with a collection of programs, their effects, and quantities like historical spending. However, to run a simulation with programs, additional information is required - for example, which year to switch from databook parameters to program-computed parameters. This type of information is specific to the simulation being run, rather than being an intrinsic property of a set of programs. Therefore, that information is stored in a ProgramInstructions instance.

At minimum, the ProgramInstructions must contain the year to turn on programs. It can also optionally contain the year to turn off programs. In addition to the start/stop years, the ProgramInstructions also contains any overwrites that should be applied to

  • Spending (in units of people/year)

  • Capacity (in units of people/year)

  • Fraction/proportion coverage

    • For continuous programs, specified as a dimensionless fraction

    • For one-off programs, specified as a ‘fraction/year’ coverage

which thus provides the underlying implementation for program-related scenarios. The ProgramSet and Program methods access and use the ProgramInstructions instances. The overwrites for spending in particular are widely used - for example, budget optimization is a mapping from one set of ProgramInstructions to another, and thus during optimization, ProgramInstructions instances are used to test different allocations.

Note that the program calculation proceeds by

  1. Using spending and unit cost to compute capacity

  2. Using capacity and the compartment sizes to compute fractional coverage

  3. Using fractional coverage to compute program outcomes

Overwrites to each quantity (spending, capacity, coverage) are applied at their respective stages, so if the ProgramInstructions contains more than one type of overwrite, they will be applied in this same order (and later stages will take precedence e.g. if both capacity and coverage are overwritten, it will be the coverage overwrite that impacts the final parameter value).

Finally, for simplicity, if an overwrite is provided, it entirely replaces the values in the program book, in contrast to parameter scenarios, which contain more complex logic for interpolating between databook and scenario values.

Parameters:

  • start_year (float) – Year to switch to program-calculated parameters

  • stop_year (float) – Year to switch back to databook parameters

  • alloc –

    The allocation. It can be - A dict keyed by program name, containing a scalar spend, or a TimeSeries of spending values. If the spend is

    scalar, it will be assigned to the start year

    • A ProgramSet instance, in which case an allocation will be assigned by interpolating the ProgramSet’s spending onto the program start year. This is a shortcut to ensure that budget scenarios and optimizations where spending is specified in future years ramp correctly from the program start year (and not the last year that data was entered for)

  • capacity (dict) – Overwrites to capacity. This is a dict keyed by program name, containing a scalar capacity or a TimeSeries of capacity values For convenience, the capacity overwrite should be in units of ‘people/year’ and it will be automatically converted to a per-timestep value based on the units for the program’s unit cost.

  • coverage (dict) – Overwrites to proportion coverage. This is a dict keyed by program name, containing a scalar coverage or a TimeSeries of coverage values. The overwrite is specified in dimensionless units for continuous programs, and ‘/year’ units for one-off programs.

Methods

scale_alloc

Scale allocation by a constant
scale_alloc(scale_factor)[source]

Scale allocation by a constant

This method multiplies the budget by a constant to scale the total budget up or down. The scale factor is applied at all time points.

Parameters:

scale_factor (float) – Multiplicative factor for spending

Return type:

None

Returns:

A new, scaled copy of the instructions