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),
>>> ):
>>>     ...