simbiology-build-model

# Build SimBiology Models

API reference, helper functions, and patterns for building, modifying, and
diagramming SimBiology models. Works in all MATLAB environments (desktop,
headless, batch, remote). Diagram/layout features require the Model Builder
app and are activated only when the user requests visual output.

## When to Use

- Building or modifying SimBiology models (compartments, species, reactions, parameters, rules, events, doses, observables, variants)
- Opening, saving, or loading models in the Model Builder / Analyzer apps
- Designing or adjusting diagram layouts
- Keywords: "build", "create", "modify", "add compartment/species/reaction", "diagram", "layout"

## When NOT to Use

- Simulation and analysis (use `simbiology-simulate-model`)
- Parameter fitting, population modeling, NCA (use `simbiology-fit-model`)

## Must-Follow Rules

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

Run at the start of every session:
```matlab
addpath(fullfile('<WORKSPACE_ROOT>', '.claude', 'skills', 'simbiology-build-model', 'scripts'));
disp('Helper scripts added to path.')
```

### 2. Only open the Builder when needed

Do NOT open the Model Builder by default. Open it when:
- The user explicitly requests a diagram, layout, or visual
- The input is an `.sbproj` file — use `loadViaBuilder` to preserve
  diagram layout/styling (`sbioloadproject` loses this data)

A model is fully functional without a diagram — it can be simulated,
fitted, and analyzed using only the model object on `sbioroot`.

### 3. Model construction uses standard SimBiology API

Build models using `addcompartment`, `addspecies`, `addreaction`, etc.
directly. This works in all environments: desktop, headless, batch, remote.

```matlab
model = sbiomodel('MyModel'); disp(model.uuid)
comp = addcompartment(model, 'Central', 1);
addspecies(comp, 'Drug', 100);
addparameter(model, 'ke', 0.1);
rx = addreaction(model, 'Central.Drug -> null');
kl = addkineticlaw(rx, 'MassAction');
kl.ParameterVariableNames = {'ke'};
```

For **standard PK models** (1- or 2-compartment with standard dosing and
elimination), use `references/pk-library-guidance.md` as the reference for
correct parameterization, naming, and rules. When no diagram is needed,
call `PKModelDesign` directly. When the user requests a diagram, construct
the model manually following the same PK library conventions but use
`addAndPositionCompartment` for layout control (see Rule 8b).

### 4. Write reactions in the biological forward direction

The diagram renders **arrows on products** and **plain lines on reactants**
(based on the forward direction of the reaction string). Writing a reaction
backwards produces incorrect arrows even if the kinetics are equivalent.

```matlab
% CORRECT — L and R get plain lines, C gets an arrow
addreaction(model, 'cell.L + cell.R <-> cell.C');

% WRONG — same kinetics but L and R get arrows (they're "products" now)
addreaction(model, 'cell.C <-> cell.L + cell.R');
```

Guidelines:
- **Binding:** write `A + B -> C` (substrates on left, complex on right)
- **Degradation/elimination:** write `Drug -> null` (not `null -> Drug`)
- **Synthesis:** write `null -> mRNA` (not `mRNA -> null`)
- **Transport:** write `Source.Drug -> Dest.Drug` (source on left)

### 5. Always use qualified names for species and reaction-scoped parameters

Always reference species and reaction-scoped parameters by their **qualified name**. If any of the names are not valid MATLAB variable names, surround them with square brackets before building the qualified name.

- **Species:** `CompartmentName.SpeciesName` (e.g., `Central.Drug`, `Peripheral.[Drug-bound]`)
- **Reaction-scoped parameters:** `ReactionName.ParameterName` (e.g., `Elimination.ke`)

**Qualification is always exactly one level deep** — the immediate parent
compartment only. Multi-level paths like `Body.Central.Drug` are **invalid**
in reaction strings. This is never ambiguous because compartment names must
be globally unique across the entire model (SimBiology enforces this
regardless of nesting depth). So `Central.Drug` is always sufficient.

**Compartment naming rules:**
- Names must be unique across the entire model — no two compartments can
  share a name even at different nesting levels
- If you need hierarchical naming, use underscores: `Body_Central` (not
  nested compartments both named `Central`)
- Species names must be unique within a compartment but can repeat across
  different compartments (disambiguated by `Compartment.Species`)

### 6. Use modern property names (`Value`, `Units`, `Constant`)

SimBiology objects (species, compartments, parameters) share a unified
property interface. Always use the modern names:

| Modern | Deprecated (do NOT use) | Applies to |
|--------|------------------------|------------|
| `Value` | `InitialAmount`, `Capacity` | species, compartments, parameters |
| `Units` | `InitialAmountUnits`, `CapacityUnits`, `ValueUnits` | species, compartments, parameters |
| `Constant` | `ConstantAmount`, `ConstantCapacity`, `ConstantValue` | species, compartments, parameters |

```matlab
sp.Value = 100;       % NOT sp.InitialAmount
sp.Units = 'milligram';  % NOT sp.InitialAmountUnits
sp.Constant = false;  % NOT sp.ConstantAmount

comp.Value = 1;       % NOT comp.Capacity
comp.Units = 'liter'; % NOT comp.CapacityUnits
comp.Constant = true; % NOT comp.ConstantCapacity

p.Value = 0.1;        % NOT redundant, but never use p.ValueUnits or p.ConstantValue
p.Units = '1/hour';
p.Constant = true;
```
### 7. Close Builder and Analyzer before `sbioreset`

`sbioreset` does NOT close these apps, leaving orphaned windows:
```matlab
try mb = SimBiology.web.desktophandler.getModelBuilder();
    if ~isempty(mb) && isfield(mb,'webWindow') && isvalid(mb.webWindow), mb.webWindow.close(); end
catch, end
try ma = SimBiology.web.desktophandler.getModelAnalyzer();
    if ~isempty(ma) && isfield(ma,'webWindow') && isvalid(ma.webWindow), ma.webWindow.close(); end
catch, end
pause(1); sbioreset;
```
### 8. D