Build and Use Parallel Calculation

Parallel Calculation is a special kind of model calculations that is executed in a 3-step fashion and is mainly used to implement use cases where it is required to calculate many independent items in parallel. In practice, those items are calculated in a distributed manner.

The most visible example of such a calculation is in the Negotiation Guidance Model Class which builds a segmentation tree and then calculates each of the segments in parallel.

See Model Parallel Calculation Logic , Model Class (MC) | Parallel Calculation Fields and Model Object (MO) | Calculation Items for technical details about this feature.

Here we are going to look at a simplified example of a one-step Model Class with a parallel calculation that:

Creates a few items
Calculates for each a simple arithmetic expression
Summarizes it by computing the sum of the outputs

Sample Model Class

{
  "uniqueName": "POAI_Sample_Parallel",
  "definition": {
    "calculations": [
      {
        "name": "calc",
        "type": "parallel",
        "formulaName": "POAI_Sample_Parallel_Calc"
      }
    ],
    "steps": [
      {
        "name": "step",
        "label": "Main",
        "calculation": "calc",
        "tabs": [
          {
            "name": "tab",
            "label": "Results",
            "type": "dashboard",
            "formulaName": "POAI_Sample_Parallel_Eval"
          }
        ]
      }
    ]
  }
}

The POAI_Sample_Parallel_Calc logic will be of Nature model_parallel_calculation and each of its elements will be associated to one of the three available contexts: Init, Item or Summary.

The POAI_Sample_Parallel_Eval logic will be of Nature model_evaluation.

Calculation Logic

Creating Items, Init Context

Element Initialisation of POAI_Sample_Parallel_Calc:

(1..10).forEach {
  // Keys of the form k01, k02, etc
  def itemKey = 'k' + it.toString().padLeft(2, '0')
  def itemInputs = [
    theValue: it
  ]
  model.addCalculationItem(itemKey, itemInputs)
}

When the calculation is executed, all the elements associated to the Init context will be executed once. In this case it means that at the end of this (first out of three) steps of the parallel calculation, 10 items will be created and attached to the calculation for parallel calculation.

Each item starts with the status CREATED, a key that must be unique for the set of inputs provided.

Calculating Items, Item Context

Element Item of POAI_Sample_Parallel_Calc:

def item = model.calculationItem()

api.logInfo("Processing ", item.key())

def value = item.inputs().theValue as int

return value * 2

When the calculation is executed, each item created will have the elements associated to the Item context be executed. In this case it means that for each of the 10 created items in the Init context, the code above will be executed and the Item element output will be the item’s associated value (theValue) multiplied by two.

For parallel calculations to work correctly, it is important to ensure that the calculation of each item is always idempotent because, by design, items are meant to be calculable multiple times (e.g., in case of infrastructure errors, but also if the user decides to recalculate some items). In practical terms, this means that the parallel calculation logic elements of Item context should be careful when mutating external state, and in particular when using model.loadTable. For example, a typical use case is to load new rows in a Model Table for each item and calculating multiple times the same item should not add more rows but overwrite existing ones: usually the simplest way of enforcing this is to ensure that the tables where the items are loaded are using keys that match unique criteria of the items.

Summarizing Items, Summary Context

Element Summary of POAI_Sample_Parallel_Calc:

When the calculation is executed, after all items have been calculated, the elements associated to the Summary context are executed once. In this case it means that the code above will retrieve the output of the calculation of each item and do a sum over all of them.

Evaluation Logic

Element Result of POAI_Sample_Parallel_Eval:

After the calculation is executed, the UI will show the tabs of the step, and thus the evaluation result of this logic.

As we can see, it is possible to access the outputs of the calculation using model.outputs().

The Calculation Items are considered as part of the internal state of the Parallel Calculation, and thus it is not possible to access the results of each of the items. It is the responsibility of the Summary context of a Parallel Calculation to prepare results and data (e.g., in model tables) from the items. This behavior promotes decoupling between implementation details of calculations and other logics used in a Model Class.

Executing and Exploring Results

After deploying this Model Class and associated logic, we can create a new Model Object in the UI:

We can see in Calculation Tracking that there is only one calculation being executed:

Once this is done, we can go into the details of the job to get more information:

In particular we can see the result of the Summary step.

Then going into the Calculation Items page, we can see the detail of each and every item in the same manner:

In particular we can see the result of this specific item.

If needed, you can also recalculate just specific items (manually selected or filtered out).