Domain constraints

All functionality related to domain constraints on objective function.

Main features in this module:

• constrained()
• wrap_constraints()

Module author: Marc Claesen

exception optunity.constraints.ConstraintViolation(constraint, *args, **kwargs)

Bases: exceptions.Exception

Thrown when constraints are not met.

args

constraint

kwargs

message

optunity.constraints.constr_lb_c(field, bounds, *args, **kwargs)

Models args.field >= bounds.

optunity.constraints.constr_lb_o(field, bounds, *args, **kwargs)

Models args.field > bounds.

optunity.constraints.constr_range_cc(field, bounds, *args, **kwargs)

Models args.field in [bounds[0], bounds[1]].

optunity.constraints.constr_range_co(field, bounds, **kwargs)

Models args.field in [bounds[0], bounds[1]).

optunity.constraints.constr_range_oc(field, bounds, *args, **kwargs)

Models args.field in (bounds[0], bounds[1]].

optunity.constraints.constr_range_oo(field, bounds, *args, **kwargs)

Models args.field in (bounds[0], bounds[1]).

optunity.constraints.constr_ub_c(field, bounds, *args, **kwargs)

Models args.field <= bounds.

optunity.constraints.constr_ub_o(field, bounds, *args, **kwargs)

Models args.field < bounds.

optunity.constraints.constrained(constraints)

Decorator that puts constraints on the domain of f.

>>> @constrained([lambda x: x > 0])
... def f(x): return x+1
>>> f(1)
2
>>> f(0) 
Traceback (most recent call last):
...
ConstraintViolation
>>> len(f.constraints)
1
Traceback (most recent call last):
...
ConstraintViolation

optunity.constraints.violations_defaulted(default)

Decorator to default function value when a ConstraintViolation occurs.

>>> @violations_defaulted("foobar")
... @constrained([lambda x: x > 0])
... def f(x): return x+1
>>> f(1)
2
>>> f(0)
'foobar'

optunity.constraints.wrap_constraints(f, default=None, ub_o=None, ub_c=None, lb_o=None, lb_c=None, range_oo=None, range_co=None, range_oc=None, range_cc=None, custom=None)

Decorates f with given input domain constraints.

Parameters:

• f (callable) – the function that will be constrained
• default (number) – function value to default to in case of constraint violations
• ub_o (dict) – open upper bound constraints, e.g. \(x < c\)
• ub_c (dict) – closed upper bound constraints, e.g. \(x \leq c\)
• lb_o (dict) – open lower bound constraints, e.g. \(x > c\)
• lb_c (dict) – closed lower bound constraints, e.g. \(x \geq c\)
• range_oo (dict with 2-element lists as values ([lb, ub])) – range constraints (open lb and open ub) \(lb < x < ub\)
• range_co (dict with 2-element lists as values ([lb, ub])) – range constraints (closed lb and open ub) \(lb \leq x < ub\)
• range_oc (dict with 2-element lists as values ([lb, ub])) – range constraints (open lb and closed ub) \(lb < x \leq ub\)
• range_cc (dict with 2-element lists as values ([lb, ub])) – range constraints (closed lb and closed ub) \(lb \leq x \leq ub\)
• custom (list of constraints) – custom, user-defined constraints

*custom constraints are binary functions that yield False in case of violations.

>>> def f(x):
...     return x
>>> fc = wrap_constraints(f, default=-1, range_oc={'x': [0, 1]})
>>> fc(x=0.5)
0.5
>>> fc(x=1)
1
>>> fc(x=5)
-1
>>> fc(x=0)
-1

We can define any custom constraint that we want. For instance, assume we have a binary function with arguments x and y, and we want to make sure that the provided values remain within the unit circle.

>>> def f(x, y):
...     return x + y
>>> circle_constraint = lambda x, y: (x ** 2 + y ** 2) <= 1
>>> fc = wrap_constraints(f, default=1234, custom=[circle_constraint])
>>> fc(0.0, 0.0)
0.0
>>> fc(1.0, 0.0)
1.0
>>> fc(0.5, 0.5)
1.0
>>> fc(1, 0.5)
1234