.. include:: ../shared/configurators.rst
.. _scenario-generation:


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.

.. py:module:: optilog.tuning.configurators
    :noindex:

.. autoclass:: optilog.tuning.configurators.TuningEntrypointType
    :members:
    :undoc-members:
.. autoclass:: optilog.tuning.configurators.TuningGlobalConfigurableType
    :members:
    :undoc-members:
    
.. autoclass:: optilog.tuning.configurators.GGAScenario
.. autoclass:: optilog.tuning.configurators.SMACScenario

Here you can see a few examples with GGA and SMAC. Starting with a SMAC example:

.. code:: python
    :number-lines:
    
    from optilog.tuning import ac
    from optilog.tuning.configurators import SMACScenario
    from optilog.blackbox import ExecutionConstraints, RunSolver
    
    @ac
    def entrypoint(data, seed, ...):
        ...
    
    if __name__ == '__main__':
    
        configurator = SMACScenario(
            entrypoint,
            input_data=['path1', 'path2', 'path3'],
            run_obj='quality',
            data_kwarg="data",
            seed_kwarg="seed",
            quality_regex=r"^Result: (\d+)$",
            constraints=ExecutionConstraints(
                s_wall_time=30,
                s_real_memory="8GB",
                enforcer=RunSolver()
            ),
            wallclock_limit=43200,  # Item inside **scenario_kwargs
        )
    
        configurator.generate_scenario('./smac-scenario')

In this example we specify:

* The `entrypoint` function as `entrypoint`
* The path to `runsolver` is omitted because runsolver is in PATH
* `input_data` is the list `instances_list`
* `data_kwarg` as `instance` and `seed_kwarg` as `seed`
* Other GGA arguments

.. warning::
    The generation of the scenario needs to be inside a ``__main__`` block
    because the file may be dynamically reimported by the execution scenario

.. code:: python
    :number-lines:

    from optilog.tuning import ac
    from optilog.tuning.configurators import GGAScenario
    from optilog.blackbox import ExecutionConstraints, RunSolver
    
    @ac
    def entrypoint(instance, seed, ...):
        ...
    
    if __name__ == '__main__':
        configurator = GGAScenario(
            entrypoint,
            input_data='path/to/instances/*.txt',
            constraints=ExecutionConstraints(
                s_wall_time=120,
                s_real_memory="18G",
                enforcer=RunSolver()
            ),
            run_obj="quality",
            data_kwarg="instance",
            seed_kwarg="seed",
            quality_regex="^o (\d+)$",
            seed=1,
            cost_min=0,
            cost_max=(2 << 64) - 1,
        )
        configurator.generate_scenario('./gga-scenario')

The following example presents a few differences:

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

.. code:: python
    :number-lines:

    from optilog.tuning import ac, Bool, Int, Real, Categorical
    from optilog.tuning.configurators import GGAScenario
    from optilog.blackbox import ExecutionConstraints, RunSolver
    
    @ac
    def func1(
        p1: Bool() = True, p2: Real(-1.3, 2) = 0,
        p3: Int(-5, 5) = 0, p4: Categorical("A", "B", "C") = "A"):
        ...
    
    if __name__ == '__main__':
        configurator = GGAScenario(
            func1,
            constraints=ExecutionConstraints(
                s_wall_time=25,
                s_real_memory="8GB",
                s_cpu_time=30,
                enforcer=RunSolver()
            ),
            run_obj="quality",
            quality_regex="^o (\d+)$",
            seed=1,
            cost_min=0,
            cost_max=(2 << 64) - 1,
        )
        configurator.generate_scenario('./gga-scenario')

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

.. code:: python
    :number-lines:
    
    from optilog.tuning import ac, Bool, Int, Real, Categorical
    from optilog.tuning.configurators import GGAScenario
    from optilog.blackbox import ExecutionConstraints, RunSolver
    
    @ac
    def func1(
        data,
        p1: Bool() = True, p2: Real(-1.3, 2) = 0,
        p3: Int(-5, 5) = 0, p4: Categorical("A", "B", "C") = "A"):
        ...
    
    if __name__ == '__main__':
        configurator = GGAScenario(
            func1,
            constraints=ExecutionConstraints(
                s_wall_time=25,
                s_real_memory="8GB",
                s_cpu_time=30,
                enforcer=RunSolver()
            ),
            input_data='path/to/instances/*.txt',
            data_kwarg="data",
            run_obj="quality",
            quality_regex="^o (\d+)$",
            seed=1,
            cost_min=0,
            cost_max=(2 << 64) - 1,
        )
        configurator.generate_scenario('./gga-scenario')