First, learn about criteria at https://pricefx.atlassian.net/wiki/spaces/KB/pages/3865280714.

After populating a scope with variables, the next step is to describe criteria that apply to some of them if needed.

General Rules

• A criterion declared in the criteria section of one scope is instantiated for each set of coordinates within the scope. Their names act as keys for coordinates inside their space, thus two criteria at the same coordinates cannot share the same name. This means two mutually exclusive scopes can define the same criterion in two different ways. An example with variables is given in https://pricefx.atlassian.net/wiki/spaces/KB/pages/3867312401.

• Every parameter can either be set directly inline or through data.

  • In the case of an inline type, the description provides a value. It is the way to provide a hard-coded value or a user-entry value.

  • In the case of a data type, the description provides a field name. The instantiation will seek in the problem table corresponding to the scope, named Problem_<name of the space>_<name of the scope> to get the values, which depend on the coordinates of the criteria.

• After (and during) an optimization run, a criterion is:

  • SATISFIED if the constraint expressed by the criterion is met.

  • ACCEPTABLE if it is within its acceptable margin of error.

  • UNACCEPTABLE otherwise.

• You can set priorities for criteria: low, medium, or high.

  • Higher priority unacceptable criteria are treated first in case of conflict, but the system will always try to solve every criterion.

Criteria Types

There are several types of criteria, that can be sorted into two categories:

• Single-Variable Criteria: sometimes called “simple criteria”. They apply to a single variable and go in the same space as said variable. They are:

  • target

  • lower_threshold and upper_threshold

  • maximization and minimization

• Multi-Variable Criteria: they apply to a list of variables. They are:

  • alignment

  • equality

Each criterion has its own set of parameters, but they all include the variable(s) to which the criterion applies. It is up to the person doing the configuration to make sure all the required variables are properly defined in the problem description.

Target

A target criterion applies to a single variable and expresses a value that this variable has to reach, within a given precision. It should be placed in the same space as its variable. Its parameters are:

• on – The variable it applies to.

• target – The target value.

• precision – The expected precision of the target. It should be set with technical or domain-related limitations in mind, it has nothing to do with a user being okay with a target not being exactly met.

  • A target to 0 with a precision of 0.1 will be considered satisfied if the value is in ]-0.1; 0.1[ (see the figure below).

  • Usually, we set the precision to half the smallest relevant amount of change for the variable.

    • E.g. half a cent for a variable in Euros.

• acceptable_delta – The acceptable margin of error. It is related to the end-users tolerance to error.

  • A target to 0 with an acceptable delta of 0.5 will be considered acceptable (but not satisfied) if the value is in [-0.5,-precision[ U ]+precision, +0.5] (see the figure below).

• priority – low, medium, or high.

Open

Lower Threshold

A lower threshold criterion applies to a single variable and expresses a value above which this variable has to stay. It should be placed in the same space as its variable. Its parameters are:

• on – The variable it applies to.

• threshold – The threshold value.

• acceptable_delta – The acceptable margin of error. It is related to the end-users' tolerance to error.

  • A lower threshold at 0 with an acceptable delta of 0.5 will be considered acceptable (but not satisfied) if the value is in [-0.5, 0] (see the figure below).

• priority – low, medium, or high.

Open

Upper Threshold

An upper threshold criterion applies to a single variable and expresses a value below which this variable has to stay. It should be placed in the same space as its variable. Its parameters are:

• on – The variable it applies to.

• threshold – The threshold value.

• acceptable_delta – The acceptable margin of error. It is related to the end-users' tolerance to error.

  • An upper threshold at 0 with an acceptable delta of 0.5 will be considered acceptable (but not satisfied) if the value is in [0, 0.5] (see the figure below).

• priority – low, medium, or high.

Maximization

A maximization criterion applies to a single variable and expresses the need to make its value as high as possible (towards positive infinity). It should be placed in the same space as its variable. Its parameters are:

• on – The variable it applies to.

• acceptable_value – The value above which the user considers that the criterion is acceptable. It can be a gross estimation because it has only a fringe impact on the optimization. It does not act as a threshold at all: once reached, the system will continue to try to go higher, but will lower the importance of the criterion.

• priority – low, medium, or high.

Beware: Nobody knows the actual global optimum and because of this a maximization can never be satisfied (see the figure below). Higher priority unacceptable criteria are treated first in the system, this is why it is strongly advised to set a lower priority for maximization criteria than for other criteria, except if you set an acceptable_value low enough to be sure it can be reached without impeding the other criteria too much.

Minimization

A minimization criterion applies to a single variable and expresses the need to make its value as low as possible (towards negative infinity). It should be placed in the same space as its variable. Its parameters are:

• on – The variable it applies to.

• acceptable_value – The value below which the user considers that the criterion is acceptable. It can be a gross estimation because it has only a fringe impact on the optimization. It does not act as a threshold at all: once reached, the system will continue to try to go lower, but will lower the importance of the criterion.

• priority – low, medium, or high.

Beware: Nobody knows the actual global optimum and because of this a minimization can never be satisfied (see the figure below). Higher priority unacceptable criteria are treated first in the system, this is why it is strongly advised to set a lower priority for maximization criteria than for other criteria, except if you set an acceptable_value low enough to be sure it can be reached without impeding the other criteria too much.

Multi-Variable Criteria Rules

Multi-variable criteria are deprecated and will be removed from OE v5 onward.

A multi-variable criterion applies to a list of variables. They use the same way as computations to refer to the variables to which they apply (see https://pricefx.atlassian.net/wiki/spaces/KB/pages/3867312401 to learn how to refer to variables from other spaces). For instance, If the user wants all variables of the same key to be equal, then the equality criterion should be placed in a “global” dimensionless space, using all as on type. If the user wants several variables of different keys to be equal, then the criterion should be in the same space as these variables and use fixed as on type.

Be aware that, in practice, a multi-variable criterion is a composite criterion: the OE will instantiate several single-variable criteria, applied on hidden computed variables. For instance, for an alignment criterion between A, B, and C, the OE creates two computed variables (A minus B, and B minus C), and applies a threshold to zero to each of them. When looking at the results, the state of a multi-variable criterion is the worst state among its single-variable criteria.

Alignment Criteria

Alignment criteria are deprecated and will be removed from OE v5 onward. The better solution is to explicitly describe alignments, with actual computed variables and threshold criteria, using spaces with dimensions sharing the same categories (see https://pricefx.atlassian.net/wiki/spaces/KB/pages/3867639907/Spaces+and+Scopes+Description#Spaces and https://pricefx.atlassian.net/wiki/spaces/KB/pages/3867312401/Variables+Description#Reference-Disambiguation).

For instance, a product price alignment would be described in a [reference: product, following: product] space containing:

• A computed variable that is the difference between “reference product” price and “following product” price.

• A threshold criteria on that difference that expresses the desired alignment between both prices.

This way it offers a lot more flexibility than using the built-in alignment criteria.

It is important to keep https://pricefx.atlassian.net/wiki/spaces/KB/pages/3866755214/Criteria+Description#Multi-Variable-Criteria-Rules in mind.

An alignment criterion applies to several variables and expresses an order that must be respected by these variables. The general idea is “all other things being equal, please order these variables by this particular feature of theirs”. It works like this:

• The alignment criterion should be placed in the Global space, i.e. a dimensionless root space.

  • The only exception is when different orders for different coordinates are needed: in this case, the alignment must be placed in a space whose dimensions are those differentiating the orders.

    • E.g. prices by color and product_category, the color order is [blue, green, red] for product_category=shoes and [red, green] for product_category=cars, then the alignment has to be in a space with dimension product_category but not dimension color.

  • There are two examples below.

• The user specifies:

  • how to group the variables, i.e. what other things are equal;

  • how to order them within each group.

  • E.g. if you group discounts by product family and order them by customer revenue in the natural order, it:

    • implies that discounts are in the [product family, customer] space;

    • means that each discount in the same product family should be ordered following the customer revenue (higher revenue, higher discount).

      • Discounts in different product families are not ordered with each other.

The parameters of an alignment criterion are:

• on – The variables it applies to. They can be selected using all or fixed in the same way the inputs of computed variables are selected.

  • group – Defines how to group the selected variables so each group can be ordered.

    • type – The way we decide things are equal (for grouping them); the options are:

      • strict – The standard group by the operation that groups strictly equal things.

        • by – The list of dimensions or data fields to group by.

      • custom – This lets the user define for each feature how to decide if two elements are equal. It is useful to group things that are similar rather than strictly equal. It only works with doubles.

        • by – The list of dimensions or data fields to group by with instructions on how to group them.

          • feature – A dimension that is parsable to a double or a data field that contains a double.

          • type – The type of equality for this feature, either strict or approximate (strict will be used if no type is specified). In the case of approximate, the user has to set the parameter tolerance_as_amount or tolerance_as_rate to define the approximation as needed.

  • comparator – The comparator that defines the order.

    • type – There are three types currently available:

      • inc_natural_order – Increasing natural order over dimension or data field of any type.

      • dec_natural order – Decreasing natural order over strings dimension or data field of any type.

      • explicit – the user explicitly states the order within a list.

        • E.g. if you want to order prices by their color where blue is the lowest and red is the highest, then state the following order: ["blue", "red"].

        • This order can either be defined inline or through data in the alignment’s scope.

          • By using data, you can specify partial orders with a different min_gap for each.

      • Two other types of comparators exist but are deprecated:

        • double_inc_natural_order – Increasing natural order over string-typed dimension or data field that will be cast to double.

        • double_dec_natural_order – Decreasing natural order over string-typed dimension or data field that will be cast to double.

    • over – The feature over which the comparator is applied. It is usually a dimension, but it can be any data field in the scope where the variables are selected.

• The minimum gap between two consecutive variables is required. There are two options:

  • min_gap_as_amount if the gap is expressed as a fixed amount.

    • E.g. applied to A<B<C: A + min_gap_as_amount < B & B + min_gap_as_amount < C

  • min_gap_as_rate if the gap is expressed as a rate of the previous variable in the alignment.

    • E.g. applied to A<B<C: A + A*min_gap_as_rate < B & B + B*min_gap_as_rate < C

  • Each can be defined inline or through data.

• priority – low, medium, or high.

Under the hood, multi-variable alignment criteria are implemented as a series of lower-threshold criteria on differences or ratios of the aligned variables – depending on whether min_gap_as_amount or min_gap_as_rate is used. This min_gap is used to compute both the threshold value and the acceptable delta for the underlying threshold criteria.

Equality

Equality criteria are deprecated and will be removed from OE v5 onward. The best solution to replace them is to explicitly describe a Standard Deviation computed variable over all the desired input variables and apply a target criterion (equals to zero) to the standard deviation.

It is important to keep https://pricefx.atlassian.net/wiki/spaces/KB/pages/3866755214/Criteria+Description#Multi-Variable-Criteria-Rules in mind.

An equality criterion applies to a list of variables. It is used to express the equality between two variables. If the equality is between a variable and a given parameter, then you should use a target criterion instead. Its parameters are:

• on – The variables it applies to. They can be selected using all or fixed in the same way the inputs of the computed variables are selected.

  • group – Defines the groups within which the variables should be equal. This can be omitted if you want all the selected variables to be equal to each other. Works in the same way as with the Alignment criterion.

• precision – The expected precision of the equality. It should be set with technical or domain-related limitations in mind, it has nothing to do with a user being okay with the criterion not being exactly met.

  • Equality with a precision of 0.1 will be considered satisfied if the difference between the variables is in ]-0.1; 0.1[.

  • Usually, we set the precision to half the smallest relevant amount of change for the variable.

    • E.g. half a cent for a variable in Euros.

• acceptable_delta – The acceptable margin of error. It is related to the end-users' tolerance to error.

  • Equality with an acceptable delta of 0.5 will be considered acceptable (but not satisfied) if the difference between the variables is in [-0.5,-precision[ U ]+precision, +0.5].

• priority – low, medium, or high.

Refer to https://pricefx.atlassian.net/wiki/spaces/KB/pages/3866755214/Criteria+Description#Target to have a graphical understanding of Equality criterion precision and acceptable_delta parameters. Indeed, multi-variable equality criteria are implemented as a series of “target to zero” criteria on differences between the variables.