| name | simulink-requirements |
| description | Use this skill for all requirements-related work in a MATLAB MBSE project using the Requirements Toolbox (slreq). Covers creating and populating requirement sets, derivation links, test case requirements, verification coverage, reading and tracing links across requirement sets and models, checking link health, allocating requirements to components (Implement links), and building traceability reports. Trigger when the user asks about slreq API, slreqx files, slmx link files, outLinks/inLinks, traceability matrices, coverage analysis, broken links, or mapping requirements to architecture components. Use proactively for any requirements or traceability task. |
| license | MathWorks BSD-3-Clause (see LICENSE) |
| metadata | {"author":"MathWorks","version":"1.0"} |
MATLAB Requirements Toolbox — Requirements & Traceability
This skill covers everything in the slreq API: creating and reading requirements,
managing traceability links, checking verification coverage, allocating requirements
to architecture components, and auditing link health.
For architecture phases (System Composer models, functional decomposition,
functional→physical allocation) see the mbse-architecture skill.
See references/api-quickref.md in this skill folder for a compact one-page API reference.
The Two File Types
| Extension | Class | Role |
|---|
.slreqx | slreq.ReqSet | Stores requirements (text, hierarchy) |
.slmx | slreq.LinkSet | Stores traceability links outgoing from a source artifact |
When a .slmx file is created
slreq writes a .slmx file only when its companion artifact is the source of at least one link. The LinkSet is keyed on the source artifact, not the destination.
MyReqs~slreqx.slmx appears only if some link's source is a requirement in MyReqs.slreqx (e.g., slreq.createLink(srcReq, destReq) where srcReq lives in MyReqs)MyModel~mdl.slmx appears only if some link's source is a model element in MyModel.slx (typical: slreq.createLink(component, req) with Type Implement — the component is the source)
An artifact that is only ever a link destination never gets a paired .slmx. In a typical MBSE project:
| Artifact | Gets a .slmx? | Why |
|---|
StakeholderNeeds.slreqx | Yes | SNs are the source of Derive links to SRs |
SystemRequirements.slreqx | Usually no | SRs are destinations of Derive / Implement / Verify links; no file unless SR-to-SR Refine links or links to external docs are added |
TestCases.slreqx | Yes | TC requirements are the source of Verify links to SRs |
Architecture .slx models | Yes | Components are the source of Implement links to SRs |
Reporting rules for build scripts
Because .slmx files are conditional, never claim a .slmx was produced based on the API calls you made — always verify with isfile before reporting. A script that creates only SN→SR Derive links will produce StakeholderNeeds~slreqx.slmx but not SystemRequirements~slreqx.slmx, even though both .slreqx files exist.
Idempotent cleanup and project registration for .slmx files must both guard with isfile:
if isfile(snLinks), delete(snLinks); end % cleanup — safe whether or not it exists
The registerWithProject helper already does this — it skips files that don't exist on disk — so passing a non-existent .slmx path is a no-op, not an error.
Requirements (Phases 1–2)
Two-Level Structure
| Level | ID scheme | Character |
|---|
| Stakeholder Needs | SN-SYS-001 | Operational, informal — what the user/operator needs |
| System Requirements | SR-SYS-001 | Formal, testable — what the system shall do |
Each SR traces back to one or more SNs via a Derive link.
Well-Formed Shall-Statements
- One obligation per requirement ("shall", not "should" or "will")
- Measurable and testable — include numeric criteria where possible
- Avoid
< and > in Description fields — the Requirements Editor treats them
as HTML. Use "not exceeding", "at least", "greater than", etc.
Good: The system shall respond with latency not exceeding 100 ms.
Avoid: The system shall respond with latency < 100 ms.
Creating Requirement Sets
slreq.clear();
if isfile('MyReqs.slreqx'), delete('MyReqs.slreqx'); end
rs = slreq.new('MyReqs.slreqx'); % NOT slreq.createReqSet (does not exist)
req = rs.add();
req.Id = 'SR-SYS-001';
req.Summary = 'Short title';
req.Description = 'The system shall ...';
req.Rationale = 'Why this requirement exists.';
rs.save();
Find a requirement by ID
req = rs.find('Id', 'SR-SYS-001');
Valid Link Types
| Type | Meaning | Direction |
|---|
"Derive" | Parent decomposes into derived child | SN (source) → SR (destination) |
"Implement" | Architecture element (or model block) implements requirement | Component/Block (source) → SR (destination) |
"Verify" | Test case verifies requirement | TC (source) → SR (destination) |
"Refine" | Requirement refined into a more specific requirement (same artifact kind, more detail). Not used for SR → architecture in this workflow. | SR (source) → SR (destination) |
"Relate" | Informal relationship | Bidirectional |
Creating Links
% Req-to-req derivation: parent (e.g. SN) decomposes into derived child (e.g. SR)
lnk = slreq.createLink(parentReq, childReq);
lnk.Type = 'Derive';
% Model block to req (model must be open in Simulink)
lnk = slreq.createLink(blockHandle, req);
lnk.Type = 'Implement';
% Test case requirement to SR
lnk = slreq.createLink(tc, sr);
lnk.Type = 'Verify';
slreq.saveAll(); % always call after creating cross-artifact links
Side effect: {modelName}~mdl.slmx link store
The first time you create a link whose source is an element of a Simulink/System Composer
model (component, subsystem, or block), slreq writes a {modelName}~mdl.slmx file next to the
.slx. This is the normal case for Implement links in this workflow — slreq.createLink(component, req)
has the component as source, so the link lives in the model's LinkSet, not the requirement set's.
A model that only ever receives links (no element of it is used as a link source) does not
get a ~mdl.slmx. In MBSE practice this is rare: architecture models almost always have Implement
links where they are the source.
After creating links whose source is in a model, register both the .slx and the .slmx with the
project, guarding .slmx registration with isfile since the file may not yet exist:
addFile(proj, fullfile(archDir, 'MyModel.slx'));
slmx = fullfile(archDir, 'MyModel~mdl.slmx');
if isfile(slmx), addFile(proj, slmx); end
Forgetting to register an existing .slmx causes project file-system checks to fail and the
traceability links won't travel when the project is shared.
Requirements Script Skeleton
See code/buildMyRequirements.m for the full parameterized function:
buildMyRequirements(snFile, srFile)
Exporting a Requirement Set to Excel
There is no public slreq Excel-export API. slreq.export emits ReqIF only,
and the Requirements Editor's File → Export → Microsoft Excel is GUI-only. To
script an xlsx export, build the table yourself with writetable.
Requirement sets can be hierarchical. find(rs, 'Type', 'Requirement')
returns all requirements flat in storage order, which silently drops the
parent/child structure the Requirements Editor displays. To preserve hierarchy:
- Find top-level reqs by filtering for
~isa(r.parent(), 'slreq.Requirement')
— top-level items have the ReqSet as their parent, not another requirement
- Recurse via the
children() method (a method, not a property)
- Emit rows depth-first so each parent precedes its children
- Sort siblings with a natural sort on the
Index string ("1", "1.2", "1.10"
as numeric tuples — lexicographic string sort would put 1.10 before 1.2)
- Write
Index, Depth, ParentIndex columns so the hierarchy is recoverable
from the xlsx alone
Note also that r.Id may be an auto-assigned SID like #13 if the set was
authored in the Editor without user IDs — always include the Index column as
a stable user-meaningful identifier.
Extract parent IDs from incoming Derive links so the DerivedFrom column is
populated instead of stuffing parent refs into Rationale:
function ids = deriveParents(req)
ids = strings(0,1);
lnks = req.inLinks();
for k = 1:numel(lnks)
if strcmp(lnks(k).Type, 'Derive')
% getSourceLabel() returns "ID Summary"; strtok pulls just the ID
ids(end+1,1) = string(strtok(lnks(k).getSourceLabel())); %#ok<AGROW>
end
end
end
See code/exportRequirementsToExcel.m for the
full parameterized function:
exportRequirementsToExcel(slreqxFile)
Importing a Requirement Set from Excel
slreq.import handles Excel natively, but has several gotchas worth wrapping:
it treats the header row as a requirement (use rows=[2 lastRow] to skip it),
it auto-creates a Container node wrapping the items, and — most importantly —
it does not save to disk (the returned ReqSet is marked Dirty=1; call
.save() explicitly).
Use AsReference=false to get an editable copy rather than read-only references
to the xlsx, and map columns with idColumn / summaryColumn /
descriptionColumn / rationaleColumn.
Flatten the auto-created Container by default
slreq.import always wraps imported items under a single Container node
named "<File>!<Sheet>", which becomes index 1 in the set and pushes every
actual requirement to 1.1, 1.2, etc. Users viewing the set in the
Requirements Editor see a useless extra hierarchy level. The wrapper helper
unwraps this by default: it forward-promotes each direct child of the
Container to top level, then removes the empty Container. Real nested
hierarchy (e.g. when importing ReqIF with actual parent/child structure) is
preserved — the helper never touches children of non-Container nodes.
Two invariants to preserve if editing the flatten logic:
- Exactly one Container at top level — flatten only the auto-import
wrapper. If a set has zero or multiple top-level Containers, leave them all
alone (that's not the wrapper signature).
- Forward-promote, not reverse — promoting children in reverse reverses
sibling order in the resulting flat list. Iterate
1:numel(kids).
Helper
See code/importMyRequirements.m for a wrapper
that applies the defaults and saves:
importMyRequirements(xlsxFile, setName)
importMyRequirements(xlsxFile, setName, flatten=false) % keep the Container
Verification (Phase 7) — TC Requirements
Test cases live in their own requirement set (TestCases.slreqx), separate from
system requirements. Each TC is an slreq.Requirement linked to its SR with a
Verify link.
SR-SYS-001 ←[Verify]─ TC-SYS-001
Each TC captures a test in prose — setup, stimulus, pass criterion — and
traces back to exactly one SR. This is the only verification layer in the
workflow; there is no separate executable-test artifact.
TC Requirement Fields
| Field | Content |
|---|
Id | TC-SYS-001 |
Summary | Short test name |
Description | Setup + action + pass criterion |
Rationale | "Verifies SR-SYS-001" |
A good description answers: Setup (initial conditions), Action (stimulus
applied), Pass criterion (measurable result that constitutes success).
Test Case Script Skeleton
See code/buildMyTestCases.m for the full parameterized function:
buildMyTestCases(srFile, tcFile)
Verification Coverage Report
allSRs = srSet.find('Type', 'Requirement');
covered = 0;
for i = 1:numel(allSRs)
in_ = allSRs(i).inLinks(); % method on the req object — NOT slreq.inLinks()
hasTc = false;
for k = 1:numel(in_)
if strcmp(in_(k).Type, 'Verify')
hasTc = true;
break;
end
end
if hasTc
covered = covered + 1;
else
fprintf('NOT COVERED: %s\n', allSRs(i).Id);
end
end
fprintf('Coverage: %d / %d (%.0f%%)\n', covered, numel(allSRs), ...
100 * covered / numel(allSRs));
Reading and Tracing Links
Loading Files for Analysis
To load a single file:
rs = slreq.load('path/to/MyReqs.slreqx');
To load all requirement and link files across a project tree, see
code/loadProjectRequirements.m:
loadProjectRequirements(projRoot)
slreq.load() is for scripted analysis (no UI). slreq.open() opens the
Requirements Editor UI — avoid it in analysis scripts.
File discovery note: proj.Files only lists top-level project files. Sub-project
files don't appear. Always use dir(fullfile(root,'**','*.slreqx')) to find all files.
Querying Loaded Objects
% All loaded ReqSets and LinkSets
allReqSets = slreq.find('type', 'ReqSet');
allLinkSets = slreq.find('type', 'LinkSet');
% Find a specific ReqSet by name
rs = slreq.find('type', 'ReqSet', 'Name', 'SystemRequirements');
% All requirements in a set (returns ALL node types: Functional, Container, etc.)
reqs = rs.find('Type', 'Requirement');
% Find by ID or SID
r = rs.find('Id', 'SR-SYS-001');
r = rs.find('SID', 5);
rs.find('Type','Requirement') returns every node — both Functional and Container
types. Filter by r.Type if you only want leaf requirements.
Requirement Node Properties
r.Id % user-assigned ID (string), e.g. 'SR-SYS-001'
r.SID % internal integer, unique within the file
r.Type % 'Functional', 'Container', 'Safety', 'Informational'
r.Summary % one-line summary
r.Description % HTML string — use getDescriptionAsText() for plain text
r.Rationale % plain text rationale
r.Index % hierarchical index, e.g. '2.1.3'
% Clean description (strips HTML formatting)
plainText = r.getDescriptionAsText();
% Navigate hierarchy
kids = r.children(); % slreq.Requirement array of child nodes
parent = r.parent(); % slreq.Requirement or slreq.ReqSet (if top-level)
outLinks and inLinks
Every requirement has two directions of links:
| Method | Returns | Meaning |
|---|
r.outLinks() | Links from this req pointing outward | This req decomposes into a derived child (Derive outLink) |
r.inLinks() | Links pointing INTO this req | Things that implement, verify, or derive from this req |
out = r.outLinks(); % slreq.Link array
in_ = r.inLinks(); % slreq.Link array
% IMPORTANT: cannot vertcat outLinks/inLinks directly — iterate with index
for k = 1:numel(out)
lnk = out(k);
fprintf(' -> %s "%s"\n', lnk.Type, lnk.getDestinationLabel());
end
Reading Link Data
These methods work even when isResolved() is false:
lnk.Type % 'Derive', 'Implement', 'Verify', 'Relate', 'Refine'
lnk.getSourceLabel() % human-readable label for the source artifact
lnk.getDestinationLabel() % human-readable label for the destination artifact
% Resolution status
lnk.isResolved() % true only if BOTH ends are resolved — often false, do not rely on it
lnk.isResolvedSource() % source artifact is loaded
lnk.isResolvedDestination() % destination artifact is loaded
% Raw reference struct — ALWAYS readable, even when unresolved
src = lnk.source(); % struct: .domain, .artifact, .id (source end)
ref = lnk.getReferenceInfo(); % struct: .domain, .artifact, .id (destination end)
Link Domain Types
The .domain field identifies what kind of artifact the link points to:
| Domain | Artifact type | ID format |
|---|
linktype_rmi_slreq | .slreqx requirement file | integer SID string, e.g. "8" |
linktype_rmi_simulink | .slx Simulink model block | SID path, e.g. ":4:27" |
linktype_rmi_word | .docx Word document | @Simulink_requirement_item_N |
Resolving a Req-to-Req Link Destination
ref = lnk.getReferenceInfo();
if strcmp(ref.domain, 'linktype_rmi_slreq')
sid = str2double(ref.id);
allRS = slreq.find('type', 'ReqSet');
for i = 1:numel(allRS)
[~, fn] = fileparts(allRS(i).Filename);
[~, artName] = fileparts(ref.artifact);
if strcmpi(fn, artName)
destReq = allRS(i).find('SID', sid);
break;
end
end
end
Link Direction Semantics
SN ──[Derive]──> SR (parent has outLink; derived child has inLink)
Component ──[Implement]──> SR (component has outLink; req has inLink)
Test case ──[Verify]────> SR (test has outLink; req has inLink)
In this workflow link direction goes parent/active → child/requirement-end for all
three types — the parent SN points at the SR it decomposes into, the architecture
element points at the SR it implements, and the test case points at the SR it verifies.
A requirement derives from another (parent) when it has inLinks() of type Derive.
A requirement is implemented by an architecture element when it has inLinks() of
type Implement whose source is a System Composer component (or a Simulink block).
A requirement is verified by a test case when it has inLinks() of type Verify.
LinkSet Methods
links = ls.getLinks(); % all links in a LinkSet
[broken, details] = ls.getBrokenLinks(); % links whose destination is gone
orphans = ls.getOrphanLinks(); % links whose source artifact is gone
ls.Artifact % full path to the artifact this LinkSet belongs to
ls.Filename % full path to the .slmx file itself
Coverage Analysis — Per-Requirement Status
See code/reportCoverageByReq.m:
reportCoverageByReq(rs)
Coverage Analysis — Aggregate Across All ReqSets
See code/reportCoverageAggregate.m — loads all files
via loadProjectRequirements, then prints a per-ReqSet summary table:
reportCoverageAggregate(projRoot)
Link Health Report
See code/reportLinkHealth.m — operates on all currently loaded
LinkSets; call loadProjectRequirements first:
reportLinkHealth()
Full Traceability Chain Trace
See code/traceRequirement.m:
traceRequirement(rs, reqId)
Common Pitfalls
slreq.inLinks(req) / slreq.outLinks(req) do not exist — these are methods
on the requirement object: req.inLinks() and req.outLinks().
slreq.open() in scripts — use slreq.load() for scripted analysis. slreq.open()
launches the Requirements Editor UI.
isResolved() is almost always false for model links — this is normal.
Simulink block SIDs can't be resolved without opening the model. Always use
getSourceLabel(), getDestinationLabel(), and getReferenceInfo() instead.
outLinks()/inLinks() arrays cannot be vertcat'd — iterate with index,
or collect into a cell array first.
rs.find('Type','Requirement') returns Containers too — the Type property on
returned objects is 'Container', 'Functional', etc. Filter if needed:
reqs(strcmp({reqs.Type}, 'Functional')).
Description contains HTML — use r.getDescriptionAsText() to get clean text.
getImplementationStatus() requires update first — call rs.updateImplementationStatus()
before calling r.getImplementationStatus(), otherwise it throws.
Delete .slmx link files alongside .slreqx files when rebuilding requirement
sets. Stale .slmx files store cross-artifact links and will auto-open old model
files on load, causing conflicts.
Linking a System Composer Interaction (sequence diagram) to a requirement
doesn't persist on R2025b. Two dead ends:
slreq.createLink(interactionObj, req) — with a raw
systemcomposer.interaction.Interaction — throws a bare "Link creation failed" error.- The struct workaround
struct('domain','linktype_sc_interaction', 'artifact',modelName,'id',char(diagram.UUID)) does create a link in
memory (and req.inLinks() shows it), but on next slreq.load the
slreq.data.ReqData/loadLinkSet listener errors with
"Artifact type mismatch: Expected linktype_rmi_simulink, Found linktype_sc_interaction" whenever the same .slx artifact already
stores linktype_rmi_simulink Implement links from component→req
wiring. slreq refuses to coexist two different artifact-type LinkSets
on one .slx; the interaction-sourced link is silently dropped on
reload.
Workarounds:
- Convention-based trace. Give the interaction a clear name and refer
to it by name from requirements'
Description or Rationale, or from
a TC. Rely on humans to walk the trace.
- Companion TC. Create a dedicated
TC-XXX-YYY whose description is
"Execute the <interactionName> sequence on the model and
verify message ordering and guard expressions." Verify link that TC
to the target SR; slreq supports TC→SR Verify links normally.
Revisit in a future MATLAB release — mixed-domain LinkSets on one .slx
may eventually be permitted, at which point the UUID-struct approach can
be re-enabled. See the system-composer skill's Sequence Diagrams
section for the programmatic API.
Don't stuff parent-reference text into Rationale. Writing "Derived from SN-SYS-001." into req.Rationale shadows the real purpose of the field AND
collides with the DerivedFrom column on xlsx export. Keep Rationale for the
why (what constraint or judgment picked this value); let the Derive link carry
the parent reference, and extract it from inLinks() at export time.
Getting a parent requirement's Id from a link. lnk.source() returns a
struct with .domain, .artifact, .id — but .id is the numeric SID, not
the user-facing Id like 'SN-SYS-001'. For the Id string, use
strtok(lnk.getSourceLabel()) — the label format is "ID Summary", so
strtok pulls just the Id.
slreq.import does not save to disk. The function returns
[refCount, reqSetFilePath, reqSetObj] — the path is where the file will
live, but the ReqSet is only in memory and marked Dirty=1. Call
reqSetObj.save() (or slreq.saveAll()) before closing, or the imported set
vanishes. Observed with AsReference=false on Excel import; worth checking
before relying on the default behavior in other modes.
Excel import treats the header row as a requirement unless you set
rows=[firstDataRow lastDataRow]. Also auto-creates a Container node named
"<File>!<Sheet>" wrapping the imported items; the importMyRequirements
helper flattens it by default (see above), otherwise filter it out with
r.Type == "Container" when iterating.
req.inLinks() auto-loads referenced ReqSets. Calling inLinks() on a
requirement causes slreq to resolve link sources, which loads any .slmx /
.slreqx files that reference this set. So a plain
slreq.load(SystemRequirements.slreqx); req.inLinks(); may silently bring
TestCases.slreqx into memory too (if any Verify link points here). This
causes hidden state leakage across phases of a pipeline — if one phase loaded
SR and walked its inLinks, the next phase's slreq.clear() must happen
before that phase's slreq.load(), not after, and you can't assume slreq.find
only returns sets you explicitly loaded.
req.remove() leaves orphan outLinks in the .slmx. Removing a
requirement drops the requirement object, but its outgoing links (e.g. Verify
links pointing at an SR) stay in the LinkSet as "unresolved source" entries
until the LinkSet is reloaded. Symptom on next open:
Warning: LinkSet for MyFile.slreqx contains N links with unresolved sources.
Fix: clear the LinkSet explicitly before removing requirements. Pattern:
lnkSets = slreq.find('type','LinkSet','Artifact', reqFile);
for i = 1:numel(lnkSets)
links = lnkSets(i).getLinks();
for j = 1:numel(links), links(j).remove(); end
end
existing = rs.find('Type','Requirement');
for k = numel(existing):-1:1, existing(k).remove(); end
Idempotency pattern: load-or-clear-and-repopulate beats delete-and-new.
slreq.new(file) intermittently fails with Can not create Requirement Set named X because of name conflict with X.slreqx even after slreq.clear() and
a successful delete(file) — especially in long pipelines where earlier phases
have touched the file. The robust idempotent pattern is:
if isfile(reqFile)
rs = slreq.load(reqFile);
clearLinkSet(rs); % see above — avoids orphan-link warnings
clearRequirements(rs);
else
rs = slreq.new(reqFile);
end
% ... populate fresh ...
rs.save();
This is the pattern in Phase 9 of mbse-workflow/SKILL.md.
