---

name: simbiology-build-model description: "Build, modify, and diagram SimBiology models — API reference, helper functions, and layout patterns. Use when constructing or editing models programmatically or visually." license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "2.0"

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:

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.

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.

% 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 |

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:

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. Diagram rules (only when user requests a diagram)

The following rules apply ONLY when the user asks for a diagram or layout. Skip all of these for pure model construction.

Model size limit (precondition): Layout helpers bail out above 400 total blocks (species + reactions). For large models, skip automated layout — use simple grid positioning instead (reactions at midpoints of connected species).

a. Use addAndPositionCompartment for diagram layout

When building a diagram, use addAndPositionCompartment instead of raw addcompartment + setBlock — it atomically creates, positions, and validates each compartment.

% speciesInfo: cell array of structs with .Name, .Value, .Position
speciesInfo = {
    struct('Name', 'Drug', 'Value', 100, 'Position', [40, 30, 50, 16]);
    struct('Name', 'DrugBound', 'Value', 0, 'Position', [140, 30, 100, 16])
};
[comp, sp] = addAndPositionCompartment(model, 'Central', 1, [20, 20, 280, 80], speciesInfo);
% sp is a SimBiology Species ARRAY — index with sp(1), sp(2), NOT sp{1}

b. Diagram build order

1. Open the Builder first — the diagram does not exist until the Builder creates it. All simbio.diagram.* calls and addAndPositionCompartment will fail without this step.
2. Plan [x y w h] positions for ALL compartments up front (leave 80 px gaps minimum)
3. Build ONE compartment at a time with addAndPositionCompartment
4. Add ALL parameters (including rule LHS targets), reactions, rules, doses, events
5. repositionAllReactions(model) then checkDiagramLayout(model) — fix until zero violations
6. positionAncillaryBlocks(model) — positions rule/parameter blocks in a grid to the right

c. Leave 80 px gaps between connected compartments

Inter-compartment reaction nodes (15×15) are placed in these gaps by repositionAllReactions. Without adequate gaps, reaction lines cross through compartment blocks. For compartments with many shared reactions (3+), increase to 120 px.

d. Post-placement validation is mandatory

After placing all blocks:

repositionAllReactions(model);
results = checkDiagramLayout(model);
if results.nTotal > 0
    for i = 1:numel(model.Reactions)
        pos = computeSafeReactionPosition(model, model.Reactions(i));
        simbio.diagram.setBlock(model.Reactions(i), 'Position', pos);
    end
    results = checkDiagramLayout(model);
end
positionAncillaryBlocks(model);  % must run LAST, after all objects exist

e. Always use the safe-open pattern for the Builder

Never call simBiologyModelBuilder(model) without first checking isAppOpen('builder'). If open, close it, wait 2s, then reopen.

if isAppOpen('builder')
    try
        mb = SimBiology.web.desktophandler.getModelBuilder();
        if ~isempty(mb) && isfield(mb, 'webWindow') && isvalid(mb.webWindow)
            mb.webWindow.close();
        end
    catch, end
    pause(2);
end
% If Analyzer is open, it already has a model loaded — open Builder
% without an argument so it picks up the Analyzer's active model.
% Passing a model argument when Analyzer is open can cause conflicts.
if isAppOpen('analyzer')
    simBiologyModelBuilder();
else
    simBiologyModelBuilder(model);
end

f. Never close the Builder to make modifications

The model handle is on sbioroot — all code works on the live model and updates the diagram in real time. Only close when the user explicitly asks.

Helper Functions (scripts/)

Model construction (always available)

| Function | Signature | Purpose | |----------|-----------|---------| | getModelByUUID | model = getModelByUUID(uuid) | Look up model by UUID |

Diagram & Builder (only when user requests diagram/layout)

| Function | Signature | Purpose | |----------|-----------|---------| | addAndPositionCompartment | [comp,sp] = addAndPositionCompartment(model,name,cap,compPos,speciesInfo,Name=Value) | Create compartment + species and position atomically. sp is a Species array — index with sp(1), NOT sp{1}. Options: FontWeight ("bold"), TextLocation ("center"), Padding (20), AutoExpand (true), AutoFixPositions (true) | | checkDiagramLayout | results = checkDiagramLayout(model) | Containment + line-through-block + overlap checks | | computeSafeReactionPosition | pos = computeSafeReactionPosition(model,rxn) | Crossing-free reaction node position | | repositionAllReactions | nFixed = repositionAllReactions(model) | Batch-reposition all reactions (up to 3 passes) | | positionAncillaryBlocks | n = positionAncillaryBlocks(model) | Grid-position rule/parameter blocks to the right of compartments | | openLiveBuilder | openLiveBuilder(model) | Open Builder with safe-open pattern | | isAppOpen | tf = isAppOpen(appName) | Check if Builder/Analyzer is open | | loadViaBuilder | model = loadViaBuilder(filePath) | Load .sbproj preserving diagram | | saveViaBuilder | saveViaBuilder(filePath) | Save from Builder preserving diagram | | lineIntersectsRect | hit = lineIntersectsRect(x1,y1,x2,y2,rect) | Shared geometry helper (used internally by layout scripts) |

checkDiagramLayout output

results.nTotal        % total violations (must be 0 before presenting)
results.nContainment  % species outside parent compartment
results.nLineThrough  % connection lines through unrelated blocks
results.nOverlap      % blocks <10px apart

API Quick Reference

Model

• sbiomodel(name) — create model; model.uuid — unique ID
• sbioloadproject('file.sbproj') — returns a struct with the model name as field; extract dynamically:

  proj = sbi