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. Iftrue
, 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 iscpu
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.monitoring
, a map containing a key namedenabled
, set totrue
orfalse
, indicating whether or not the OE should push data every step to the monitoring database.
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:
Found an issue in documentation? Write to us.