matlab-simulate-simbiology-model

# Simulate SimBiology Models

Run simulations of SimBiology models: deterministic ODE, stochastic SSA,
scenario exploration, and sensitivity analysis.

## When to Use

- "simulate", "run", "predict" model behavior
- "what if" / "what happens if" (implies simulation or scenarios)
- Time-course results from a model
- Dose-response studies, parameter sweeps, factorial designs
- Stochastic, SSA, Gillespie, noise, gene expression variability
- "which parameters matter most", sensitivity, Sobol, Morris
- Keywords: "simulate", "run", "predict", "what-if", "stochastic", "sensitivity"

## When NOT to Use

- Model construction or diagram layout (use `matlab-build-simbiology-model`)
- Parameter estimation from data (use `matlab-fit-simbiology-model`)
- NCA / AUC / Cmax from data (use `matlab-fit-simbiology-model`)

## Must-Follow Rules

### 0. Add helper scripts to the MATLAB path first

Run at the start of every session:
```matlab
addpath(fullfile('<WORKSPACE_ROOT>', '.claude', 'skills', 'matlab-simulate-simbiology-model', 'scripts'));
```

### 1. Element-wise operators in observables

Use `./` and `.*` (element-wise) in observable expressions when mixing
time-varying species with constant parameters. Plain `/` and `*` cause
size mismatches at simulation time.

### 2. StatesToLog for constant parameters

When observables reference constant parameters (e.g., `Drug ./ Vd`),
add those parameters explicitly to `StatesToLog`:
```matlab
cs.RuntimeOptions.StatesToLog = [m.Species; sbioselect(m,'Type','parameter','Name','Vd')];
```
`StatesToLog = 'all'` does **not** log constant compartments or parameters.

### 3. All reactions must be MassAction for SSA

The stochastic solver does not support custom rate expressions. Every
reaction must use `addkineticlaw(rx, 'MassAction')`.

### 4. Do NOT combine Scenarios with `+`

The `+` operator is not supported on `SimBiology.Scenarios` objects.
Always use `add()` to append entries.

### 5. Reset local sensitivity options after use

Local sensitivity settings persist on the configset and affect
subsequent simulations. Always reset:
```matlab
cs.SolverOptions.SensitivityAnalysis = false;
cs.SensitivityAnalysisOptions.Inputs = [];
cs.SensitivityAnalysisOptions.Outputs = [];
```

### 6. Set `MaximumWallClock` to prevent hung simulations

When fitting or scanning, bad parameter values can make individual
simulations extremely slow. Protect against this:
```matlab
cs.MaximumWallClock = 60;  % seconds; default is Inf
```
This is a **configset** property (not a solver or optimizer option).
It stops any single simulation that exceeds the wall clock limit.

### 7. Unit conversion requires `TimeUnits`

When `cs.CompileOptions.UnitConversion = true`, you MUST also set
`cs.TimeUnits` to match your StopTime units (e.g., `'hour'`).
Otherwise SimBiology defaults to seconds and your 24-unit simulation
covers 24 seconds, not 24 hours:
```matlab
cs.CompileOptions.UnitConversion = true;
cs.TimeUnits = 'hour';
cs.StopTime = 24;  % now correctly 24 hours
```

### 8. Scenario results are interleaved, not blocked

Factorial scenario results come back interleaved by the first dimension.
Always use `generate(sc)` to map result indices to conditions — never
assume all entries of one factor appear consecutively.

## Decision Table

| Scenario | Approach |
|----------|----------|
| One-off simulation | `sbiosimulate` |
| Parameter sweep / Monte Carlo | `createSimFunction` |
| Dose/variant/parameter what-if | `SimBiology.Scenarios` + `createSimFunction` |
| Low molecule count / noise | SSA solver (`cs.SolverType = 'ssa'`) |
| Which parameters matter? | `sbiosobol` (Sobol) or `sbioelementaryeffects` (Morris) |
| Quick sensitivity check | Local sensitivity via configset |

## Basic Simulation (`sbiosimulate`)

Prefer returning **SimData** (single output) — it carries state names,
units, and metadata, and works directly with `sbioplot` and `selectbyname`:

```matlab
m = getModelByUUID(modelId);
cs = getconfigset(m, 'active');
cs.StopTime = 24;
cs.SolverType = 'ode15s';
simData = sbiosimulate(m);
```

With a dose:
```matlab
d = sbiodose('Bolus', 'schedule');
d.TargetName = 'Drug'; d.Amount = 100; d.Time = 0;
simData = sbiosimulate(m, cs, d);
```

## Plotting Results

Use `sbioplot` for quick visualization of SimData:
```matlab
simData = sbiosimulate(m, cs, d);
sbioplot(simData);
```

For custom plots, extract numeric data first:
```matlab
[t, x, names] = getdata(simData);
plot(t, x);
legend(names, 'Interpreter', 'none');
xlabel('Time'); ylabel('Amount');
```

## Extracting State Data from SimData

Use `selectbyname` to extract specific states. It returns a **SimData
object**, not a numeric array — extract numeric data before doing math:
```matlab
simData = sbiosimulate(m, cs, d);
result = selectbyname(simData, 'Central.Drug');  % returns SimData, NOT double
drugData = result.Data;   % numeric column vector
drugTime = result.Time;   % time column vector
```

Or use `getdata()` to get arrays:
```matlab
[t, x, names] = getdata(selectbyname(simData, 'Central.Drug'));
```

For quick numeric access to all states without SimData, use the
three-output form:
```matlab
[t, x, names] = sbiosimulate(m, cs, d);  % t, x are double arrays directly
```

## Repeated Simulation (`createSimFunction`)

```matlab
% Signature: createSimFunction(model, params, observables, dosedSpecies)
simfun = createSimFunction(model, {'ke','ka'}, {'Drug'}, []);
r1 = simfun([0.1, 0.5], 24);           % single run
r2 = simfun([0.1, 0.5; 0.3, 1.0], 24); % multiple parameter sets (rows)
[t, x] = r1.getdata();
```

- Compiles once, runs many — much faster than `sbiosimulate` in a loop
- **Exception:** SSA (stochastic) requires `sbiosimulate` in a loop because each run needs fresh random state; `createSimFunction` does not support stochastic solvers
- Compatible with `parfor` (Parallel Computing Toolbox)
- Returns `SimData` objects; use `.getdata()` to extract arrays

### SimFunction with doses

The 4th argument to `createSimFunction` dec