# Optimizer Options

The *Optimizer Options* is a set of parameters used to fine-tune the study optimization strategy during the *optimize* step.

Optimizer options have the following structure:

<table data-full-width="true"><thead><tr><th>Field</th><th>Type</th><th>Value restrictions</th><th>Description</th></tr></thead><tbody><tr><td><code>onlineMode</code></td><td>string</td><td><code>RECOMMEND</code>, <code>FULLY_AUTONOMOUS</code></td><td>Changes are approved automatically or must be edited/approved by the user</td></tr><tr><td><code>safetyMode</code></td><td>string</td><td><code>LOCAL</code>, <code>GLOBAL</code></td><td>Defines how Akamas optimizer evaluates goal constraints</td></tr><tr><td><code>safetyFactor</code></td><td>decimal</td><td>between 0 and 1</td><td>Parameter that impacts the distance from goal constraints for new configurations</td></tr><tr><td><code>workloadOptimizedForStrategy</code></td><td>string</td><td><code>LAST</code>, <code>MOST_VIOLATED</code>, <code>MAXIMIN</code></td><td>Selects the computation strategy to generates future configurations</td></tr><tr><td><code>explorationFactor</code></td><td>decimal, string</td><td>between 0 and 1 or <code>FULL_EXPLORATION</code></td><td>Set the tendency to explore toward unexplored configuration values</td></tr><tr><td><code>trialsWithBeta</code></td><td>integer</td><td>-</td><td>Number of trials that will be executed with beta-warping optimization. If the threshold is reached, the following experiment disables the usage.</td></tr></tbody></table>

### Options for both online and offline studies

#### Safety Factor

The `safetyFactor` field specifies how much the optimizer should stay on the safe side in evaluating a candidate configuration with respect to the goal constraints. A higher safety factor corresponds to a safer configuration, that is a configuration that is less likely to violate goal constraints.

Acceptable values are all the real values ranging between 0 and 1, with (`safetyFactor` - 0.5) representing the allowed margin for staying within the defined constraint:

* 0 means "no safety", as with this value the optimizer totally ignores goal constraint violations;
* 0.5 means "safe, but no margin", as with this value the optimizer only tries configurations that do not violate the goal constraints, by remaining as close as possible to them;
* 1 means "super safe", as with this value the optimize only tries configurations that are very far from goal constraints.

For live optimization studies, 0.6 is the default value, while for offline optimization studies, the default value is 0.5.

### Options for offline studies

For [offline optimization studies](https://docs.akamas.io/akamas-docs/3.6/using/study/offline-optimization-study), the `optimizerOptions` field can be used to specify whether **beta-warping** **optimization** (a more sophisticated optimization that requires a longer time) should be used and for how many experiments:

```yaml
trialsWithBeta: 20
```

### Options for live studies <a href="#define-workloads-selection" id="define-workloads-selection"></a>

For live optimization studies, the `optimizerOptions` field can be used to specify several important parameters governing the live optimization:

```yaml
optimizerOptions:
  onlineMode: RECOMMEND                    # [RECOMMEND|FULLY_AUTONOMOUS]
  safetyMode: GLOBAL                       # [GLOBAL|LOCAL]
  workloadOptimizedForStrategy: MAXIMIN    # [MAXIMIN|LAST|MOST_VIOLATED]
  safetyFactor: 0.55                       # 0 <= safetyFactor <= 1
  explorationFactor: 0.05                  # 0 <= explorationFactor <= 1 or FULL_EXPLORATION
```

Notice that while available as independent options, the optimizer options `onlineMode` (described [here below](#online-mode)), `workloadOptimizedForStrategy` ([here below](#workload-strategy)) and the `safetyFactor` ([see above](#safety-factor)) work in conjunction according to the following schema:

| Online Mode        | Safety Mode | Workload strategy |
| ------------------ | ----------- | ----------------- |
| `RECOMMEND`        | `GLOBAL`    | `MAXIMIN`         |
| `FULLY_AUTONOMOUS` | `LOCAL`     | `LAST`            |

All these optimizer options can be changed at any time, that is while the optimization study is running, to become immediately effective. The [Optimizer options commands](https://docs.akamas.io/akamas-docs/3.6/reference/cli-reference/optimizer-options-commands) page in the reference guide provides these specific update commands.

#### Online Mode

The `onlineMode` field specifies how the Akamas optimizer should operate:

* `RECOMMEND`: configurations are recommended to the user by Akamas and are only applied after having been approved (and possibly modified) by the user;
* `FULLY AUTONOMOUS MODE`: configurations are immediately applied by Akamas.

#### Safety Mode

The `safetyMode` field describes how the Akamas optimizer should evaluate the goal constraints on a candidate configuration for that configuration to be considered valid:

* `GLOBAL`: the constraints must be satisfied by the configuration under all observed workloads in the configuration history - this is the value taken in case `onlineMode` is set to `RECOMMEND`;
* `LOCAL`: the constraints are evaluated only under the workload selected according to the workload strategy - this should be used with `onlineMode` set to `FULLY_AUTONOMOUS`.

Notice that when setting the `safetyMode` to `LOCAL`, the recommended configuration is only expected to be good for the specific workload selected under the defined workload strategy, but it might violate constraints under another workload.

#### Workload Strategy

The `workloadOptimizedForStrategy` field specifies the workload strategy that drives how Akamas leverages the workload information when looking for the next configuration:

* `MAXIMIN`**:** the optimizer looks for a configuration that maximizes the minimum improvements for all the already observed workloads;
* `LAST`**:** for each workload, the last observed workload is considered - this works well to find a configuration that is good for the last workloads - it is often used in conjunction with a `LOCAL` safety mode (see [here above](#safety-factor));
* `MOST_VIOLATED`: for each workload, the workload of the configuration with more violations is considered.

#### Exploration Factor

The `explorationFactor` field specifies how much the optimizer explores the (unknown) optimization space when looking for new configurations. For any parameter, this factor measures the difference between already tried values and the value of a new possible configuration. A higher exploration factor corresponds to a broader exploration of never-tried-before parameter values.

Acceptable values are all the real values ranging between 0 and 1, plus the special string `FULL_EXPLORATION`:

* 0 means "no exploration", as with this value the optimizer chooses a value among the previously seen values for each parameter;
* 1 means "full exploration, except for categories", as with this value the optimizer for a non-categorical parameter any value among all its domain values can be chosen, while only values (categories) that have already been seen in previous configurations are chosen for a categorical parameter;
* `FULL_EXPLORATION` means "full exploration, including categories" as with this value the optimizer chooses any value among all its domain values, including categories, even if not already seen in previous configurations.

In case the desired `explorationFactor`is 1 but there are some specific parameters that also need to be explored with respect to all its categories, then PRESET steps (refer to the [Preset step](https://docs.akamas.io/akamas-docs/3.6/reference/construct-templates/study-template/steps/preset-step) page) can be used to run an optimization study with these values. For an example of a live optimization study where this approach is adopted see [Optimizing a live full-stack deployment (K8s + JVM)](https://docs.akamas.io/akamas-docs/3.6/knowledge-base/optimizing-a-live-full-stack-deployment-k8s-+-jvm).

### Example

The following fragment refers to an optimization study that runs 100 experiments using the SOBOL optimizer and forces 50% of the experiments to use the beta-warping option, enabling a more sophisticated but longer optimization:

```yaml
name: "my_optimize"  # name of the step
type: "optimize"     # type of the step (optimize)
optimizer: "SOBOL"
numberOfExperiments: 100  # amount of experiments to execute
numberOfTrials: 2         # amount of trials for each experiment
```