PW_Library is used in nearly all the other logics deployed by the Accelerator and defines a set of generic OE-related functions to facilitate the model’s tables reading and writing and to deal with parameter definition in the UI. It is accessed via the calls on libs.PW_Library.XXX in the code. It is preferable to keep this code unmodified to facilitate the maintenance and readability of the project.

PW_InternalLibrary contains some functions needed specifically for this Accelerator, such as reading its configuration from the application settings, applying the user filters in each part of the model, preprocessing the data for the charts, and many small helpers for the charts rendering.

If a specific function is needed for the project, it should be added in PW_InternalLibrary. It will be accessed then via libs.PW_InternalLibrary.XXX in the code.

When users deploy the accelerator, they define the Data Source and the mapping of the entries. But in some cases, they could want to change the source or the mapping for some models. This tab displays the Datamart source and the mapping deployed by the accelerator and allows the user to change it. It is also the place where the model for elasticity is defined.

It declares the mapping of fields to be used in the model.

If the optimization model needs fewer or more fields than the ones which are preset by the accelerator, then it is the place to update the mapping.

You can also remove the Elasticity user input if no elasticity is used in the optimization.

This logic aggregates the transaction Datamart, which was confirmed or changed in the previous step. The optimization is done at a product x customer level, not at the transaction level.

A Datamart table called Aggregated is created in the model. It is a product x customer Datamart. This is the main connection to external data.

This calculation is the main connection to the external data and most often requires to be modified to accommodate the specifics of the customer data, such as mandatory filters. If the waterfall structure is not the standard one, maybe some columns should be added to the Aggregated table. In this case, you may also change the user inputs to define this mapping, too (see https://pricefx.atlassian.net/wiki/spaces/ACC/pages/5933171198/Technical+User+Reference+Optimization+-+Price+Waterfall#Mapping-Tab).

The Aggregated table is a result of an aggregation. In some cases, the aggregation can change; for example to replace an average with a median.

This logic lets the end user choose the filters to scope the optimization, through the configurator PW_2_Sco_Eval_Scope_Configurator. It means, for example, creating a model with a scope filtered on a product group or a set of customers. On the right, it displays some charts to evaluate how the scope is defined.

A map of filters which are called later in the code by model.inputs('definition', 'scope').Scope.

A dashboard with information, charts, and tables that summarize the scope taken into account according to the user filters.

The main reason to modify these logics is to retrieve data from other sources (PX, DS, DM…) or with different filters. The filtering options that we expose to the user are modified here.

The goal of this calculation is to transform the Aggregated table into a collection of tables stored in the model and to present the data efficiently for the Optimization Engine. It involves mainly SQL requests, used with Pricefx API functions, as well as shortcut functions to filter the data and read the Accelerator settings from the library PW_InternalLibrary. This step also extracts the elasticities from the Segmentation Model in a table.

This step writes a collection of tables; the most important ones are:

• Segmentation table – Produced from the selected Segmentation model.

• Problem_nameOfTheSpace_nameOfTheScope tables – Data manipulation to prepare the last tables needed by the Optimization Engine. These logics are prefixed by “Store_” and create the model tables that act as an endpoint for the Optimization Engine. Be careful, their names follow a strict format. Only the problem tables that do not contain user input values, like objective and constraints, are created here. The other ones are created during the RunOptimization calculation.

The complexity of the data preparation needed in this step depends on the problem to solve. The main reason to modify this logic is to expose different Problem tables to the Optimization Engine if some spaces or some scopes are changed in the problem.

These tabs are used to retrieve the user objectives and as such, are configurators. They contain all the information needed to guide the optimization process by setting the constraints and the goals to reach. The separation into two tabs is mainly for UI purposes.

The user inputs are stored to be aggregated in the following steps with the rest of the data. In general, it means computing some target and threshold values at different levels of granularity.

It is quite common to change these logics by adding or modifying the constraints and objectives in the problem; for example, adding targets at some levels or setting thresholds to keep some values in check. These modifications are needed but not sufficient as the problem modeling itself must be changed to take them into account. It is possible to change the number of tabs where these objectives and constraints are defined, but then the Model Class definition has to be modified too.

This tab is used to retrieve the optimization run parameters and as such, is a configurator.

The user inputs are stored to be used in the RunOptimization calculation. The most important values are the following three that define when the Optimization Engine will stop:

• Max. Number Of Steps – For how long, in a number of steps, the optimization will run before considering it has reached a “good” state. The default value should be enough, but remember that this value can be increased if the optimization logs many values as “still converging”.

• Max. Number of Minutes – For how long, in a number of minutes, the optimization will run before considering it has reached a “good” state. The default value is 0 (= no limit), but for some large models it may be useful to define a default limit;

• Stop when stabilized – Allows an early stop if the model is stabilized.

There is also a Profiling group of parameters but it is more for a development purpose.

The most common reason to change the logic is to set different default values. All the outputs of this logic are used in the PW_4_Res_Calc_RunOptimization logic.

The goal of this calculation is to create a simulation and an optimization run and retrieve their results. To do so, we need to create a Problem Description that details the structure of the problem to solve by the Optimization Engine and to give endpoints for the OE to get the data of the problem. The previous steps will change the problem by altering its scope and changing the objectives, and the data will be fed directly to the OE thanks to the model tables.

This step consists of:

• Data manipulation to prepare the last tables needed by the OE. These logics are prefixed by Store_ and create the model tables prefixed by Problem_ that act as an endpoint for the OE. Be careful, their names follow a strict format: These endpoints must be named according to the Problem_nameOfTheSpace_nameOfTheScope present in the ProblemDescription.groovy and return the corresponding data. The behavior of the OE and its way of reading data from endpoints highlight the need for a well-thought-out Scope step. Creating tables of the needed data, already computed and aggregated, implies being well aware of “where is the data I need” and “how do I need to transform it”. Due to computations depending on user inputs from business rules and objectives, some tables have to be created in later steps, explaining why even the RunOptimization calculation can have some store logics. That is why it is normal to refactor and improve scope logics and the other store logics during the development of ProblemDescription.groovy.

• ProblemDescription.groovy element – Returns the problem description in a map.  The content of the problem description is detailed in Problem Description.

• GlassboxConfig.groovy element – Parses the problem description to automate the post-processing.

• Run.groovy element – Contains the code that handles the problem description. It takes the description of the problem and the advanced parameters user inputs, and triggers the two optimization jobs thanks to model.startJobTriggerCalculation. Each run will return prefixed tables of similar structures. The jobs will run in parallel. The first one is the optimization itself and its outputs are prefixed by “Optimized”. The second one is a simulation: it simulates the first state of the optimization and will be a reference to compare before/after values in the results dashboards. Its outputs are prefixed by “Current”. The job type (optimization vs. simulation) is indicated by the input parameters of the model.startJobTriggerCalculation function.

 Once the problem description is created, it is sent via a Kafka message to trigger the instantiation of a job running an OE configured by this file. The OE has to have access to the correct endpoints to get the data and to know where to write back the results when the computation is finished.

The Groovy code does some preparation work. It creates Problem_nameOfTheSpace_nameOfTheScope tables – data manipulation to prepare the last tables needed by the OE. These logics are prefixed by “Store_” and create the model tables that act as an endpoint for the OE. Be careful, their names follow a strict format. Only the problem tables that contain user input values, such as objectives and constraints, are created here. The other ones are created during the PW_3_Conf_Calc_FilterScope calculation.

A Groovy element also reads the problem description to retrieve a list of parameters used during the postprocessing step to reformat the Glassbox data.

At the end of its run, the OE will write a set of model tables containing its results and the Glassbox information needed to understand why this solution was used. This writing is done directly by the OE and is not related to a Groovy logic. This job is done by the two OE jobs, the simulation one and the optimization one.

• The Glassbox table provides optimization indicators for each pair of instantiated value finder – criterion. The simulation job does not create any Glassbox table.

• The tables prefixed by Results_ present the state of the objectives and constraints at the end of the optimization.

• The tables prefixed by Solution_ present the raw values that the system was meant to find (declared as Value_Finder in the Problem Description). The simulation job does not create any Solution table.

• The tables prefixed by Simulation_ present the value of computed variables marked as exposed in the description, typically including values of interest such as forecasted quantities.

Any modification of the problem modeling and type of constraints to apply or objectives to reach implies a modification of the Problem Description, thus ProblemDescription.groovy should change accordingly.

⚠ If the problem description changes, do not forget to check if it is necessary to change or create some Problem tables, either in the Configuration step, PW_3_Conf_Calc_FilterScope logic, or here in the Results step, PW_4_Res_Calc_RunOptimization logic.

In some cases, it could be useful to change the OE image and/or the OE tag that the job trigger refers to. Their values are in the element Run.groovy.

This calculation retrieves the outputs of the RunOptimization logic and reformats them to provide tables that can be used to show user-friendly optimization results. Each element stores one model table or some similar tables.

• Store_Optimized and Store_Current logics create the Optimized and Current tables that mirror each other. The Current table details the state of the system before the optimization; the Optimized one is the state after the optimization. Therefore a lot of visualizations will directly use these two tables to highlight the evolution of key values and the impact of the optimization. They are both created the same way, using the function defined in AggregationUtils.groovy.

• Store_Details_ logics write tables whose goal is to clearly show, for each type of variable adjusted by the OE, the optimized value, the reference value (what would that value be if the OE did not optimize anything), their difference, and the needed data to know what is impacted by this value (for example, returning the SpecificAdjustmentRate, but also the revenue and the margin rate, by customer group in the Customer Groups table). This way, the user can see the impact of the optimization on every adjusted value.

• StoreGlassboxTables element is a call to the Optimization Common Library to calculate aggregated metrics on the optimization agents criteria and value finders. (Refer to https://pricefx.atlassian.net/wiki/spaces/ACCDEV/pages/4818370673/Optimization+Common+Libraries#GlassboxLib – internal access only.)

This calculation writes a collection of tables:

• Current table – Details the state of the system before the optimization.

• Optimized table – Details the state of the system after the optimization. Its architecture mirrors the Current table one.

• Details tables – There is one table for each type of variable adjusted by the OE, and it contains the optimized value, the reference value (what would that value be if the OE did not optimize anything), their difference, and the needed data to know what is impacted by this value (for example, returning the customer_id and the customer_type for the Detail_CustomerAdjustment table). This way, the user can see the impact of the optimization on every adjusted value.

• GlassboxVF_ tables – Their names are built as GlassboxVF_NameOfTheSpace_NameOfTheValueFinder, there is one table by value finder key (i.e. type of value finder). These tables store the overall values of each value finder.

• GlassboxProbe_ tables – Their names are built as GlassboxProbe_NameOfTheSpace_NameOfTheValueFinder, there is one table by value finder key (i.e. type of value finder). These tables store the initial movement of each value finder.

• GlassboxCriteria_ tables – Their names are built as GlassboxCriteria_NameOfTheSpace_NameOfTheCriterion, there is one table by criterion key (i.e. type of criterion). These tables store the overall values of each criterion.

• Glassbox_AggregatedMetrics table – Summarizes the global interaction indicators between each value finder key and each criterion key.

• Glassbox_VFs_by_Key table – Summarizes the global overall indicators of each value finder key.

• Glassbox_Criteria_by_Key table – Summarizes the global overall indicators of each criterion key.

• Glassbox_Spaces table – Summarizes the total number of criteria and value finders in each space.

If the problem description has been changed, then the parameter set that helps to create the Current and the Optimized tables has to be changed too. It is in the element AggregationUtils.groovy.

The other most common reason to change the logic is to reformat some data to ease the work of providing charts in the Result step tabs.

This tab exposes the results of the OE execution in an HTML summary and some complex graphs. It is a comparison of the optimized values and the current ones (what would that value be if the OE did not optimize anything).

The charts are created with the usual method:

api.newChartBuilder(...)

There are eight portlets:

• HTML summary to write explicitly the main variations.

• Waterfall comparison.

• Four bar charts that compare the revenue and margin, before and after the optimization, by product group and by customer group.

• Two bullet charts, one for the current state and one for the optimized one. They show the volume, the revenue, and the margin percentage for each pair of product x customer.

For details see https://pricefx.atlassian.net/wiki/spaces/ACCDEV/pages/3992879122#Impact-Tab.

Add, modify or remove visualizations. This step is one of the most straightforward ones and its modification should not impact the previous steps.

This tab clearly shows, for each type of variable adjusted by the OE, the optimized value, the current value (what would that value be if the OE did not optimize anything), their difference, and the needed data to know what is impacted by this value. This way, the user can see the impact of the optimization on every adjusted value.

Some data tables. For details see https://pricefx.atlassian.net/wiki/spaces/ACCDEV/pages/3992879122#Details-Tab.

Add, modify or remove table outputs. In practice, if the list of the value finders or their definition in the problem description change, the detail tables would change and thus these outputs would be modified.

These tabs expose the technical state of the OE execution at the end of the process. It is a development tool to help tune the model. It is only a call to the Optimization Common Library tools. A previous call to the same library should have be run from a calculation (refer to the PrepareeResult calculation paragraph).

This logic displays charts that show the satisfaction, influences, impacts of the value finders and the criteria, initial movements of the value finders, and evolution of the criticality during the process of optimization. For details see Glassbox Dashboards.

In general, there is no reason to change this dashboard.

This logic is used to access model results from outside of the model itself; for example in another logic. The first step is to use api.model("ModelName") to get the model and then use the function evaluate on it to retrieve an answer depending on the nature of the given parameters. The code needed to get these results is:

def model = api.model(“The Model Unique Name”)
def results = model.evaluate(
  “query_results”, 
  [
    product: "someProductID",
    customer: "someCustomerID",
  ]
)
def unitNetPrice = results['unit_net_price']

The accepted inputs and the corresponding returned results are:

The evaluator provides all the optimized waterfall values. For details see Results Description (Optimization - Price Waterfall).

If the optimization model depends on new fields and if it provides new values, the evaluator should be changed to take them into account.