matlab-build-simbiology-model

name	matlab-build-simbiology-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	MathWorks BSD-3-Clause
metadata	{"author":"MathWorks","version":"1.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 matlab-simulate-simbiology-model)
• Parameter fitting, population modeling, NCA (use matlab-fit-simbiology-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', 'matlab-build-simbiology-model', 'scripts'));
disp('Helper scripts added to path.')

2. Only open the Builder when the user wants a diagram

Do NOT open the Model Builder by default. Only open it when the user explicitly requests a diagram, layout, or visual (e.g., "show me the diagram", "lay out the model", "open the Builder").

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), prefer PKModelDesign — it produces models consistent with the PK library (correct parameterization, naming, rules). See references/pk-library-guidance.md.

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.

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);

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 reactions, parameters, rules, doses after all compartments exist
5. repositionAllReactions(model) then checkDiagramLayout(model) — fix until zero violations

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

Model size limit for layout helpers: The layout scripts (checkDiagramLayout, computeSafeReactionPosition, repositionAllReactions) have O(n²) to O(n⁴) complexity and bail out with a warning if the model exceeds 400 total blocks (species + reactions). For models with more than ~200 species or ~200 reactions, skip automated layout validation — use simple grid-based positioning instead (place reactions at midpoints of their connected species without the crossing-avoidance search).

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 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. 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)
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 = sbioloadproject('file.sbproj');
  fn = fieldnames(proj);
  model = proj.(fn{1});
  

• copyobj(model) — deep clone; verify(model) — check consistency
• sbioreset — clear all models (close apps first!)

Compartments

• addcompartment(model, name, capacity)
• comp.Value, comp.Constant, comp.Units, model.Compartments

Species

• addspecies(comp, name, initialValue)
• sp.Value, sp.Units, sp.BoundaryCondition, sp.Constant
• sp.Parent.Name — parent compartment; model.Species

Parameters

• addparameter(model, name, value) — model-scoped
• addparameter(kineticLaw, name, value) — reaction-scoped
• p.Value, p.Units, p.Constant, model.Parameters

Reactions

• addreaction(model, 'A -> B') — forward; 'A <-> B' — reversible
• addkineticlaw(rx, 'MassAction') then kl.ParameterVariableNames = {'k1'}
• rx.ReactionRate = 'k1*A' — custom rate (no kinetic law needed)
• Multi-compartment: 'Central.Drug -> Peripheral.Drug'

Rules, Events, Doses

• addrule(model, 'x = expr', ruleType) — 'initialAssignment', 'repeatedAssignment', 'rate'
• addevent(model, 'time >= 10', {'Drug = 50'})
• sbiodose(name, 'schedule') / sbiodose(name, 'repeat')
• Schedule: .TargetName, .Amount, .Time, .Rate
• Repeat: .TargetName, .Amount, .StartTime, .Interval, .RepeatCount
• adddose(model, d) / removedose(model, d)

Observables & Variants

• addobservable(model, name, expression) — use ./ and .* for element-wise ops
• StatesToLog caveat: If the observable references a constant parameter (e.g., 'Drug ./ Vd'), add that parameter to StatesToLog — otherwise it logs as NaN. Observables themselves are auto-logged when their dependencies are present (do NOT add observables to StatesToLog — it only accepts species, parameters, and compartments).
• addvariant(model, name) + addcontent(v, {'type','name','prop',val})
• v.Content, getvariant(model, name)

Simulation Config

• cs = getconfigset(model, 'active')
• cs.StopTime, cs.SolverType ('ode15s', 'ode45', 'sundials')
• cs.RuntimeOptions.StatesToLog — 'all' or handle array

Selection

• sbioselect(model, 'Type', type, 'Name', name)
• For reactions: use 'Reaction' property (not 'Name')

Core Patterns

Model creation (standard — no diagram)

model = sbiomodel('MyModel');
disp(model.uuid)
comp = addcompartment(model, 'Central', 1);
addspecies(comp, 'Drug', 100);
addparameter(model, 'ke', 0.1);

Reactions

% MassAction (always use qualified species names)
rx = addreaction(model, 'Central.Drug -> null');
kl = addkineticlaw(rx, 'MassAction');
kl.ParameterVariableNames = {'ke'};

% Custom rate
rx = addreaction(model, 'Central.E + Central.S <-> Central.ES');
rx.ReactionRate = 'kf*Central.E*Central.S - kr*Central.ES';

% Multi-compartment transfer
rx = addreaction(model, 'Central.Drug -> Peripheral.Drug');

% Species with invalid MATLAB variable names
rx = addreaction(model, 'Central.[Drug-bound] -> Central.[Drug-free]');

Removing components

delete(sbioselect(model, 'Type', 'species', 'Name', 'Drug'));
delete(sbioselect(model, 'Type', 'reaction', 'Reaction', 'Drug -> null'));
removedose(model, model.Doses(1));  % doses use removedose, not delete

Doses

% Bolus
d = sbiodose('Dose', 'schedule');
d.TargetName = 'Drug'; d.Amount = 100; d.Time = 0;
adddose(model, d);

% Repeat dose
d = sbiodose('RepeatDose', 'repeat');
d.TargetName = 'Drug'; d.Amount = 50;
d.StartTime = 0; d.Interval = 8; d.RepeatCount = 3;
adddose(model, d);

Events, variants, observables

ev = addevent(model, 'time >= 10', {'Drug = 50'}); ev.Name = 'RescueDose';
v = addvariant(model, 'HighDose'); addcontent(v, {'parameter','ke','Value',0.5});
obs = addobservable(model, 'DrugConc', 'Drug ./ Central');

Saving Models

Standard save (no diagram required)

Save models to .mat files using standard MATLAB save/load. Do NOT use sbiosaveproject — it requires base workspace hacks and is deprecated in favor of .mat:

save('mymodel.mat', 'model');          % save model
save('session.mat', 'model', 'dose');  % save model + dose together

To reload:

loaded = load('mymodel.mat');
model = loaded.model;

Save/Load with diagram preservation (requires Builder)

Method	Preserves Diagram?	Requires Builder?
saveViaBuilder(path)	Yes	Yes
loadViaBuilder(path)	Yes	Yes
save(path, 'model') (.mat)	No	No
sbioloadproject -> simBiologyModelBuilder(model)	No	No

Switching models in the Builder

1. Ask user if they want to save first
2. If yes: saveViaBuilder('name.sbproj')
3. Close: mb.webWindow.close(); pause(2);
4. Reopen: simBiologyModelBuilder(newModel);

Diagram Basics (only when user requests diagram/layout)

Coordinate system

Position = [x y width height] where (x, y) is top-left corner.

Standard block sizes

Block Type	Default Size	Notes
Species	[50, 16]	Scale width: <=5 chars → 50, 6-12 → 100, 13+ → 130
Reaction	[15, 15]
Rule	[20, 20]

Compartment sizing from content

Species Count	Size	Notes
1	160 x 100	Single species, centered
2 (isolated)	240 x 170	Vertically stacked
2 (in chain)	400 x 100	Side by side
3-5	160+n*50 x 100+n*35	Scale to content
6+	240+n*50 x 220+n*35	Row layout, multiple rows if needed

Internal padding: 30 px minimum on all sides.

Row-based species placement (3+ species)

species = comp.Species;
n = numel(species);
spWidth = 50;  % scale per name length: <=5→50, 6-12→100, 13+→130
margin = 40;   % intra-compartment margin from edges
spacing = (width - 2*margin - spWidth) / max(n-1, 1);
for i = 1:n
    sx = x + margin + (i-1)*spacing;
    sy = y + height/2 - 8;
    simbio.diagram.setBlock(species(i), 'Position', [round(sx) round(sy) spWidth 16]);
end

Layout rules

Hard requirements:

1. No block overlap (except species inside compartments)
2. Labels visible — not overlapping other blocks
3. Horizontal/vertical alignment for same-tier compartments
4. Inter-compartment reactions outside both compartments (in the gap)
5. No connection lines through unrelated blocks
6. 50 px minimum reaction-to-species distance

Preferred placement: 7. Elimination/degradation reactions inside their parent compartment (communicates the process occurs locally, not across a boundary)

Flow direction by model type

Model Type	Flow Direction
PKPD	PD upper-left, PK lower-right
Metabolic	Top-to-bottom
PBPK	Circulation-based columns
Simple PK	Left-to-right or diagonal

References

Load on demand for detailed guidance:

• references/layout-strategy-guidance.md — strategy selection, pre-build checklist, 7 recipes
• references/pbpk-layout-guidance.md — PBPK circulation and ACAT chain layouts
• references/evacuation-procedure-guidance.md — 5-phase rearrangement for existing models
• references/api-cheatsheet-guidance.md — full simbio.diagram API (getBlock, setBlock, lines, clones)
• references/app-lifecycle-guidance.md — switching models, Analyzer coordination
• references/diagram-styling-guidance.md — colors, fonts, cloning mechanics
• references/pk-library-guidance.md — PKModelDesign for standard PK models

---

Copyright 2026 The MathWorks, Inc.

---