simscape-write-ssc

Simscape Language Authoring

Write .ssc files (components, domains, functions) that pass validation and are physically correct.

When to Use

• Writing a new .ssc component, domain, or function from scratch
• Adding or modifying physics, equations, or parameterization in an existing .ssc file
• Converting governing equations into a working Simscape component
• Adding mode charts, events, or switching logic to a component
• Building a composite component that connects subcomponents together
• Fixing Simscape Language syntax or validation errors

When NOT to Use

• Configuring or connecting existing Simscape blocks in a Simulink model — use building-simulink-models instead
• Simulating a model or inspecting results — use simulating-simulink-models
• Setting block parameters from MATLAB or a script without editing .ssc source

---

Workflow

Designing a component

Below are the sections that make up a Simscape component. Include only what is needed.

nodes, inputs, outputs

• nodes — quantity participates in bilateral energy exchange (the network enforces Across equalization + Through summation).
• inputs — physical signal imposed from outside (control signal, environment).
• outputs — physical signal for a measurement or computed result.

Node ports have a domain. Reuse an existing one, especially foundation; author a custom domain only when none covers the physics.

Physics	Domain path
Electrical (single-phase)	foundation.electrical.electrical
Rotational mechanical	foundation.mechanical.rotational.rotational
Translational mechanical	foundation.mechanical.translational.translational
Thermal (heat transfer)	foundation.thermal.thermal

For fluid domains, polyphase electrical, position/angle-based mechanical variants, or any domain not in the table, you must read: references/foundation/domain-selection.md.

parameters, variables

Parameters — user-configurable inputs; part of the interface.

• Expose as parameters for physical quantities the engineer sets (resistances, dimensions, thresholds).
• Use parameters(Access=private) for quantities computed from other parameters. Use intermediates when the value depends on a runtime value.
• Defaults: physically typical values, so the component works out of the box.

Variables — differential, algebraic, or event.

• Differential (appear in der(x)): set priority.high; use an initial equation only when the start depends on another variable rather than a fixed/parameter value — never both.
• Event: declare (Event = true)

Visibility (both): default Access = public, ExternalAccess = modify for user-facing items. Access = private + ExternalAccess = none for pure implementation detail; protected + observe for internal quantities that subclasses or logging should see.

Units — declare everywhere. Every parameter and variable carries a unit ({value, 'unit'}, or '1' for dimensionless). Simscape validates commensurability at compile time and auto-converts across the network. Declare in the unit the engineer naturally uses (mm, deg, bar). A bare number is a silent mismatch waiting to happen.

Compile-time vs. runtime conditionals (if)

• Interface items (ports, variables the user sees): declared unconditionally (public). Use conditional annotations + ExternalAccess to hide/show them based on a parameter — they remain part of the interface but become invisible in inactive variants.
• Internal items (hidden variables, internal equations): prefer compile-time if (top-level, parameter-guarded) to eliminate them entirely — reduces states, logging, and solver work.
• Runtime if (inside equations): use when the governing equation changes at runtime. Must have an else branch. Equation count/dimensionality must be identical in every branch.

equations, intermediates, components, connections, for, modecharts, events, annotations

Section	Include when
equations	continuous relationships (== is symmetric equality), assert for parameter validation, equations (Initial=true) for init-only constraints
intermediates	factor a reused subexpression or want it logged
components / connections	assembling from existing subcomponents (composite)
for	arrays of components or nodes
modecharts	the component has discrete operating states, each with a structurally different equation set (different equation counts, or der terms that come/go) — and transitions between them, possibly with hysteresis. Overkill when a smooth approximation (tanh, tablelookup) or runtime if with identical equation counts fits.
events	update variables(Event=true) (latches, sample-hold, one-shot triggers) at discrete instants via edge() / initialevent. Prefer modecharts when suitable.
annotations	conditional visibility (ExternalAccess overrides), icons (Icon), dialog tabs (UILayout), port sides (Side), logging units (LoggingUnit), fault modeling (Faults), or unit dropdowns (UnitDropdown)
setup	never — deprecated; use assert in equations instead

Write the .ssc file

Write for textbook readability — equations should read as physics. Match the surrounding library's conventions when editing an existing file.

Validate

simscape.agentic.sscIssues (in scripts/+simscape/+agentic/) takes the fully qualified name of a Simscape component, domain, or function and prints diagnostics or "No issues found." Run it with evaluate_matlab_code, project_path set to the skill's scripts/ folder so MATLAB can find the package. Fix reported issues and re-validate until clean.

simscape.agentic.sscIssues("mylib.components.MyComponent")

Pass the fully qualified name — dot-separated namespaces, not a file path. A file at +mylib/+components/MyComponent.ssc on the MATLAB path is named mylib.components.MyComponent. The function errors if the name is not on the path or does not resolve to a .ssc/.sscp file.

Setting project_path changes the current folder, so the working folder and the files the component references may drop off the path. A not found on the MATLAB search path error, or a Validation failed: diagnostic naming a missing referenced file, is a path problem — not a bug in the .ssc. Add necessary folders to the path before treating diagnostics as real.

Reference files (references/)

Each file is self-contained. Read only what you need.

references/
  composition/
    arrays-of-nodes.md
    composite-components-and-connections.md
    composites-member-variable-initialization.md
    for-loop-component-arrays.md
    inheritance-and-subclassing.md
    optional-and-variant-members.md
  equations-and-variables/
    assertions-and-bounds.md
    intermediates-and-let.md
    variables-derivatives-initialization.md
  foundation/
    domain-selection.md
    gas.md
    isothermal-liquid.md
    moist-air.md
    thermal-liquid.md
    two-phase-fluid.md
  language-functions/
    matlab-declaration-functions.md
    tablelookup.md
    writing-simscape-functions.md
  modecharts-and-events/
    events-and-event-variables.md
    modecharts.md
  parameters-and-conditionals/
    access-and-visibility-attributes.md
    conditional-sections-and-hiding-members.md
    enumerations.md
    parameter-declaration.md
  ports-and-nodes/
    branches.md
    nodes-conserving-ports.md
    physical-signal-inputs-and-outputs.md
  presentation/
    block-appearance-and-ports.md
    uilayout-and-dialog-tabs.md

---

Copyright 2026 The MathWorks, Inc.

---