Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt

Use this file to discover all available pages before exploring further.

This page explains how to create multi-level simulation hierarchies using branch chaining. Branch chaining allows simulations to target non-master parent branches, enabling complex simulation scenarios where one simulation builds upon another.

​
What is branch chaining?

Branch chaining allows simulations to use any branch as a parent, not just the master branch. This creates a hierarchy of simulations where each simulation can build upon the results of a previous simulation. For example, in a financial risk analysis:
  • Simulation on branch A uses master as its parent and models a 2% interest rate increase.
  • Simulation on branch B uses branch A as its parent and adds a market volatility scenario.
  • Simulation on branch C uses branch B as its parent and applies portfolio adjustments.
This creates a chain: master → A → B → C.

​
How to create a branch chain

When creating a simulation, specify the parent branch in the simulation definition: 
IDatabaseSimulation simulation = new DatabaseSimulation();
simulation.setBranch("branch-b");
simulation.setParentBranch("branch-a");  // Use branch A as the parent
simulation.setSimulationName("Volatility scenario");
// Set other properties...

workflow.execute(simulation);
The workflow automatically validates the parent branch and creates the branch chain.

​
What happens during execution?

When a simulation is executed on a branch, the workflow performs these steps:
  1. Parent branch validation: If the target branch already exists with completed simulations, the workflow queries those simulations to determine the actual parent branch.
  2. Automatic correction: If the specified parent branch does not match the actual parent used by existing simulations on that branch, the workflow automatically corrects the parent branch reference. A warning is logged when this occurs.
  3. Branch creation: If the target branch does not exist, it is created using the specified parent branch. If the parent branch does not exist, the operation fails with a clear status instead of throwing an exception.
  4. Execution: The simulation executes on the target branch using the validated parent.

​
What are the edge cases?

The branch chaining implementation handles several edge cases:

​
Non-existent parent branch

Attempting to create a branch with a non-existent parent returns a failure status. The simulation status is set to FAILED and an error is logged with the branch name and parent branch name. 
// If parent-branch-x does not exist
simulation.setParentBranch("parent-branch-x");
workflow.execute(simulation);
// Result: simulation.getStatus() == DatabaseSimulationStatus.FAILED

​
Mismatched parent branch

When executing a simulation on an existing branch, if the specified parent does not match the parent used by other simulations on that branch, the parent is automatically corrected: 
// Branch B already has simulations with parent A
simulation.setBranch("branch-b");
simulation.setParentBranch("branch-x");  // Wrong parent
workflow.execute(simulation);
// Result: parent is corrected to branch A, warning logged

​
Parent branch deletion

Deleting a parent branch does not affect child branches. Child branches remain intact with their data preserved. Simulations on child branches continue to function normally. 
// Given: master → A → B
workflow.deleteBranch("branch-a");
// Result: Branch B still exists with all data intact

​
What are the consistency guarantees?

The workflow ensures branch chain consistency:
  • All simulations on a given branch share the same parent branch.
  • Parent branch references are validated and corrected automatically.
  • Branch creation failures are handled gracefully without exceptions.
  • Existing data is preserved when parent branches are deleted.

​
When to use branch chaining

Branch chaining is useful for scenarios that require:
  • Incremental simulations: Building scenarios layer by layer, where each layer depends on the previous one.
  • Comparative analysis: Creating multiple variations from a common baseline scenario.
  • Complex workflows: Modeling multi-step processes where each step modifies the output of the previous step.
  • Rollback points: Creating intermediate branches that serve as checkpoints for further experimentation.

​
Example workflow

Here is a complete example showing how to create a simulation chain: 
// Step 1: Create base scenario on branch A
IDatabaseSimulation simA = new DatabaseSimulation();
simA.setBranch("scenario-a");
simA.setParentBranch("master");
simA.setSimulationName("Base scenario");
workflow.execute(simA);

// Step 2: Create variant on branch B using A as parent
IDatabaseSimulation simB = new DatabaseSimulation();
simB.setBranch("scenario-b");
simB.setParentBranch("scenario-a");  // Chain from A
simB.setSimulationName("Variant 1");
workflow.execute(simB);

// Step 3: Create another variant on branch C using B as parent
IDatabaseSimulation simC = new DatabaseSimulation();
simC.setBranch("scenario-c");
simC.setParentBranch("scenario-b");  // Chain from B
simC.setSimulationName("Variant 2");
workflow.execute(simC);

// Result: master → scenario-a → scenario-b → scenario-c

​
How does branch chaining interact with permissions?

Branch permissions are inherited from the parent branch when a new branch is created. Users must have:
  • Read access to the parent branch to create a child branch.
  • Write access to the target branch to execute simulations.
See How are user permissions managed for more information about permission configuration.