GuidesCompose Models

Compose Models

Combine multiple models into complex multi-scale simulations.

Time estimate: 20 minutes

Goal

By the end of this tutorial, you’ll be able to:

  • Understand model composition concepts
  • Create a composition from multiple models
  • Connect model inputs and outputs
  • Run and analyze composed simulations

What is Model Composition?

Model composition allows you to:

  • Connect models: Link outputs of one model to inputs of another
  • Multi-scale simulation: Combine molecular, cellular, and tissue-level models
  • Modular design: Reuse validated models as building blocks
  • Complex systems: Model interactions between subsystems

Model composition is an advanced feature. We recommend completing the basic tutorials first.

The Composition Editor

Navigate to Compose in the main navigation to open the composition editor.

Canvas

The main workspace where you arrange and connect models.

  • Drag models from the library onto the canvas
  • Connect ports by dragging from output to input
  • Select models to configure properties
  • Pan and zoom to navigate large compositions

Model Library

Browse and search for models to add to your composition.

Properties Panel

View and edit properties of selected models or connections.

Creating a Composition

Step 1: Add Models

  1. Search for your first model in the library
  2. Drag it onto the canvas
  3. Repeat for additional models

Step 2: Understand Ports

Each model has:

  • Input ports (left side): Accept data from other models
  • Output ports (right side): Provide data to other models

Hover over a port to see its name and data type.

Step 3: Connect Models

  1. Click and drag from an output port
  2. Drop onto a compatible input port
  3. A connection line appears
⚠️

Only compatible ports can be connected (matching data types and dimensions).

Step 4: Configure Connections

Click on a connection to set:

  • Mapping: How values are transformed
  • Time delay: If outputs should be delayed
  • Aggregation: How to combine multiple sources

Example: Coupled Oscillators

Let’s create a simple composition with two oscillator models:

Add Models

  1. Search for “oscillator” in the library
  2. Add two instances to the canvas
  3. Arrange them side by side

Connect

  1. Connect oscillator_1.output to oscillator_2.input
  2. Connect oscillator_2.output to oscillator_1.input

This creates a feedback loop between the oscillators.

Configure

  1. Select oscillator_1 and set initial conditions
  2. Select oscillator_2 and set different initial conditions
  3. Adjust connection strengths as needed

Run

  1. Click Run Composition
  2. Set duration and output settings
  3. View synchronized (or chaotic) oscillations!

Advanced Features

Subcompositions

Group multiple connected models into a reusable subcomposition:

  1. Select multiple models
  2. Right-click → Create Subcomposition
  3. Name your subcomposition
  4. Reuse in other compositions

Parameter Sharing

Share parameter values across models:

  1. Select models that should share a parameter
  2. Right-click → Link Parameters
  3. Changing one updates all linked parameters

Conditional Connections

Control when data flows between models:

  1. Click a connection
  2. Enable Conditional
  3. Set condition (e.g., time > 50)

Time Scaling

Handle models with different time scales:

  1. Select a model
  2. Set Time Scale Factor
  3. Values > 1 slow down the model
  4. Values < 1 speed up the model

Running Compositions

Simulation Settings

Compositions have additional settings:

SettingDescription
Global DurationTotal simulation time
Sync PointsWhen models exchange data
Integration MethodAlgorithm for solving
Error ToleranceAccuracy vs. speed tradeoff

Execution Order

The system automatically determines execution order based on connections. For cycles (feedback loops), it uses iterative solving.

Performance

Complex compositions may take longer. Tips:

  • Reduce output points
  • Increase sync point interval
  • Use simpler models where possible

Saving Compositions

  1. Click Save
  2. Name your composition
  3. Add description and tags
  4. Share with collaborators (optional)

Compositions appear in your Projects dashboard.

Best Practices

  1. Start simple: Begin with two models before adding more
  2. Validate components: Run individual models first
  3. Document connections: Add notes explaining the biology
  4. Test incrementally: Add one model at a time, verify each step
  5. Use version control: Save versions as you develop

Troubleshooting

Connection Not Allowed

  • Check data types match
  • Verify dimensions are compatible
  • Ensure no circular dependencies (unless intended)

Simulation Fails

  • Check for numerical instability
  • Reduce time step
  • Verify parameter values are valid

Unexpected Results

  • Verify connection directions
  • Check parameter sharing
  • Run models individually to isolate issues

Next Steps

Analyze ResultsOverview