- class atomica.programs.ProgramInstructions(start_year, stop_year=None, alloc=None, coverage=None, capacity=None)¶
Store instructions for applying programs
ProgramSetcontains 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
At minimum, the
ProgramInstructionsmust 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
ProgramInstructionsalso 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
Programmethods access and use the
ProgramInstructionsinstances. The overwrites for spending in particular are widely used - for example, budget optimization is a mapping from one set of
ProgramInstructionsto another, and thus during optimization,
ProgramInstructionsinstances are used to test different allocations.
Note that the program calculation proceeds by
Using spending and unit cost to compute capacity
Using capacity and the compartment sizes to compute fractional coverage
Using fractional coverage to compute program outcomes
Overwrites to each quantity (spending, capacity, coverage) are applied at their respective stages, so if the
ProgramInstructionscontains 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.
float) – Year to switch to program-calculated parameters
float) – Year to switch back to databook parameters
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)
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.
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.
Scale allocation by a constant
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.