SysML v2
SysML v2 Tutorials
Nine guided tutorials for SysML v2 projects, from the first package to ports, actions, states, requirements, verification, constraints and variants, with a step panel that checks your work.
On this page
Holarch has a track of guided tutorials for SysML v2 projects. Each one creates a small SysML v2 starter project and opens a step panel beside the page. The panel checks the model as you work: a step turns green when the model has what the step asks for. This page lists every step as text, so you can also follow along here.
The first tutorial uses the WS-1 Weather Station, as the LML tutorials do. The others build parts of a hybrid car, the model of the Hybrid Car demo: value types and components, the powertrain's ports and interfaces, a drive cycle, the powertrain's states, the car's requirements, their verification, the checks on the sedan's values and the product line. Each tutorial has its own starter project, so you can take them in any order. Every starter project and every finished tutorial checks with 0 problems.
| Tutorial | Time | You learn to |
|---|---|---|
| Getting Started | 15 min | write SysML v2 text, see it as a tree and a view, draw in the view and add a requirement |
| Definitions and Attributes | 20 min | write enumerations, value types and abstract definitions, specialize with values and units, and use completion, Insert and rename |
| Ports and Interfaces | 20 min | define ports and interfaces, conjugate ports, connect parts and draw an interface in an Interconnection View |
| Actions and Flows | 20 min | write action definitions and a drive cycle with a fork, flows and a join, add swim lanes and build steps in the FFBD |
| States and Transitions | 20 min | write signals and a state machine with triggers, guards and state actions, and draw a timed transition |
| Requirements | 20 min | write limits, requirement definitions and usages, satisfy them and see a requirement that is not met |
| Verification and Traceability | 15 min | write a verification case, trace a step in the Traceability Matrix and derive a requirement |
| Constraints and Calculations | 20 min | write constraints and calculations, bind values in a Parametric View, run an analysis case and mark TBD and TBR values |
| Variants and Configurations | 15 min | write variations and variants, a product line with a rule, configurations and a keyword of your own |
How to use it
Start a SysML v2 tutorial
- Open Help → Tutorials in the rail, or press ⌘K / Ctrl+K and type
tutorial. Outside a project the Tutorials page lists the LML tutorials first, then Tutorials for SysML v2 projects. Inside a SysML v2 project it lists only the SysML v2 tutorials. - Click Start on a card. Holarch creates the project, for example Tutorial: SysML v2 Ports and Interfaces (Hybrid Car), and opens it with the step panel on the right.
The step panel works as in the LML tutorials: Show Me outlines the control a step needs, Go There opens the page, Read more opens the Help topic, and Restart…, Mark as Done and × work the same way. See Tutorials.
Type the text of a step
Most steps give SysML text to type in Model → Editor. The step says where the lines go, for example "before the last closing brace of the package". The text is applied to the model when you pause typing; the status under the editor says so, and the step turns green.
- Type the lines as shown. The indentation does not matter to the model; the Editor keeps yours.
- A red underline marks an error: point at it to read the message. Text with a syntax error stays a draft and is not applied until you fix it.
- ⌘Z / Ctrl+Z undoes the last applied change.
Tips
- Take the tutorials in order the first time: each one explains the text it uses, and later ones assume the earlier ideas (definitions and usages,
:>and:>>). - A step that stays open usually has a typo in a name. Compare your text with the step's lines; names are case-sensitive in SysML v2.
- The tutorials teach the same language as SysML v2 Basics; the Textual Notation page has the details.
Getting Started
Write a first model of the Weather Station: open the text, add a part definition with a value and a unit, use it in another definition, see the model in the Browser and a General View, draw a part in the view and watch it appear in the text, add a requirement with satisfy, and export the model as a .sysml file. The steps are described on Getting Started with SysML v2 Projects.
Definitions and Attributes
The starter project has the package Vehicles with one part definition, Car.
- Open the package. Click Model → Editor. Every declaration is a keyword and a name, then a body in braces or a semicolon.
- Write an enumeration. Above
part def Car {, addenum def DriveMode { enum economy; enum normal; enum sport; }(one value per line). - Define a value type. Below it, add
attribute def TirePressure :> ScalarValue;.:>means specializes. - Write an abstract definition. Add
abstract part def Componentwith adoccomment and the attributesmass : MassValue,partNumber : Stringandpower : PowerValue.//starts a note that stays in the text only. - Let the checker find a mistake. Add
part def Battery :> Componentwithattribute redefines mass = 45 [kg];and, on purpose,attribute redefines power = 60 [kg];. The checker underlines the unit: kilograms are not a power. - Fix the unit. Change it to
60 [W]. - Complete a name. In the battery, type
attribute capacity : Ener, acceptEnergyValuefrom the completion list with Enter and end with;. - Look it up in the Standard Library. Click Settings → Standard Library at the bottom of the rail and type
EnergyValuein the find box. - Insert a definition. In the Editor, press ⌃⇧Space / Ctrl+Shift+Space (or click Insert ▾) on an empty line, choose Part Definition and complete
part def Engine :> Componentwithattribute redefines mass = 110 [kg];andattribute cylinders : Integer;. - Use the definitions. In
Car, addattribute mode : DriveMode;,part battery : Battery;andpart engine : Engine;. - Rename everywhere. Place the cursor on
cylinders, press F2 and rename it tocylinderCount.
Ports and Interfaces
The starter project has the components of the powertrain with their torque and power ports, the port definitions TorquePort and PowerPort, and the interface definitions Shaft and HighVoltageBus.
- Define a port. Above
port def TorquePort, addport def FuelPortwithout attribute flowRate : Real;andattribute kind : FuelKind;.outmeans the value leaves the part that owns the port. - Give parts their ports. Add
port fuelOut : FuelPort;toFuelTankandport fuelIn : ~FuelPort;toEngine.~conjugates the port: in and out are reversed. - Define an interface. Add
interface def FuelLine { end supply : FuelPort; end consumer : ~FuelPort; }. - Build the powertrain. At the end of the package, add
part def Powertrainwith the partstank,engine,motor,batteryandtransmission, a portoutput : TorquePortandbind output = transmission.output;. - Connect two parts. In the powertrain, add
interface fuel : FuelLine connect tank.fuelOut to engine.fuelIn;. - Add the shafts. Add
interface engineShaft : Shaft connect engine.output to transmission.engineIn;andinterface motorShaft : Shaft connect motor.output to transmission.motorIn;. - Create an Interconnection View. Click Architecture → Interconnection Views, then + New Diagram. Choose
Powertrainunder Shows and click Create. - Draw an interface. Drag from the handle of the battery's port
powerOutto the motor's portpowerIn, and drop on Interface : HighVoltageBus. - Name the interface. Select the new line and enter
hvBusas its Name in the inspector. - See it in the text. Click Model → Editor: the interface is in the powertrain, with its name, type and ends.
Actions and Flows
The starter project has the package VehicleBehavior with the items Fuel and Torque, the functions ProduceTorque (F.2) and DriveWheels (F.3), and three part definitions.
- Define a function. Add
action def <'F.1'> SupplyFuelwithin attribute fuelDemand : Real;andout item fuel : Fuel;. The short name in angle brackets is the function number. - Write the drive cycle. Add
action def <'F'> DriveCyclewithfirst start then split;,fork split;,then supply;,then produce;and the stepsaction supply : SupplyFuelandaction produce : ProduceTorque, each with aduration. - Add a flow. In the drive cycle, add
flow of Fuel from supply.fuel to produce.fuel;. - Join the branches. Add
first supply then ready;,first produce then ready;,join ready;,then action drive : DriveWheels { … },then done;andflow produce.torque to drive.torque;. - Create an Action Flow View. Click Behavior → Action Flows, then + New Diagram, and choose
DriveCycleunder Shows. - Say who performs each step. Add
part def DrivenCarwithperform action trip : DriveCycle;and the partstank,engineandtransmission, each withperform trip.supply;,perform trip.produce;orperform trip.drive;. The view gets a swim lane per part. - Open Functional Analysis. Click Behavior → Functional Analysis, click Choose… and pick
DriveCycle. - Declare another action. Add
action def EmergencyShutdown;. - Build steps in the FFBD. Click Behavior → FFBD, then + New Diagram, and choose
EmergencyShutdown. In the Add panel, typeOpen Contactorsand press Enter, thenCut Fuel. - See the steps in the text. Click Model → Editor: the FFBD wrote the steps and their successions.
States and Transitions
The starter project has the package PowertrainBehavior with an empty part def Car.
- Define the signals. Add
attribute def StartRequest;,StopRequest,PlugInandUnplugthe same way. - Write a state definition. Add
state def PowertrainStateswithin attribute charge : Real;,entry; then off;and the statesoff,electricandhybrid. - Add transitions. After
state off;, addaccept StartRequest if charge > 20 then electric;andaccept StartRequest then hybrid;. - Give a state its actions. Replace
state electric;with a body holdingentry action spinUpMotor;,do action driveElectric;andexit action holdMotor;. - Leave the electric state. After it, add
if charge < 15 then hybrid;andaccept StopRequest then off;; addaccept StopRequest then off;afterstate hybrid;too. - Add a state with named transitions. Add
state charging { do action chargeBattery; },transition plugIn first off accept PlugIn then charging;andtransition unplugged first charging accept Unplug then off;. - Create a State Transition View. Click Behavior → State Machines, then + New Diagram, and choose
PowertrainStatesunder Shows. - Draw a timed transition. Drag from the handle of
chargingtooffand drop on Transition. In the transition panel, enter the Namechargedand the Triggerafter 30 [min]. - See it in the text. Click Model → Editor: the transition is written as a named transition.
- Let the car exhibit the states. In
Car, addexhibit state powertrainStates : PowertrainStates;.
Requirements
The starter project has the package VehicleRequirements with a small copy of the design: Battery, Car and the fleet's sedan with a curb mass of 1580 kg.
- Name the limits. Add
attribute maxCurbMass : MassValue = 1650 [kg];andattribute minBatteryCapacity : EnergyValue = 1.2 [kW*h];. - Write a requirement definition. Add
requirement def <'VR-1'> CurbMasswith adocstatement,subject car : Car;,attribute limit : MassValue;andrequire constraint { car.curbMass <= limit }. - Insert a requirement. Press ⌃⇧Space / Ctrl+Shift+Space on an empty line, choose Requirement Definition and write
VR-3 BatteryCapacitywith the subjectbattery : Batteryandrequire constraint { battery.capacity >= minBatteryCapacity }. - Nest requirements in a specification. Add
requirement carSpecwithsubject car : Car;andrequirement <'VR-1.1'> sedanMass : CurbMass { attribute :>> limit = maxCurbMass; }. - Say what satisfies them. Add
satisfy carSpec by fleet.sedan;andsatisfy requirement batterySpec : BatteryCapacity by fleet.sedan.battery;. - Break a requirement. Change the sedan's curb mass to
1700 [kg]. The Editor marks the satisfy: the sedan no longer meets VR-1.1. - Meet it again. Press ⌘Z / Ctrl+Z, or change it back to
1580 [kg]. - See the requirements table. Click Needs & Requirements → Requirements.
- Create a Requirement View. On the Diagrams page, click + New Diagram, choose Requirement View and
carSpecunder Shows. - Check the statements. Click Needs & Requirements → Quality and click Check Quality.
Verification and Traceability
The starter project has the curb mass requirement and the car specification, a drive cycle with the steps cruise and brake, VR-6 batteryMassLimit and VR-7 stopFromCruise.
- Write a verification case. Add
verification def <'VC-1'> CurbMassTestwithsubject car : Car;,objective massObjective { verify carSpec.sedanMass; }andreturn verdict : Boolean = car.curbMass <= maxCurbMass;. - Apply it to the sedan. Add
verification <'VC-1.1'> sedanWeighing : CurbMassTest { subject car = fleet.sedan; }. - Open the verification cases. Click Verification → Verification Cases. Steps, results and status are Holarch data next to the model. In the row of Sedan Weighing, click + Steps, then + Add Step, type
Weigh the carunder Action and click Apply. Then click Passed in its status buttons. - Read the RVTM. Click Verification → RVTM.
- Trace a step to a requirement. Click Verification → Traceability Matrix, show requirements as rows and actions as columns, click the cell of
stopFromCruiseandbrake, and choose satisfied by. - Derive a requirement. Add
private import RequirementDerivation::*;andconnection batteryMassDerivation : Derivation connect carSpec.sedanMass to batteryMassLimit;. - Run the model checks. Click Verification → Model Checks.
Constraints and Calculations
The starter project has the package VehicleAnalysis with the engine, battery, car and the sedan's values, and the targets maxCurbMass and minPowerToWeight.
- Write a constraint definition. Add
constraint def MassLimitwithin mass : MassValue;,in limit : MassValue;and the expressionmass <= limit. - Write a calculation. Add
calc def PowerToWeightwith the parameterspowerandmassandreturn ratio = power / mass;. - Bind the sedan's values. Add
constraint sedanMassCheck : MassLimit { in mass = fleet.sedan.curbMass; in limit = maxCurbMass; }. - Create a Parametric View. On the Diagrams page, click + New Diagram, choose Parametric View and
VehicleAnalysisunder Shows. The check passes: 1580 kg is within 1650 kg. - Make the check fail. Change the sedan's curb mass to
1700 [kg]; the view shows the check failing. - Make it pass again. Undo, or change it back to
1580 [kg]. Solve All checks every constraint again. - Run an analysis case. Add
analysis def PowerToWeightAnalysiswith an objective that requiresratio >= minPowerToWeight, andanalysis sedanPowerToWeight : PowerToWeightAnalysis { subject car = fleet.sedan; }. - Mark open values. Add
private import HolarchMetadata::*;and the requirement VR-5ChargeTimewith#TBRon its time limit and@TBDwith an owner, a due date and a rationale on the charger power.TBDandTBRcome from Holarch'sHolarchMetadatalibrary, not the SysML v2 standard library; they specialize the standardStatusInfometadata. - Open the TBD/TBR register. Click Needs & Requirements → TBD/TBR. The charge time is listed with the owner and due date of its
@TBDmetadata. The register is read-only: change the owner or date in the metadata in the Editor. - Roll up the mass. Click Architecture → Budgets & TPMs and select the root part
sedan.
Variants and Configurations
The starter project has Component, Battery, Controller, Car and Powertrain.
- Import the variability package. Add
private import HolarchVariability::*;. - Write a variation. On an empty line, press ⌃⇧Space / Ctrl+Shift+Space (or click Insert ▾), choose Variation and complete
variation part def BatteryPack :> Batterywith the variantsstandardPack(1.4 kWh) andlargePack(12 kWh, 120 kg). - Write the product line. Add
part def CarLine :> Carwithpart pack : BatteryPack;, avariation part chargerwith the variantsnoChargerandwallbox, andassert constraint wallboxNeedsLargePack { charger == charger::wallbox implies pack == BatteryPack::largePack }. - Start a configuration. Choose Insert ▾ → Configuration and fill in
part plugInHybrid : CarLine { @HolarchConfiguration; }. The Editor notes the variation points still open. - Choose the variants. In
plugInHybrid, choose Insert ▾ → Variant Choice for each point and fill inpart :>> pack = BatteryPack::largePack;andpart :>> charger = charger::wallbox;. - Add a second configuration. Add
selfChargingHybridthe same way, with the standard pack and no charger. - Define a keyword of your own. Add
metadata def <safetyCritical> SafetyCritical. - Use the keyword. In
Powertrain, write#safetyCritical part controller : Controller;. - See the product line. Create a General View of
Vehicles: the battery pack is marked variation.
Tutorial projects
SysML v2 tutorial projects follow the same rules as the other tutorial projects: they do not count toward your plan's active projects, hold up to 300 items, and you can have one per tutorial. See Tutorials.
Related
- Tutorials
- Getting Started with SysML v2 Projects
- The Text Editor and Browser
- Textual Notation
- Views
- Requirements in SysML v2 Projects
SysML® and OMG® are registered trademarks of Object Management Group, Inc. in the United States and other countries.