atomica.optimization.TotalSpendConstraint

class atomica.optimization.TotalSpendConstraint(total_spend=None, t=None, budget_factor=1.0)

Bases: Constraint

Fix total spending

This class implements a constraint on the total spend at every time point when a program is optimizable. A program is considered optimizable if an Adjustment reaches that program at the specified time. Spending is constrained independently at all times when any program is adjustable.

The initial_total_spend argument allows the total spending in a particular year to be explicitly specified rather than drawn from the initial allocation. This can be useful when using parametric programs where the adjustables do not directly correspond to spending value. If the total spend is not provided, it will automatically be computed from the first ASD step. Note that it is computed based on the initial instructions after the initial ASD values have been applied. This is because relative constraints on all adjustables are interpreted relative to the initial value of the adjustable, since not all adjustables map directly to values in the instructions. Since the adjustable hard upper and lower bounds are used as part of the constraint, for consistency, the total spend constraint itself is drawn from the same set of instructions (i.e. after the initial value has been applied). In cases where this is not the desired behaviour, the cause would likely be that the default value does not agree with a known desired total spend value. In that case, the desired total spend should simply be specified here explicitly as an absolute value.

This constraint can also be set to only apply in certain years.

The budget_factor multiplies the total spend at the time the hard_constraint is assigned Typically this is to scale up the available spending when that spending is being drawn from the instructions/progset (otherwise the budget_factor could already be part of the specified total spend)

Note that if no times are specified, the budget factor should be a scalar but no explicit spending values can be specified. This is because in the case where different programs are optimized in different years, an explicit total spending constraint applying to all times is unlikely to be a sensible choice (so we just ask the user to specify the time as well).

Parameters:

• total_spend – A list of spending amounts the same size as t (can contain Nones), or None. For times in which the total spend is None, it will be automatically set to the sum of spending on optimizable programs in the corresponding year

• t – A time, or list of times, at which to apply the total spending constraint. If None, it will automatically be set to all years in which spending adjustments are being made

• budget_factor – The budget factor multiplies whatever the initial_total_spend is. This can either be a single value, or a year specific value

Methods

constrain_instructions	Apply total spend constraint
get_hard_constraint	Return hard constraint dictionary

constrain_instructions(instructions, hard_constraints, optimization)

Apply total spend constraint

Parameters:

• instructions (ProgramInstructions) – The ProgramInstructions instance to constrain

• hard_constraints (dict) – Dictionary of hard constraints

• optimization – The parent optimization, in case it’s needed

Return type:

float

Returns:

Distance-like difference between initial spending and constrained spending, np.inf if constraint failed

get_hard_constraint(optimization, instructions)

Return hard constraint dictionary

Parameters:

• optimization – Optimization instance

• instructions (ProgramInstructions) – Initial ProgramInstructions

Return type:

dict

Returns: