Configurable parameters

The tuning module can convert any parameter of any Python function into a configurable one.

To achieve that, the user just has to:

  • Add the decorator @ac to the function containing the parameter

  • Annotate the configurable parameters with a custom type hint that specifies the parameter type, domain and default value.

Consider the following Python function:

>>> def func1(data, p1 = True, p2 = 0.0, p3 = 0, p4 = "A"):
>>>    ...

This function receives data which will not be a configurable parameter and p1, p2, p3 and p4 that we want to turn into configurable parameters.

The only changes that the user has to apply are the following:

>>> from optilog.tuning import ac, Bool, Int, Real, Categorical
>>>
>>> @ac
>>> def func1(
>>>     data,
>>>     p1: Bool() = True, p2: Real(-1.3, 2) = 0,
>>>     p3: Int(-5, 5) = 0, p4: Categorical("A", "B", "C") = "A"):
>>>     ...
  • The function must be decorated with the @ac decorator

  • All the configurable parameters must be annotated using autocgf custom type hints

Notice that this annotated function can be used in the same contexts where the original function was used.

The list of available tuning parameter types is the following:

class optilog.tuning.Bool(default=None)

Annotates a boolean parameter.

Parameters

default (Optional[bool]) – Default value of the parameter. Defaults to None. Note: May be specified in the definition of the function.

>>> from optilog.tuning import ac, Bool
>>> @ac
>>> def func(data, seed, p: Bool() = True):
>>>     ...
class optilog.tuning.Int(start, end, default=None)

Annotates an integer parameter.

Parameters
  • start (int) – Start of parameter range (inclusive)

  • end (int) – End of parameter range (inclusive)

  • default (Optional[int]) – Default value of the parameter. Note: May be specified in the definition of the function.

>>> from optilog.tuning import ac, Int
>>> @ac
>>> def func(data, seed, p: Int(-10, 10) = 0):
>>>     ...
class optilog.tuning.Real(start, end, default=None)

Annotates a real parameter.

Parameters
  • start (float) – Start of parameter range (inclusive)

  • end (float) – End of parameter range (inclusive)

  • default (Optional[float]) – Default value of the parameter. Note: May be specified in the definition of the function.

>>> from optilog.tuning import ac, Real
>>> @ac
>>> def func(data, seed, p: Real(-1.3, 3.14) = 0.18):
>>>     ...
class optilog.tuning.Categorical(*args, default=None)

Annotates a categorical parameter.

Parameters
  • args (List[str]) – List of possible categorical values

  • default (Optional[str]) – Default value of the parameter. Note: May be specified in the definition of the function.

>>> from optilog.tuning import ac, Categorical
>>> @ac
>>> def func(data, seed, p: Categorical("A", "B", "C") = "A"):
>>>     ...
class optilog.tuning.Choice(*args, default=None)

Annotates a disjunctive parameter (enum-union like, or also known as algebraic data types)

Parameters
  • args (List[Parameter]) – Parameters to configure.

  • default (Optional[Parameter]) – Default value of the parameter. Defaults to None. Note: May be specified in the definition of the function.

>>> from optilog.tuning import ac, Int, Real, Choice
>>>
>>> @ac
>>> def func(
>>>     data, seed,
>>>     n: Choice(Int(-7, 8, default=3), Real(0.1, 4.8, default=1.0)) = Int(-7, 8, default=3),
>>> ):
>>>     ...
class optilog.tuning.Dict(dt)

Annotates a set of parameters all at once

Parameters

dt (Dict[str, Parameter]) – Dictionary of pairs (string, parameter) to configure.

>>> @ac
>>> def func(data, seed,
>>>          d: Dict({'height': Int(3,10, default=7), 'width': Int(1, 8, default=6)})):
>>>     ...
class optilog.tuning.CfgCall(fn)

Configures a local configurable function. See the documentation for Local Configurable Functions

Parameters

fn (Callable) – Function to configure

>>> from optilog.tuning import ac, CfgCall
>>> @ac
>>> def func2(
>>>     data, seed,
>>>     func1_call1: CfgCall(func1),
>>>     func1_call2: CfgCall(func1),
>>> ):
class optilog.tuning.CfgCls(cls)

Annotates a configurable class

Parameters

cls (Type) – Configurable class

>>> from optilog.solvers.sat import Glucose41
>>> @ac
>>> def func(
>>>     instance,
>>>     seed,
>>>     init_solver_fn: CfgCls(Glucose41),
>>> ):
>>>     solver = init_solver_fn(seed=...)
>>>     ...
class optilog.tuning.CfgObj(cls)

Annotates a configurable class and instanties it

Parameters

cls (Type) – Configurable class

>>> from optilog.solvers.sat import Glucose41
>>> @ac
>>> def func(
>>>     instance,
>>>     seed,
>>>     solver: CfgObj(Glucose41),
>>> ):
>>>     ...