General Rules

A variable declared in the variables section of a scope is instantiated for each set of coordinates within the scope. Variable names act as keys for coordinates inside a space, thus two variables at the same coordinates cannot share the same name. This means two mutually exclusive scopes can define the same variable in two different ways. In the following sample, TotalDiscount is defined in two different ways, depending on the scope: two discount rates are applied for high turnovers, whereas only one is used for low turnovers.

Every parameter can either be set directly inline or through data.
- In the case of an inline type, the description expects 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 expects a field name. The instantiation will look in the 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 variable.
- See examples below with variables

Variables Types

There are three types of variables:

Value Finder – Active variable that self-adjusts during the run.
Static – Passive variable that stays constant during the run.
Computed – Variable that is computed from other variables during the run.

Each type comes with its specific parameters, detailed in the following sections.

Value Finders

Value Finders are the variables for which you seek a value -typically prices and discounts- also referred to as free variables or decision variables. They are defined by an initial value, a minimum and a maximum value, and some optimization engine parameters. Each parameter can either be initialized inline or through data.

List of the Value Finder parameters:

init – initial value
- This can be overridden by init_simulation_mode and/or init_optimization_mode if needed.
- init is used by default, init_<mode>_mode is used if present and OE is running in <mode>.
min – minimum value, hard limit
max – maximum value, hard limit
Then the advanced parameters can be of two types:
- continuous, used for standard Value Finders: initial_amplitude, minimum_amplitude, maximum_amplitude, increase_coefficient (greater than 1), decrease_coefficient (greater than 1) – These define the velocity and acceleration of the Value Finder.
- rounding, used for Value Finders where rounding rules apply. There are two types of rounding rules:
  - slots: between lower_boundary (included) and upper_boundary (included), the Value Finder is only allowed to take values that end with the numbers specified in the slots list, repeating the pattern with a specified period.
    - E.g. for prices between 0.19€ and 99.99€ to be rounded at 0.19, 0.49, and 0.99 the rule should be:
      - lower_boundary: 0.19
      - upper_boundary: 99.99
      - slots: [0.19, 0.49, 0.99]
      - period: 1
  - uniform_increment: the Value Finder increment step is uniform between the specified lower_boundary (included) and upper_boundary (included).
    - E.g. for prices to be rounded to .99€ between 99.99€ and 9999.99€ the rule should be:
      - lower_boundary: 99.99
      - upper_boundary: 9999.99
      - increment: 1
  - The user also has to specify the general decimal precision, i.e. the maximum desired number of decimal digits among all the rounding rules.
    - This precision has to be compatible with the finest increments and slots. E.g. if the finest increment is 0.01, then the precision should be 2.
  - The user can specify any number of rounding rules, the only condition is for them to be contiguous, i.e. the upper_boundary of the first rule should be equal to the lower_boundary of the next rule.

Static Variables

Static variables are typically used for parameters that do not change during a run, such as costs for instance. Their sole parameter is init, which defines their initial (and forever) value.

Computed Variables

A computed variable is a variable computed from other variables. You have to define what those other variables are and what computation is used. For instance, here is a margin rate computed from a gross margin and a revenue thanks to a division.

The optional field exposed lets the system know to output this variable into a Simulation table after the run. By default, computed variables are not outputted.

Inputs Types

Inputs are references to other variables in the description. There are two types of inputs, fixed and all:

fixed lets you pick specific variables one by one, either from your space or from another space. For instance, here is a variable that is the sum of two variables, one from the same space and one from another space. The system automatically fetches the right variables thanks to their coordinates. For instance, if the computed variable is in space ByCustomerAndProduct, one of the inputs may be from space ByProduct, and the system will fetch the variable with a matching product.

all lets you select a whole set of variables from a given space. For instance, in the space [product_family], we compute the revenue with a summation of all the [product] revenues. This will select the “Revenue” variable for all the products belonging to the product family.

Available Computations

This is a summary of this page: https://pricefx.atlassian.net/wiki/spaces/KB/pages/2719252576

The computations you need should already be available, like the basic arithmetics summation, subtraction, multiplication, and division. There is also exponentiation, and pricing-related operators rated summation and rated subtraction.

You can also write the expression inline (or even use a custom Java implementation).

Each computation expects specific inputs. For instance, summation can take either two fixed inputs or a set of inputs with all, but division can only takes two inputs. The https://pricefx.atlassian.net/wiki/spaces/KB/pages/2719252576 page documents all of this.

Referencing Other Spaces

Spaces and scopes can be referred to from other spaces and scopes to connect computed variables to their "inputs".

Referencing other spaces when connecting inputs is akin to projecting the dimensions from one space to another. Thus, for the Optimization Engine to be able to retrieve variables, the targeted space must share at least one category or hierarchy with the computed variable’s space.

For instance, with the following hierarchies:

hierarchies:
  - [product, product_family]
  - [customer]

You cannot:

from a [customer] space, reference a [product] space (and vice versa)
from a [customer] space, reference a [product_family] space (and vice versa)

You can:

What you can do is pretty intuitive and varied, depending on whether you seek to get particular coordinates by using fixed or a set of coordinates by using all. For the sake of exhaustiveness, here it is:

with input type fixed
- from a [product] space, reference a [product_family] space:
  - get the product family of the product
- from a [product, customer] space, reference a [product] space
  - get the product of the (product, customer) pair
- from a [product, customer] space, reference a [product_family] space
  - get the product family of the product in the (product, customer) pair
- from a [product, customer] space, reference a [product_family, customer] space
  - get the (product family, customer) pair that has the same customer as the (product, customer) pair and the family product of the product in the (product, customer pair)
- from a [product_family, customer] space, reference a [product_family] space
  - get the product family in the (product family, customer) pair
with input type all
- from a [product_family] space, reference a [product] space
  - get all the products of the product family
- from a [product_family] space, reference a [product, customer] space
  - get every (product, customer) pair for every product in the product family
- from a [product_family] space, reference a [product_family, customer] space
  - get every (product family, customer) pair with the corresponding product family
- from a [product_family, customer] space, reference a [product, customer] space
  - get every (product, customer) pair that has the same customer as the (product family, customer) pair, for every product in the product family
- from a [product_family, customer] space, reference a [product] space
  - get all the products of the product family from the (product family, customer) pair
- from a [product] space, reference a [product_family, customer] space
  - get every (product family, customer) pair with the product family of the product, and every customer
- from a [product] space, reference a [product, customer] space
  - get every (product, customer) pair with the corresponding product

When using all, you can also tell the Optimization Engine to “relax” one or several dimensions, i.e. to fetch all the other coordinates over these same dimensions instead of following hierarchies. For instance, with the following description, the inputs of RelaxedVariable1 are the revenue from every <product, customer> pair, instead of the revenue from the pairs with only products matching the product category of RelaxedVariable1.

In this other example, the inputs of RelaxedVariable2 are the revenue from every product, instead of the revenue from only the product of RelaxedVariable2 if the dimension was not relaxed.

Reference Disambiguation

Spaces may have several dimensions using the same category. Any reference to or from such space must explicitly state how dimensions should be mapped in order to avoid ambiguity. This is done by adding mapping after the reference to the state. A mapping is a list of:

on – list of categories in the referenced space the user wants to map
from – the prefix for the categories in the referencing space
to – the prefix for the categories in the referenced space

Where at least one of from or to must be specified.

Here is an example (that does not make real sense business-wise).

Configuration Engineer Knowledge Base

Variables Description