matlab-build-simbiology-model

SimBiology モデルの構築

SimBiology モデルの構築、変更、図示に関する API リファレンス、ヘルパー関数、パターンです。すべての MATLAB 環境（デスクトップ、ヘッドレス、バッチ、リモート）で動作します。図やレイアウトの機能には Model Builder アプリが必要で、ユーザーが視覚的な出力を要求した場合にのみ有効になります。

使用する場面

• SimBiology モデル（コンパートメント、種、反応、パラメーター、ルール、イベント、投与、オブザーバブル、バリアント）の構築や変更
• Model Builder／Analyzer アプリでのモデルの開く、保存、読み込み
• 図のレイアウトの設計や調整
• キーワード：「build」、「create」、「modify」、「add compartment/species/reaction」、「diagram」、「layout」

使用しない場面

• シミュレーションと解析（matlab-simulate-simbiology-model を使用）
• パラメーターフィッティング、集団モデリング、NCA（matlab-fit-simbiology-model を使用）

必ず守るルール

1. まずヘルパースクリプトを MATLAB パスに追加する

各セッションの開始時に実行します：

addpath(fullfile('<WORKSPACE_ROOT>', '.claude', 'skills', 'matlab-build-simbiology-model', 'scripts'));
disp('Helper scripts added to path.')

2. 必要な場合のみ Builder を開く

デフォルトでは Model Builder を開かないでください。次の場合に開きます：

• ユーザーが図、レイアウト、または視覚的な出力を明示的に要求した場合
• 入力が .sbproj ファイルの場合 — 図のレイアウト／スタイルを保持するため、loadViaBuilder を使用します（sbioloadproject ではこのデータが失われます）

図がなくてもモデルは完全に機能します。sbioroot 上のモデルオブジェクトのみを使ってシミュレーション、フィッティング、解析ができます。

3. モデルの構築には標準の SimBiology API を使用する

addcompartment、addspecies、addreaction などを直接使ってモデルを構築します。これはデスクトップ、ヘッドレス、バッチ、リモートを含むすべての環境で動作します。

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'};

標準的な PK モデル（標準的な投与と消失を伴う 1 または 2 コンパートメントモデル）では、適切なパラメーター化、命名、ルールのリファレンスとして references/pk-library-guidance.md を使用します。図が不要な場合は、PKModelDesign を直接呼び出します。ユーザーが図を要求した場合は、同じ PK ライブラリの規約に従ってモデルを手動で構築しますが、レイアウトを制御するために addAndPositionCompartment を使用します（ルール 8b を参照）。

4. 反応は生物学的な順方向に記述する

図では、反応文字列の順方向に基づいて、生成物には矢印、反応物には単純な線が描画されます。反応を逆向きに記述すると、速度論的に等価であっても矢印が誤って表示されます。

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

ガイドライン：

• 結合： A + B -> C と記述します（左側に基質、右側に複合体）
• 分解／消失： Drug -> null と記述します（null -> Drug ではありません）
• 合成： null -> mRNA と記述します（mRNA -> null ではありません）
• 輸送： Source.Drug -> Dest.Drug と記述します（左側に移送元）

5. 種と反応スコープのパラメーターには、常に修飾名を使用する

種と反応スコープのパラメーターは、常に修飾名で参照します。名前に MATLAB の変数名として無効なものが含まれている場合は、修飾名を作成する前に角括弧で囲みます。

• 種： CompartmentName.SpeciesName（例：Central.Drug、Peripheral.[Drug-bound]）
• 反応スコープのパラメーター： ReactionName.ParameterName（例：Elimination.ke）

修飾は常に、直近の親コンパートメントまでの 1 階層のみです。Body.Central.Drug のような複数階層のパスは、反応文字列では無効です。コンパートメント名はモデル全体で一意でなければならないため（SimBiology はネストの深さにかかわらずこれを適用します）、曖昧さは生じません。そのため、常に Central.Drug で十分です。

コンパートメントの命名規則：

• 名前はモデル全体で一意でなければなりません。ネストの階層が異なっていても、同じ名前のコンパートメントを複数作成することはできません
• 階層的な命名が必要な場合は、Body_Central のようにアンダースコアを使用します（どちらも Central という名前のコンパートメントをネストするのではありません）
• 種の名前はコンパートメント内で一意である必要がありますが、異なるコンパートメント間では同じ名前を使用できます（Compartment.Species で区別されます）

6. 最新のプロパティ名（Value、Units、Constant）を使用する

SimBiology オブジェクト（種、コンパートメント、パラメーター）は、統一されたプロパティインターフェースを共有します。常に最新の名前を使用してください。

最新の名前	非推奨（使用しないでください）	対象
Value	InitialAmount、Capacity	種、コンパートメント、パラメーター
Units	InitialAmountUnits、CapacityUnits、ValueUnits	種、コンパートメント、パラメーター
Constant	ConstantAmount、ConstantCapacity、ConstantValue	種、コンパートメント、パラメーター

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. sbioreset の前に Builder と Analyzer を閉じる

sbioreset はこれらのアプリを閉じないため、ウィンドウが孤立したままになります。

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. ダイアグラムのルール（ユーザーがダイアグラムを要求した場合のみ）

以下のルールは、ユーザーがダイアグラムまたはレイアウトを要求した場合にのみ適用されます。 モデル構築のみの場合は、これらのルールをすべて無視してください。

モデルサイズの上限（前提条件）： レイアウトヘルパーは、 合計ブロック数が400を超えると処理を中止します（種＋反応）。大規模なモデルでは、 自動レイアウトを省略し、代わりにシンプルなグリッド配置を使用してください（反応は 接続された種の中点に配置します）。

a. ダイアグラムのレイアウトには addAndPositionCompartment を使用する

ダイアグラムを構築する際は、生の addcompartment と setBlock を使う代わりに、addAndPositionCompartment を使用してください。この関数は各コンパートメントを一括で作成、配置し、検証します。

% 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. ダイアグラムの構築順序

1. 最初に Builder を開きます。Builder が作成するまで、ダイアグラムは存在しません。この手順を行わないと、すべての simbio.diagram.* 呼び出しと addAndPositionCompartment が失敗します。
2. すべてのコンパートメントの [x y w h] 位置を事前に計画します（最低80 pxの間隔を空けます）
3. addAndPositionCompartment を使って、一度に1つのコンパートメントを構築します
4. すべてのパラメーター（ルールのLHSターゲットを含む）、反応、ルール、投与、イベントを追加します
5. repositionAllReactions(model)、次に checkDiagramLayout(model) を実行し、違反がゼロになるまで修正します
6. positionAncillaryBlocks(model) を実行します。ルール／パラメーターブロックが右側のグリッドに配置されます

c. 接続されたコンパートメント間に80 pxの間隔を空ける

コンパートメント間の反応ノード（15×15）は、repositionAllReactions によってこの間隔に配置されます。間隔が十分でないと、反応の線がコンパートメントのブロックを通過します。共有反応が多い（3件以上）コンパートメントでは、間隔を120 pxに増やしてください。

d. 配置後の検証は必須です

すべてのブロックを配置した後：

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. Builder には必ず安全なオープン手順を使用する

isAppOpen('builder') を事前に確認せずに simBiologyModelBuilder(model) を呼び出してはいけません。開いている場合は閉じ、2秒待ってから再度開いてください。

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. 変更するために Builder を閉じない

モデルハンドルは sbioroot 上にあります。すべてのコードはライブモデルに対して動作し、ダイアグラムをリアルタイムで更新します。ユーザーから明示的に求められた場合にのみ閉じてください。

ヘルパー関数（scripts/）

モデル構築（常に利用可能）

関数	シグネチャ	用途
getModelByUUID	model = getModelByUUID(uuid)	UUID でモデルを検索

図とビルダー（ユーザーが図／レイアウトを要求した場合のみ）

機能	シグネチャ	目的
addAndPositionCompartment	[comp,sp] = addAndPositionCompartment(model,name,cap,compPos,speciesInfo,Name=Value)	コンパートメントと種を作成し、まとめて配置します。sp は Species 配列です。sp{1} ではなく、sp(1) でインデックスを指定してください。 オプション：FontWeight（"bold"）、TextLocation（"center"）、Padding（20）、AutoExpand（true）、AutoFixPositions（true）
checkDiagramLayout	results = checkDiagramLayout(model)	包含、ブロックを横切る線、重なりをチェックします
computeSafeReactionPosition	pos = computeSafeReactionPosition(model,rxn)	線が交差しない反応ノードの位置
repositionAllReactions	nFixed = repositionAllReactions(model)	すべての反応をまとめて再配置します（最大3回のパス）
positionAncillaryBlocks	n = positionAncillaryBlocks(model)	ルール／パラメータブロックをコンパートメントの右側にグリッド状に配置します
openLiveBuilder	openLiveBuilder(model)	安全なオープンパターンで Builder を開きます
isAppOpen	tf = isAppOpen(appName)	Builder／Analyzer が開いているか確認します
loadViaBuilder	model = loadViaBuilder(filePath)	図を保持したまま .sbproj を読み込みます
saveViaBuilder	saveViaBuilder(filePath)	図を保持したまま Builder から保存します
lineIntersectsRect	hit = lineIntersectsRect(x1,y1,x2,y2,rect)	共通のジオメトリーヘルパー（レイアウトスクリプト内部で使用）

checkDiagramLayout の出力

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 クイックリファレンス

モデル

• sbiomodel(name) — モデルを作成します。model.uuid — 一意の ID
• sbioloadproject('file.sbproj') — モデル名をフィールドとする構造体を返します。動的に取り出します：

  proj = sbioloadproject('file.sbproj');
  fn = fieldnames(proj);
  model = proj.(fn{1});
  

• copyobj(model) — ディープクローン（図のレイアウトはコピーしません）。verify(model) — 整合性をチェックします
• sbioreset — すべてのモデルをクリアします（先にアプリを閉じてください！）

コンパートメント

• addcompartment(model, name, value)
• comp.Value、comp.Constant、comp.Units、model.Compartments
• 単位の整合性： いずれかのコンポーネントに単位がある場合、すべてのコンポーネント（コンパートメント、種、パラメータ）に単位が必要です。単位が欠けていると、シミュレーション／フィッティング時に 'Dimensional analysis failed' エラーが発生します。

種

• addspecies(comp, name, value)
• sp.Value、sp.Units、sp.BoundaryCondition、sp.Constant
• sp.Parent.Name — 親コンパートメント。model.Species

パラメータ

• addparameter(model, name, value) — モデルスコープ
• addparameter(kineticLaw, name, value) — 反応スコープ
• p.Value、p.Units、p.Constant、model.Parameters

反応

• addreaction(model, 'A -> B') — 順反応。'A <-> B' — 可逆反応
• kl = addkineticlaw(rx, 'MassAction'); kl.ParameterVariableNames = {'k1'}（可逆反応の場合は {'kf','kr'}）
• 複数コンパートメント：'Central.Drug -> Peripheral.Drug'

ルール、イベント、投与

• addrule(model, 'x = expr', ruleType) — 'initialAssignment'、'repeatedAssignment'、'rate'
• ルールと反応の排他性： レートルールまたは反復代入ルールの左辺にある種は、反応の反応物または生成物としても使用できません。動態を制御する方法はいずれか一方を使用してください。
• ルールの左辺の要件： 左辺には、既存の種、パラメータ、または Constant = false のコンパートメントを指定する必要があります。パラメータはルールより前に作成してください（修正のために後から作成するのではなく、図のレイアウト用ブロックが確実に作成されるようにします）：

  p = addparameter(model, 'RO', 0); p.Constant = false;
  addrule(model, 'RO = Complex / (Target + Complex)', 'repeatedAssignment');
  

• addevent(model, 'trigger', {'action1', 'action2'})
• イベントアクションの要件： イベントアクションで変更するパラメータは、Constant = false である必要があります（パラメータの既定値は true です）：

  p = sbioselect(model, 'Type', 'parameter', 'Name', 'kgrow');
  p.Constant = false;
  addevent(model, 'Tumor.Cancer < 1e6', {'kgrow = kgrow * 0.5'});
  

• sbiodose(name, 'schedule') ／ sbiodose(name, 'repeat')
• スケジュール：.TargetName、.Amount、.Time、.Rate
• 繰り返し：.TargetName、.Amount、.StartTime、.Interval、.RepeatCount
• adddose(model, d) ／ removedose(model, d)

オブザーバブルとバリアント

• addobservable(model, name, expression) — 要素ごとの演算には ./ と .* を使用します
• StatesToLog に関する注意： オブザーバブルが定数パラメーター（例：'Drug ./ Vd'）を参照する場合は、そのパラメーターを StatesToLog に追加してください。追加しないと、NaN として記録されます。依存関係がそろっていれば、オブザーバブル自体は自動的に記録されます（オブザーバブルを StatesToLog に追加しないでください。受け付けるのは種、パラメーター、コンパートメントのみです）。
• v = addvariant(model, name) の後、addcontent(v, {'type','name','prop',val}) を実行します
• v.Content、getvariant(model, name)

シミュレーション設定

• cs = getconfigset(model, 'active')
• cs.StopTime、cs.SolverType（'ode15s'、'ode45'、'sundials'）
• cs.RuntimeOptions.StatesToLog — 'all' またはハンドル配列

選択

• sbioselect(model, 'Type', type, 'Name', name)
• 反応の場合は、'Name' ではなく 'Reaction' プロパティを使用します

コアパターン

モデルの作成（標準 — ダイアグラムなし）

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

反応

% 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]');

コンポーネントの削除

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

投与

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

イベント、バリアント、オブザーバブル

% Event modifying a parameter — mark non-constant first
p = sbioselect(model, 'Type', 'parameter', 'Name', 'ke');
p.Constant = false;
ev = addevent(model, 'time >= 10', {'ke = ke * 2'}); ev.Name = 'EnzymeInduction';

% Event modifying a species (species default Constant=false — no extra step)
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');

モデルの保存

• 標準： save('mymodel.mat', 'model') / loaded = load('mymodel.mat'); model = loaded.model; sbiosaveproject は使用しないでください（非推奨であり、ベースワークスペースのハックが必要です）。
• ダイアグラムあり（.sbproj）： saveViaBuilder('name.sbproj') / loadViaBuilder(path)（Builder を開いておく必要があります）
• モデルの切り替え： 先に保存するようユーザーに依頼 → Builder を閉じる → pause(2) → simBiologyModelBuilder(newModel)
• 切り替えと調整のパターン全般については、references/app-lifecycle-guidance.md を参照してください。

ダイアグラムの基本（ユーザーがダイアグラム／レイアウトを求めた場合のみ）

座標系

Position = [x y width height]。(x, y) は左上の角です。

標準ブロックサイズ

ブロックタイプ	デフォルトサイズ	備考
種	[50, 16]	幅のスケール：5 文字以下 → 50、6～12 文字 → 100、13 文字以上 → 130
反応	[15, 15]
ルール	[20, 20]

内容に応じたコンパートメントのサイズ設定

種の数	サイズ	備考
1	160 x 100	種が 1 つの場合。中央に配置
2（独立）	240 x 170	縦に配置
2（連鎖）	400 x 100	横に並べて配置
3～5	160+n*50 x 100+n*35	内容に合わせて調整
6 以上	240+n*50 x 220+n*35	行レイアウト。必要に応じて複数行

内側の余白：すべての辺で最低 30 px。

行ベースの種の配置（種が 3 つ以上）

種を y + height/2 - 8 の位置で横一列に均等配置し、コンパートメントの端から 40 px の余白を確保します。名前の長さに応じて種の幅を調整します： 5 文字以下 → 50、6～12 文字 → 100、13 文字以上 → 130。

接続方向に応じた種の順序

コンパートメント内の 2 つ以上の種が、異なる外部コンパートメントに接続する場合は、各種が接続先を向くように順序を決めます。こうすることで、接続線が隣り合う種を通り抜けるのを防げます。

• 水平方向に隣接する場合： 左に接続する種を左端に、右に接続する種を右端に配置します。
• 縦に並べる場合： 上／左に接続する種を上に、下／右に接続する種を下に配置します。
• 例： Blood に Neutrophil（左側の Transit3 に接続）と Lymphocyte（左上の Spleen に接続）があるとします。線が交差しないように、 Lymphocyte を上に、Neutrophil を下に配置します。

レイアウトルール

必須要件：

1. ブロック同士を重ねない（コンパートメント内の種を除く）
2. ラベルが表示され、ほかのブロックと重ならない
3. 同じ階層のコンパートメントは、横方向／縦方向に整列させる
4. コンパートメント間の反応は、両方のコンパートメントの外側（すき間）に配置する
5. 接続線が無関係なブロックを通らない
6. 反応と種の距離は最低 50 px

推奨する配置： 7. 消去／分解反応は親コンパートメント内に配置する（境界を越えてではなく、局所的に生じるプロセスであることを示します）

モデルタイプ別のフロー方向

モデルタイプ	フロー方向
PKPD	PDは左上、PKは右下
Metabolic	上から下
PBPK	循環に基づく列
Simple PK	左から右、または斜め

参考資料

詳細なガイダンスは必要に応じて読み込んでください：

• references/layout-strategy-guidance.md — 戦略の選択、構築前チェックリスト、7つのレシピ
• references/pbpk-layout-guidance.md — PBPKの循環とACATチェーンのレイアウト
• references/evacuation-procedure-guidance.md — 既存モデルを再配置する5段階の手順
• references/api-cheatsheet-guidance.md — simbio.diagram APIの全機能（getBlock、setBlock、lines、clones）
• references/app-lifecycle-guidance.md — モデルの切り替え、Analyzerとの連携
• references/diagram-styling-guidance.md — 色、フォント、クローンの仕組み
• references/pk-library-guidance.md — 標準PKモデル向けのPKModelDesign

---

Copyright 2026 The MathWorks, Inc.

---