Holarch

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.

How to use it →

On this page
  1. How to use it
    1. Start a SysML v2 tutorial
    2. Type the text of a step
    3. Tips
  2. Getting Started
  3. Definitions and Attributes
  4. Ports and Interfaces
  5. Actions and Flows
  6. States and Transitions
  7. Requirements
  8. Verification and Traceability
  9. Constraints and Calculations
  10. Variants and Configurations
  11. Tutorial projects
  12. Related

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.

TutorialTimeYou learn to
Getting Started15 minwrite SysML v2 text, see it as a tree and a view, draw in the view and add a requirement
Definitions and Attributes20 minwrite enumerations, value types and abstract definitions, specialize with values and units, and use completion, Insert and rename
Ports and Interfaces20 mindefine ports and interfaces, conjugate ports, connect parts and draw an interface in an Interconnection View
Actions and Flows20 minwrite action definitions and a drive cycle with a fork, flows and a join, add swim lanes and build steps in the FFBD
States and Transitions20 minwrite signals and a state machine with triggers, guards and state actions, and draw a timed transition
Requirements20 minwrite limits, requirement definitions and usages, satisfy them and see a requirement that is not met
Verification and Traceability15 minwrite a verification case, trace a step in the Traceability Matrix and derive a requirement
Constraints and Calculations20 minwrite constraints and calculations, bind values in a Parametric View, run an analysis case and mark TBD and TBR values
Variants and Configurations15 minwrite 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

  1. 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.
  2. 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.

  1. Open the package. Click Model → Editor. Every declaration is a keyword and a name, then a body in braces or a semicolon.
  2. Write an enumeration. Above part def Car {, add enum def DriveMode { enum economy; enum normal; enum sport; } (one value per line).
  3. Define a value type. Below it, add attribute def TirePressure :> ScalarValue;. :> means specializes.
  4. Write an abstract definition. Add abstract part def Component with a doc comment and the attributes mass : MassValue, partNumber : String and power : PowerValue. // starts a note that stays in the text only.
  5. Let the checker find a mistake. Add part def Battery :> Component with attribute redefines mass = 45 [kg]; and, on purpose, attribute redefines power = 60 [kg];. The checker underlines the unit: kilograms are not a power.
  6. Fix the unit. Change it to 60 [W].
  7. Complete a name. In the battery, type attribute capacity : Ener, accept EnergyValue from the completion list with Enter and end with ;.
  8. Look it up in the Standard Library. Click Settings → Standard Library at the bottom of the rail and type EnergyValue in the find box.
  9. 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 :> Component with attribute redefines mass = 110 [kg]; and attribute cylinders : Integer;.
  10. Use the definitions. In Car, add attribute mode : DriveMode;, part battery : Battery; and part engine : Engine;.
  11. Rename everywhere. Place the cursor on cylinders, press F2 and rename it to cylinderCount.

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.

  1. Define a port. Above port def TorquePort, add port def FuelPort with out attribute flowRate : Real; and attribute kind : FuelKind;. out means the value leaves the part that owns the port.
  2. Give parts their ports. Add port fuelOut : FuelPort; to FuelTank and port fuelIn : ~FuelPort; to Engine. ~ conjugates the port: in and out are reversed.
  3. Define an interface. Add interface def FuelLine { end supply : FuelPort; end consumer : ~FuelPort; }.
  4. Build the powertrain. At the end of the package, add part def Powertrain with the parts tank, engine, motor, battery and transmission, a port output : TorquePort and bind output = transmission.output;.
  5. Connect two parts. In the powertrain, add interface fuel : FuelLine connect tank.fuelOut to engine.fuelIn;.
  6. Add the shafts. Add interface engineShaft : Shaft connect engine.output to transmission.engineIn; and interface motorShaft : Shaft connect motor.output to transmission.motorIn;.
  7. Create an Interconnection View. Click Architecture → Interconnection Views, then + New Diagram. Choose Powertrain under Shows and click Create.
  8. Draw an interface. Drag from the handle of the battery's port powerOut to the motor's port powerIn, and drop on Interface : HighVoltageBus.
  9. Name the interface. Select the new line and enter hvBus as its Name in the inspector.
  10. 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.

  1. Define a function. Add action def <'F.1'> SupplyFuel with in attribute fuelDemand : Real; and out item fuel : Fuel;. The short name in angle brackets is the function number.
  2. Write the drive cycle. Add action def <'F'> DriveCycle with first start then split;, fork split;, then supply;, then produce; and the steps action supply : SupplyFuel and action produce : ProduceTorque, each with a duration.
  3. Add a flow. In the drive cycle, add flow of Fuel from supply.fuel to produce.fuel;.
  4. Join the branches. Add first supply then ready;, first produce then ready;, join ready;, then action drive : DriveWheels { … }, then done; and flow produce.torque to drive.torque;.
  5. Create an Action Flow View. Click Behavior → Action Flows, then + New Diagram, and choose DriveCycle under Shows.
  6. Say who performs each step. Add part def DrivenCar with perform action trip : DriveCycle; and the parts tank, engine and transmission, each with perform trip.supply;, perform trip.produce; or perform trip.drive;. The view gets a swim lane per part.
  7. Open Functional Analysis. Click Behavior → Functional Analysis, click Choose… and pick DriveCycle.
  8. Declare another action. Add action def EmergencyShutdown;.
  9. Build steps in the FFBD. Click Behavior → FFBD, then + New Diagram, and choose EmergencyShutdown. In the Add panel, type Open Contactors and press Enter, then Cut Fuel.
  10. 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.

  1. Define the signals. Add attribute def StartRequest;, StopRequest, PlugIn and Unplug the same way.
  2. Write a state definition. Add state def PowertrainStates with in attribute charge : Real;, entry; then off; and the states off, electric and hybrid.
  3. Add transitions. After state off;, add accept StartRequest if charge > 20 then electric; and accept StartRequest then hybrid;.
  4. Give a state its actions. Replace state electric; with a body holding entry action spinUpMotor;, do action driveElectric; and exit action holdMotor;.
  5. Leave the electric state. After it, add if charge < 15 then hybrid; and accept StopRequest then off;; add accept StopRequest then off; after state hybrid; too.
  6. Add a state with named transitions. Add state charging { do action chargeBattery; }, transition plugIn first off accept PlugIn then charging; and transition unplugged first charging accept Unplug then off;.
  7. Create a State Transition View. Click Behavior → State Machines, then + New Diagram, and choose PowertrainStates under Shows.
  8. Draw a timed transition. Drag from the handle of charging to off and drop on Transition. In the transition panel, enter the Name charged and the Trigger after 30 [min].
  9. See it in the text. Click Model → Editor: the transition is written as a named transition.
  10. Let the car exhibit the states. In Car, add exhibit 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.

  1. Name the limits. Add attribute maxCurbMass : MassValue = 1650 [kg]; and attribute minBatteryCapacity : EnergyValue = 1.2 [kW*h];.
  2. Write a requirement definition. Add requirement def <'VR-1'> CurbMass with a doc statement, subject car : Car;, attribute limit : MassValue; and require constraint { car.curbMass <= limit }.
  3. Insert a requirement. Press ⌃⇧Space / Ctrl+Shift+Space on an empty line, choose Requirement Definition and write VR-3 BatteryCapacity with the subject battery : Battery and require constraint { battery.capacity >= minBatteryCapacity }.
  4. Nest requirements in a specification. Add requirement carSpec with subject car : Car; and requirement <'VR-1.1'> sedanMass : CurbMass { attribute :>> limit = maxCurbMass; }.
  5. Say what satisfies them. Add satisfy carSpec by fleet.sedan; and satisfy requirement batterySpec : BatteryCapacity by fleet.sedan.battery;.
  6. 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.
  7. Meet it again. Press ⌘Z / Ctrl+Z, or change it back to 1580 [kg].
  8. See the requirements table. Click Needs & Requirements → Requirements.
  9. Create a Requirement View. On the Diagrams page, click + New Diagram, choose Requirement View and carSpec under Shows.
  10. 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.

  1. Write a verification case. Add verification def <'VC-1'> CurbMassTest with subject car : Car;, objective massObjective { verify carSpec.sedanMass; } and return verdict : Boolean = car.curbMass <= maxCurbMass;.
  2. Apply it to the sedan. Add verification <'VC-1.1'> sedanWeighing : CurbMassTest { subject car = fleet.sedan; }.
  3. 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 car under Action and click Apply. Then click Passed in its status buttons.
  4. Read the RVTM. Click Verification → RVTM.
  5. Trace a step to a requirement. Click Verification → Traceability Matrix, show requirements as rows and actions as columns, click the cell of stopFromCruise and brake, and choose satisfied by.
  6. Derive a requirement. Add private import RequirementDerivation::*; and connection batteryMassDerivation : Derivation connect carSpec.sedanMass to batteryMassLimit;.
  7. 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.

  1. Write a constraint definition. Add constraint def MassLimit with in mass : MassValue;, in limit : MassValue; and the expression mass <= limit.
  2. Write a calculation. Add calc def PowerToWeight with the parameters power and mass and return ratio = power / mass;.
  3. Bind the sedan's values. Add constraint sedanMassCheck : MassLimit { in mass = fleet.sedan.curbMass; in limit = maxCurbMass; }.
  4. Create a Parametric View. On the Diagrams page, click + New Diagram, choose Parametric View and VehicleAnalysis under Shows. The check passes: 1580 kg is within 1650 kg.
  5. Make the check fail. Change the sedan's curb mass to 1700 [kg]; the view shows the check failing.
  6. Make it pass again. Undo, or change it back to 1580 [kg]. Solve All checks every constraint again.
  7. Run an analysis case. Add analysis def PowerToWeightAnalysis with an objective that requires ratio >= minPowerToWeight, and analysis sedanPowerToWeight : PowerToWeightAnalysis { subject car = fleet.sedan; }.
  8. Mark open values. Add private import HolarchMetadata::*; and the requirement VR-5 ChargeTime with #TBR on its time limit and @TBD with an owner, a due date and a rationale on the charger power. TBD and TBR come from Holarch's HolarchMetadata library, not the SysML v2 standard library; they specialize the standard StatusInfo metadata.
  9. Open the TBD/TBR register. Click Needs & Requirements → TBD/TBR. The charge time is listed with the owner and due date of its @TBD metadata. The register is read-only: change the owner or date in the metadata in the Editor.
  10. 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.

  1. Import the variability package. Add private import HolarchVariability::*;.
  2. Write a variation. On an empty line, press ⌃⇧Space / Ctrl+Shift+Space (or click Insert ▾), choose Variation and complete variation part def BatteryPack :> Battery with the variants standardPack (1.4 kWh) and largePack (12 kWh, 120 kg).
  3. Write the product line. Add part def CarLine :> Car with part pack : BatteryPack;, a variation part charger with the variants noCharger and wallbox, and assert constraint wallboxNeedsLargePack { charger == charger::wallbox implies pack == BatteryPack::largePack }.
  4. Start a configuration. Choose Insert ▾ → Configuration and fill in part plugInHybrid : CarLine { @HolarchConfiguration; }. The Editor notes the variation points still open.
  5. Choose the variants. In plugInHybrid, choose Insert ▾ → Variant Choice for each point and fill in part :>> pack = BatteryPack::largePack; and part :>> charger = charger::wallbox;.
  6. Add a second configuration. Add selfChargingHybrid the same way, with the standard pack and no charger.
  7. Define a keyword of your own. Add metadata def <safetyCritical> SafetyCritical.
  8. Use the keyword. In Powertrain, write #safetyCritical part controller : Controller;.
  9. 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.

SysML® and OMG® are registered trademarks of Object Management Group, Inc. in the United States and other countries.