Compose Models

Build a lab by combining models into a single runnable graph.

Time estimate: 20 minutes

Goal

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

• Understand how labs combine one or more models
• Add models to a lab
• Connect exposed inputs and outputs
• Save and run the resulting lab

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

The Lab Editor

Open or create a lab to work on its graph.

Graph Canvas

The main area 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 Picker

Browse and search for models to add to your lab.

Side Panel

Review the selected model, connection, or lab settings.

Building a Lab

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

Step 4: Save the Lab

1. Give the lab a title
2. Add a short description
3. Save it so you can rerun or publish it later

Example: Two Connected Models

Create a simple lab with a source model feeding a downstream model:

Add Models

1. Search for the first model you want to use
2. Add two instances to the canvas
3. Arrange them side by side

Connect

1. Connect an output on the first model to a compatible input on the second
2. Verify the connection appears in the graph

If your workflow needs feedback or nested labs, add those only after the basic forward path is working.

Configure

1. Select each model and review its default parameters
2. Save the lab
3. Start a run to verify the graph is valid

Run

1. Click Start Run
2. Set duration and output settings
3. Inspect the outputs in the results view

Running Compositions

Simulation Settings

Labs usually expose the same run settings as any other run:

Performance

Larger labs may take longer. Tips:

• Reduce output points
• Start from a smaller graph first
• Validate each added model before growing the lab

Saving Labs

1. Click Save
2. Name your lab
3. Add description and tags
4. Share it with collaborators if your account has that capability

Saved labs appear in your labs list.

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. Keep a clean lab title: You will likely rerun it and revisit it later

Troubleshooting

Connection Not Allowed

• Check data types match
• Verify dimensions are compatible
• Verify the source output and destination input are the right pair

Simulation Fails

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

Unexpected Results

• Verify connection directions
• Run models individually to isolate issues

Next Steps

• Biosimulant Library - Create compositions with Python