atomica.optimization.Constraint

class atomica.optimization.Constraint

Bases: object

Store conditions to satisfy during optimization

A Constraint represents a condition that must be satisfied by the Instructions after the cumulative effect of all adjustments. The Instructions are rescaled to satisfy the constraint directly (rather than changing the value of the Adjustables) although this distinction really only matters in the context of parametric spending.

Methods

constrain_instructions	Apply constraint to instructions
get_hard_constraint	Return hard constraint from initial instructions

constrain_instructions(instructions, hard_constraints, optimization)

Apply constraint to instructions

Constrains the instructions, returns a metric penalizing the constraint If there is no penalty associated with adjusting (perhaps if all of the Adjustments are parametric?) then this would be 0.0. The penalty represents in some sense the quality of the constraint. For example, the default TotalSpendConstraint rescales spending such that the total spend matches a target value. The penalty reflects the distance between the requested spend and the constrained spend, so it is desirable to minimize it.

If it is not possible to constrain the instructions, raise FailedConstraint.

Parameters:

• instructions (ProgramInstructions) – The ProgramInstructions instance to constrain (in place)

• hard_constraints – The hard constraint returned by get_hard_constraint

• optimization – The parent optimization, in case it is needed

Return type:

float

Returns:

A numeric penalty value. Return np.inf if constraint penalty could not be computed

Raises:

FailedConstraint if the instructions could not be constrained

get_hard_constraint(optimization, instructions)

Return hard constraint from initial instructions

Often constraints can be specified relative to the initial conditions. For example, fixing total spend regardless of what the total spend is in the initial instructions. Therefore, during constrain_instructions, it is necessary to examine properties from the initial instructions in order to perform the constraining.

This method is called at the very start of optimization, passing in the initial instructions. It then returns an arbitrary value that is passed back to the instance’s constrain_instructions during optimization. For example, consider the total spending constraint

• get_hard_constraint would extract the total spend from the initial instructions

• This value is passed to constrain_instructions where it is used to rescale spending

Because subclasses implement both get_hard_constraint and constrain_instructions no assumptions need to be made about the value returned by this method - it simply needs to be paired to constrain_instructions.

Parameters:

• optimization – An Optimization

• instructions (ProgramInstructions) – A set of initial instructions to extract absolute constraints from

Returns:

Arbitrary variable that will be passed back during constrain_instructions