Configuration scenario

The tuning module can generate the scenario files for several AC tools keeping the same code for the configurable functions defined by the user.

class optilog.tuning.configurators.GGAConfigurator(entrypoint, global_cfgcalls, constraints, run_obj, seed, cost_min, cost_max, eval_time_limit=None, data_kwarg=None, seed_kwarg=None, input_data=None, runsolver_path=None, quality_regex=None, **scenario_kwargs)

Handles the creation of all the needed files to use the GGA AC tool over a configurable function.

Parameters

entrypoint (Callable) – Entrypoint function to be configured.
global_cfgcalls (List[CfgCall]) – List of global configurable functions. In case entrypoint calls some configurable function it must be present in this list. Otherwise this list should only contain the entrypoint.
input_data (Optional[str]) – Input data that the AC tool will use to configure the entrypoint function. This parameter can be either a string or a list of inputs. If this parameter is a list of inputs, the type of its elements must be the same that the entrypoint function will receive on the data_kwarg parameter. The accepted types are int, str or float. If this parameter is a string, it will get expanded recursively with glob. See examples.
runsolver_path (Optional[str]) – Path to the runsolver binary, which is needed to enforce memory and times limits when configuring automatically. See the runsolver documentation for more information.
constraints (ExecutionConstraints) – Defines the execution constraints for the Configuration Process
run_obj (str) – Run objective (‘runtime’ or ‘quality’). NOTE: When run_onj='quality', the configurator will minimize the result reported by the entrypoint function.
data_kwarg (Optional[str]) – Name of the parameter inside the entrypoint function that the AC tool will use to provide the data specified in input_data. If None no data will be passed.
seed_kwarg (Optional[str]) – Name of the parameter inside the entrypoint function that the AC tool will use to provide the RNG seed. If None no seed will be passed.
quality_regex (Optional[str]) – Python regular expression used to capture the quality of an execution of the entrypoint function. The quality must be the first group within the regular expression. If run_obj='runtime' this parameter is not needed.
seed (int) – Seed used by GGA on every instance
cost_min (int) – Minimum possible cost of the algorithm
cost_max (int) – Maximum possible cost of the algorithm
eval_time_limit (Optional[int]) – Time limit for each evaluation in seconds (defaults to the wall time limit constraint)
**scenario_kwargs – GGA scenario parameters as they appear in GGA’s official documentation. These parameters will be directly written to the GGA scenario file. GGA documentation can be accessed through the official website of LOG.

generate_scenario(out_dir)

Generates all the files required by the Automatic Configurator.

Parameters: out_dir (str) – Output directory where files will be generated.

class optilog.tuning.configurators.SMACConfigurator(entrypoint, global_cfgcalls, constraints, run_obj, data_kwarg=None, seed_kwarg=None, input_data=None, runsolver_path=None, quality_regex=None, **scenario_kwargs)

Handles the creation of all the needed files to use the SMAC AC tool over a configurable function.

Parameters

entrypoint (Callable) – Entrypoint function to be configured.
global_cfgcalls (List[CfgCall]) – List of global configurable functions. In case entrypoint calls some configurable function it must be present in this list. Otherwise this list should only contain the entrypoint.
input_data (Optional[str]) – Input data that the AC tool will use to configure the entrypoint function. This parameter can be either a string or a list of inputs. If this parameter is a list of inputs, the type of its elements must be the same that the entrypoint function will receive on the data_kwarg parameter. The accepted types are int, str or float. If this parameter is a string, it will get expanded recursively with glob. See examples.
runsolver_path (Optional[str]) –
Path to the runsolver binary, which is needed to enforce memory and times limits when configuring automatically. See the runsolver documentation for more information.
constraints (ExecutionConstraints) – Defines the execution constraints for the Configuration Process
run_obj (str) – Run objective (‘runtime’ or ‘quality’). NOTE: When run_onj='quality', the configurator will minimize the result reported by the entrypoint function.
data_kwarg (Optional[str]) – Name of the parameter inside the entrypoint function that the AC tool will use to provide the data specified in input_data. If None no data will be passed.
seed_kwarg (Optional[str]) – Name of the parameter inside the entrypoint function that the AC tool will use to provide the RNG seed. If None no seed will be passed.
quality_regex (Optional[str]) – Python regular expression used to capture the quality of an execution of the entrypoint function. The quality must be the first group within the regular expression. If run_obj='runtime' this parameter is not needed.
**scenario_kwargs (dict) – SMAC scenario parameters as they appear in SMAC’s official documentation. Will be directly written to the SMAC scenario file.

generate_scenario(out_dir)

Generates all the files required by the Automatic Configurator.

Parameters: out_dir (str) – Output directory where files will be generated.

>>> from optilog.tuning.configurators import SMACConfigurator
>>>
>>> configurator = SMACConfigurator(
>>>     func2, global_cfgcalls=[func2],
>>>     runsolver_path='./runsolver',
>>>     input_data=['path1', 'path2', 'path3'],
>>>     run_obj='quality',
>>>     data_kwarg="data",
>>>     seed_kwarg="seed",
>>>     quality_regex=r"^Result: (\d+)$",
>>>     constraints=ExecutionConstraints(
>>>         wall_time=30
>>>     ),
>>>     wallclock_limit=43200,  # Item inside **scenario_kwargs
>>> )

This is a very standard example. Here we specify:

The entrypoint as linear
The runsolver_path argument
global_cfgcalls contains a single function (in this case, the same as the entrypoint)
input_data is the list instances_list
data_kwarg as instance and seed_kwarg as seed
Other GGA arguments

>>> from optilog.tuning.configurators import GGAConfigurator
>>>
>>> configurator = GGAConfigurator(
>>>     linear,
>>>     runsolver_path=args.runsolver_path,
>>>     global_cfgcalls=[linear],
>>>     input_data=instances_list,
>>>     constraints=ExecutionConstraints(
>>>         memory=f'18G',
>>>         wall_time=120
>>>     ),
>>>     run_obj="quality",
>>>     data_kwarg="instance",
>>>     seed_kwarg="seed",
>>>     quality_regex="^o (\d+)$",
>>>     seed=1,
>>>     cost_min=0,
>>>     cost_max=(2 << 64) - 1,
>>> )

The following example presents a few differences:

The runsolver_path is omitted because runsolver is in PATH
input_data, data_kwarg and seed_kwarg are omitted because they are not required to configure func1

>>> from optilog.tuning.configurators import GGAConfigurator
>>>
>>> @ac
>>> def func1(
>>>     p1: Bool() = True, p2: Real(-1.3, 2) = 0,
>>>     p3: Int(-5, 5) = 0, p4: Categorical("A", "B", "C") = "A"):
>>>     ...
>>>
>>> configurator = GGAConfigurator(
>>>     func1,
>>>     global_cfgcalls=[func1],
>>>     memory_limit=18 * 1024,
>>>     run_obj="quality",
>>>     quality_regex="^o (\d+)$",
>>>     seed=1,
>>>     cost_min=0,
>>>     cost_max=(2 << 64) - 1,
>>> )

In case we want to configure over a set of *.cnf.gz instances in a directory we could specify input data as follows:

>>> from optilog.tuning.configurators import GGAConfigurator
>>>
>>> configurator = GGAConfigurator(
>>>     linear,
>>>     runsolver_path=args.runsolver_path,
>>>     global_cfgcalls=[linear],
>>>     input_data="/path/to/instances/**/*.cnf.gz",
>>>     constraints=ExecutionConstraints(
>>>         memory=f'18G',
>>>         wall_time=120
>>>     ),
>>>     memory_limit=18 * 1024,
>>>     run_obj="quality",
>>>     data_kwarg="instance",
>>>     seed_kwarg="seed",
>>>     quality_regex="^o (\d+)$",
>>>     seed=1,
>>>     cost_min=0,
>>>     cost_max=(2 << 64) - 1,
>>> )