<!-- Source: https://docs.biosimulant.com/how-to/web/run-simulation -->

# Run a Simulation

Configure and execute simulations with custom parameters.

**Time estimate**: 15 minutes

## Goal

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

- Configure simulation time settings
- Modify initial conditions and parameters
- Monitor simulation progress
- Handle common simulation issues

## Starting a Run

From any model detail page or lab page:

1. Open the lab you want to run
2. Open the run configuration panel
3. Configure settings (see below)
4. Click **Start Run**

## Configuration Options

### Time Settings

| Setting | Description | Example |
|---------|-------------|---------|
| **Duration** | Total simulation time | 100 seconds |
| **Output Points** | Number of data points returned | 500 |
| **Start Time** | When to begin recording | 0 |

**Tip:**

  More output points = smoother plots but larger data files. 500-1000 is usually sufficient.

### Initial Conditions

Override the default starting values for supported model inputs:

```yaml
# Example
prey: 100 → 150
predator: 10 → 20
```

Use the form fields exposed by the lab or model package.

### Parameter Overrides

Modify model parameters without editing the model:

```yaml
# Example
alpha: 1.0 → 1.5
beta: 0.1 → 0.08
```

**Warning:**

  Invalid parameter values may cause simulation failures. Check parameter bounds in model documentation.

### Remote Size

For labs that require a GPU-backed remote size, Biosimulant automatically disables CPU-only sizes and blocks incompatible remote submissions before the run starts.

## Monitoring Progress

After starting a run:

1. **Status indicator** shows current state:
   - 🟡 Queued
   - 🔵 Running
   - 🟢 Completed
   - 🔴 Failed

2. **Progress and logs** may be shown while the run is active, depending on your account or workspace

## Run States

| State | Description | Action |
|-------|-------------|--------|
| **Queued** | Waiting in job queue | Wait |
| **Running** | Simulation executing | Wait |
| **Completed** | Results available | View Results |
| **Failed** | Error occurred | Check error message |
| **Cancelled** | User cancelled | Start new run |

## Handling Failures

### Common Error: Numerical Instability

**Symptoms**: "Integration failed" or "NaN values"

**Solutions**:
- Reduce simulation duration
- Decrease output points
- Check for extreme parameter values
- Use a different integration method (if available)

### Common Error: Timeout

**Symptoms**: "Simulation timed out"

**Solutions**:
- Reduce duration or complexity
- Break into smaller runs
- Contact support for long-running simulations

### Common Error: Invalid Parameters

**Symptoms**: "Parameter out of bounds"

**Solutions**:
- Check parameter constraints in model documentation
- Reset to default values
- Use biologically reasonable values

## Repeating a Run

The most reliable way to compare scenarios is:

1. Start from the same lab
2. Change one parameter or configuration block
3. Start a new run
4. Compare the finished runs in the results view

## Best Practices

1. **Start simple**: Run with defaults first, then modify
2. **Document changes**: Note which parameters you changed
3. **Save configurations**: Bookmark configurations you use frequently
4. **Compare systematically**: Change one parameter at a time

## Programmatic Runs

For automation, use the desktop CLI for desktop-managed labs or the `Biosimulant` library for local Python workflows.

## Next Steps

- [Analyze Results](/how-to/web/analyze-results) - Visualize your simulation
- [Biosimulant Library](/references/library) - Automate simulations with Python