Trigger Parameters (Optimization Engine)

The Optimization Engine (OE) is executed through a Job Trigger Calculation. This page presents the OE-specific parameters that are passed to a job trigger calculation. These parameters are stored as Groovy map that we pass to api.jsonEcode().

model.startJobTriggerCalculation(
        "cregistry.pricefx.eu/engineering/pricefx-optimization-engine",
        "latest",
        api.jsonEncode([
              // OE specific parameters presented in this page
        ]),
        "oe"  
)

The OE parameters map expects two mandatory keys (problem, stop_condition), and accepts an optional one (advanced).

Mandatory Parameters

There are two mandatory parameters expected by the OE:

problem contains the complete problem description in the form of a Groovy map.
Refer to Problem Description for more information about how to create a problem description.
stop_condition is a map that may contain several keys defining the stop conditions of the OE. In case several conditions are set up, the OE stops as soon as any one of them triggers.
- Mandatory keys:
  - max_steps is an integer and defines the maximum number of steps the Optimization Engine should run.
    - Note that the OE may automatically increase this number if it is not enough to perform at least one full calculation of the computation graph provided by the problem description .
- Optional keys:
  - max_duration is a string containing the number of minutes after which the OE should stop. This string is prefix by “PT” and suffixed by “M”, e.g. PT60M, for a maximum duration of one hour.
    - If this parameter is absent, the OE will simply not look at its running duration to decide whether or not to stop.
  - disable_auto_stop is a Boolean that indicates whether or not the OE should use its auto stop. If true, the OE will run until it reaches the maximum number of steps or the maximum duration (whichever occurs first) instead of automatically stopping when it considers itself to be stable enough.
    - If this parameter is absent, it is considered to be false.

It is usually advised to set up a large number for max_step (e.g. 100000) with disable_auto_stop = false.

Here is an example of the minimal parameters required for an OE job trigger:

def oe_parameters = [
        stop_condition: [
                max_steps : 10000,
        ],
        problem : out.ProblemDescription,
]

Advanced Parameters

The Optimization Engine allows the user the set up some advanced parameters for various purposes. Some of these parameters are often used in production, for instance to configure how the output tables are named, while some others serve purely development and debugging purposes.

All of these advanced parameters are stored in a map associated to the advanced key.

Advanced Parameters Possibly Useful in Production

execution_mode is a string defining the actual OE behavior.
- The default value is optimization mode, where the OE behaves normally.
- In simulation mode, the OE does not try to optimize any criterion but instead just computes exposed variables and criterion states from the initial values of decision variables.
  - In practice, value finders are replaced with static variables when the system is instantiated in this mode.
  - This mode is particularly useful to compute the initial state of constraints.
- The wtp_tuning mode is reserved for Market Simulation when using the OE as a mean to tune Willingness to Pay (WTP).
  - This mode is currently not used in production.
profiling is a map allowing up to four keys, one for each possible metric to profile:
- criticality is a map containing:
  - enabled, a Boolean indicating whether or not the profiling of criticality is enabled.
  - flush_period, an integer indicating when the recording journals should be flushed.
  - sample_period, an integer indicating the sampling of the steps. E.g. 10 means the criticality is recorded every ten steps.
  - If enabled, the OE outputs a new table named Profile_Criticality containing the highest criticality value at each sampled step.
- value_finders is a map containing:
  - enabled, a Boolean indicating whether or not the profiling of value finders is enabled.
  - flush_period, an integer indicating when the recording journals should be flushed.
  - sample_period, an integer indicating the sampling of the steps. E.g. 10 means the criticality is recorded every ten steps.
  - If enabled, the OE outputs a new table named Profile_ValueFinders containing the value, amplitude and entropy of each value finders at each sampled step.
- memory is a map containing:
  - enabled, a Boolean indicating whether or not memory profiling is enabled.
  - gc, a Boolean indicating whether or not garbage collecting is enabled during the profiling.
  - If enabled, the OE attaches to the model a CSV file containing memory profiling data.
- asyncProfiler is a map containing:
  - enabled, a Boolean indicating whether or not memory profiling is enabled.
  - event, a string specifying the type of event to profile. Possible values: cpu, alloc, lock, cache-misses. The default value is cpu which is to profile CPU cycles. Refer to async-profiler documentation for more information.
  - If enabled, the OE attaches to the model an HTML file containing CPU profiling data.
io is a map containing:
- outputsPrefix, a string that will be used to prefix every table created by this run of the OE.

Here is a typical example using some advanced parameters, taken from Price Waterfall Optimization Accelerator:

[
        stop_condition: [
                max_steps        : maxSteps,
                disable_auto_stop: !autoStop,
        ] + (maxDurationMinutes != null && maxDurationMinutes > 0 ? [max_duration: "PT${maxDurationMinutes}M"] : [:]),
        problem       : problem,
        advanced      : [
                execution_mode: "optimization",
                profiling     : [
                        criticality : [
                                enabled     : true,
                                flushPeriod : advancedParameters.CriticalityProfilingFlushPeriod as Integer,
                                samplePeriod: advancedParameters.CriticalityProfilingSamplePeriod as Integer,
                        ]
                ],
                io            : [
                        outputsPrefix: optim.OPTIMIZATION_OUTPUTS_PREFIX,
                ],
        ]
]

Advanced Parameters for Development and Debugging Purposes Only

A certain number of internal parameters are available for development and debugging purposes. These are stored in a map associated to the internal key. These internal advanced parameters are already described on this page (for Pricefx staff only).

Here is an example of code with every possible advanced parameter:

[
        stop_condition: [
                max_steps        : 5000,
                disable_auto_stop: true,
        ],
        problem       : problem,
        advanced      : [
                execution_mode: "optimization",
                profiling     : [
                        criticality : [
                                enabled     : true,
                                flushPeriod : 10,
                                samplePeriod: 1,
                        ],
                        value_finders: [
                                enabled     : true,
                                flushPeriod : 10,
                                samplePeriod: 1,
                        ],
                        memory: [
                                enabled     : true,
                                gc          : true,
                        ],
                        asyncProfiler: [
                                enabled     : true,
                                event       : "cpu",
                        ]
                ],
                io            : [
                        outputsPrefix: "Optimized",
                ],
                internal      : [
                        glassbox_measurement_frame_length : 10,
                        glassbox_insistence_threshold     : 0.005,
                        ncs2_max_influence_frame_length   : 2,
                        ncs2_min_influence_frame_length   : 30,
                        ncs2_elite_ratio                  : 0.5,
                        ncs2_elite_inertia                : 2,
                        ncs5_extrapolation_horizon        : 100,
                        ncs5_extrapolation_default_inc    : 0.01,
                        ncs5_extrapolation_inc_ratio      : 0.1,
                        ncs5_smoothing_horizon            : 10,
                ]
        ]
]