Evaluation, Units and Analysis in SysML v2 Projects

Overview

A SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project computes with the values in its model. Attribute values carry units, such as 1580 [kg] or 72 [kW], and Holarch evaluates them with those units. The analysis pages read the evaluated values:

These are the same pages as in LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. projects. Only their data comes from the SysML v2 model. This page explains what each one reads from the model and what it writes back. For the full page reference, see the LML pages linked under Related pages.

Concepts

Values with units

An attribute usage can bind a value: attribute redefines mass = 45 [kg];. The value is an expression. It can be a number with a unit, a name of another feature, or arithmetic such as capacity / drivePower * cruiseSpeed.

• Units come from the SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 standard library (SI::kg, SI::kW, SI::h). Compound units are written in the brackets: [kW*h], [W/kg], [km/h].
• A plain number without a unit is a number.
• The type gives the quantity kind: attribute curbMass : MassValue; declares a mass. Import ISQ::* and SI::* to use these names without a prefix.

Evaluation

Holarch's SysML checker evaluates expressions with the model:

• Literals, arithmetic and comparison operators.
• Quantity arithmetic with dimensions, and conversion between library units (1 [min] is 60 [s]).
• Names and feature chains such as fleet.sedan.curbMass, through definitions, specializations and redefinitions.
• Calculation definitions called with arguments, and the truth of constraints.

A value that names an unknown feature, or mixes dimensions that do not match, does not evaluate. The Editor marks unit problems, such as "The units do not match: … Convert one side to a compatible unit."

Redefinitions replace inherited values

A part inherits the attributes of its definition and of the definitions that definition specializes. A redefinition replaces the inherited value. In the Hybrid Car demo, Component declares attribute mass : MassValue;, Battery sets attribute redefines mass = 45 [kg];, and the sedan's own battery sets attribute redefines mass = 48 [kg];. The sedan's battery therefore weighs 48 kg; every other battery weighs 45 kg.

Model data and Holarch data

Values that belong to the system are written into the model text. Settings that only the analysis pages use are Holarch data, stored next to the model and never written into the text:

Every write to the model is one undo step and shows in the text at once.

How to use it

When and why

Use these pages once the structure and its values exist in the model:

• Parametric View: check the design against its constraints, and compute dependent values.
• Budgets & TPMsTechnical Performance Measure A key technical parameter, such as mass or power, tracked over time against its target and threshold.: track mass, power or another quantity against allocations as the design matures, and record TPMs at each review.
• Trade Studies: compare variant designs on weighted criteria before a decision.
• Simulator: estimate how long a behavior takes and how likely it meets a timing requirement.

All four connect to requirements. A requirement's require constraint gives a criterion. Constraints in a Parametric View check values against limits. Check Against Requirement records the result on a verification case.

See an evaluated value

1. Select an attribute usage in a view, the Browser or a table.
2. Read the Value field in the Features section of the inspector.

   Below the field, you see "Evaluates to 1580 kg" (or the computed result for an expression). For a value that names another element, it says "Refers to" and the element's qualified name.

3. To change the value, edit the field and press Enter. The selector before it chooses = (binds the value) or := (sets an initial value).

Check constraints in a Parametric View

1. Open the Diagrams tool and click + New Diagram.
2. Choose Parametric View and the package it shows. Click Create.

   You see each constraint with its expression, its parameters as pins on its bottom edge, and the values they bind to below it.

3. Read the badge on each constraint:
   • Pass: the constraint holds for the bound values.
   • Fail: the constraint does not hold for the bound values.
   • Needs input: a parameter has no value yet. Bind every parameter to a value.
4. To bind a parameter, drag from its pin to a value. The parameter's value becomes the value's name, such as in mass = fleet.sedan.curbMass;.
5. To remove a binding, select the binding line and press Delete.

Solve values

1. In a Parametric View, click Solve All to solve every constraint in the view. To solve one, select the constraint (or one of its parameters) and click Solve.

   The Solve All Constraints (or Solve Constraint) dialog lists the values that will change, with the Current and New values and How each was found: Computed or Solved for input. Below it, each constraint shows its state: Computed, Solved for input, Pass, Fail, Needs input or Error.

2. Click Apply N Changes.

   The values are written into the model as one undo step. The toast reads "Updated N values".

Solve computes a value that an equation defines (q == s * s), solves a single unknown and checks inequalities, all with units. It writes only values that are numbers or empty. A value written as an expression stays as it is.

Roll up a budget

1. Open Architecture → Budgets & TPMs.
2. Click Select Root Part… and choose a part usage or a part definition.
3. Under Quantity, enter the attribute name. Mass reads mass, Power reads power, Power Draw reads powerDraw. The list offers the names of attributes that have values.

   You see the part tree: the part's own parts, then the parts its definitions bring. A part that redefines an inherited one replaces it.

4. Set the Unit, Required margin and Contingency by basis, then the Basis and Allocation of each line.
5. To change a value, type it in the Unit Value column, such as 48 kg.

   Holarch writes it as 48 [kg] where the attribute is declared. If the part only inherits the attribute, Holarch adds a redefining attribute to the part.

6. To change how many of a part there are, type in the Count column. It sets the part's multiplicity.
7. Click Export XLSX to export the budget.

Track a TPM

1. Open the TPMs tab of Budgets & TPMs.
2. Select a Measure with the TPM label. Its current estimate, threshold, objective, planned profile and history show as in LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. projects.
3. To link a Measure to the parts it measures, open it and use Link existing… in its Trace section.

Measures are Holarch items, not model elements.

Run a trade study

1. Open Risk & Decisions → Trade Studies and click + New Trade Study.
2. Under Alternatives, click + Existing… to add part definitions or usages of the model, such as variant part definitions. + New creates a part definition and its part.
3. Add criteria with + Criterion. Name each one after the attribute it reads: the criterion Top Speed reads topSpeed.
4. Click Pull Values from Model.

   Each cell gets the alternative's attribute of that name, evaluated with units and converted to the criterion's units. Without such an attribute, the cell gets the roll-up of that quantity over the alternative's parts, as on the Budget tab.

5. Enter the remaining values by hand, set weights and scoring methods, and read the ranking, the Pugh matrix and the sensitivity.
6. Click Record Decision… to record the chosen alternative.

The links to alternatives point to the elements themselves, so they stay when an element is renamed or moved.

Simulate an action flow

1. Open an Action Flow View and choose ▶ Simulate ▾ → Discrete Event or Monte Carlo. Or open Behavior → Simulator and choose the root action: an action definition or usage with its own actions.
2. Set the simulator settings: Decisions, Speed, Vary fixed durations and ± %, Random seed, Calendar Dates and Start paused (step through) for Discrete Event; Runs for Monte Carlo. They are saved with the root action.
3. Press ▶ Play, ⏭ Step or ⏩ Run to End (Discrete Event), or run the Monte Carlo study.

   The timeline shows each step as it runs. Action flow as it runs highlights the steps in the Action Flow View that shows the action.

How the model maps to the simulation is listed under How the Simulator reads the model.

Check a simulation against a requirement

1. Write the criterion as a requirement's require constraint in the text, for example require constraint { tripTime <= 120 [s] }.
2. Run a Monte Carlo study, then click Check Against Requirement… and choose the requirement.

   Holarch takes the criterion from the require constraint. The model evaluates the limit (120 s) and checks the constraint at the mean of the runs.

3. Click Record Result…. It sets the status and result of a verification case that verifies the requirement, or creates one, in one undo step.

Worked example: the Hybrid Car demo

Create the demo first: on Manage Projects, click Project Files ▾ → New Demo Project → Hybrid Car (SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2).

Constraints. Open the Diagrams tool and open the view sedanParametrics. It shows two constraints from the package VehicleViews:

constraint sedanMassCheck : MassLimit {
  in mass = fleet.sedan.curbMass;
  in limit = maxCurbMass;
}

MassLimit states mass <= limit. The sedan's curb mass is 1580 kg and maxCurbMass is 1650 kg, so sedanMassCheck shows Pass. sedanBatteryCheck compares the sedan battery's capacity, 1.4 kWh, with minBatteryCapacity, 1.2 kWh, and also passes.

1. In the Editor, open Vehicles and change the sedan's attribute redefines curbMass = 1580 [kg]; to 1700 [kg].
2. Return to sedanParametrics.

   sedanMassCheck now shows Fail. Press ⌘Z / Ctrl+Z to undo the change.

Budget. Open Architecture → Budgets & TPMs. The demo has the sedan (fleet.sedan) as root and Mass as quantity.

• The tree lists the body, the powertrain's tank, engine, motor, battery, transmission and controller, and both axles with their differential and two wheels. The spare wheel counts 1, the upper bound of [0..1].
• The battery shows 48 kg, the sedan's own redefinition, not the 45 kg of Battery.
• The sedan has an allocation of 1650 kg and the powertrain 360 kg; the engine's basis is Calculated and the battery's Measured.
• Switch Quantity to Power to see the electrical load budget, with an allocation of 2000 W.

On the TPMs tab, Sedan Curb Mass (TPM-1) and Sedan Electrical Load (TPM-2) show their planned profiles and history.

Trade study. Open Risk & Decisions → Trade Studies and select Launch Variant Selection (TR-1). Its alternatives are the part definitions SportCar and CityCar.

• Top Speed comes from their topSpeed attributes: 210 km/h and 160 km/h.
• Mass has no attribute of that name on the variants, so it is the roll-up of their parts. CityCar is lighter because its body redefines mass = 780 [kg].
• Purchase Price and Driving Fun were entered by hand. The recorded decision chose CityCar.

Simulation. Open the view driveCycleFlow (DriveCycle in VehicleBehavior) and choose ▶ Simulate ▾ → Monte Carlo.

• Each step takes its duration attribute: supply 3 s and produce 4 s in parallel, accelerate 12 s, cruise 1 min, brake 8 s, and drive 75 s alongside them.
• The decision shift guards cruise with speed > 30. The model cannot evaluate speed before the run, so the demo sets the branch probabilities on the successions: cruise 70 %, else 30 %.
• The demo's study settings are 200 runs, ±10 % uniform variation of fixed durations, and seed 42.

Tips and good practice

• Give every value a unit. 48 [kg] rolls up, converts and checks. A bare 48 on a MassValue is marked as a problem: "Add a unit, for example 5 [kg]."
• Declare an attribute once on a general definition (Component::mass) and redefine its value on each specialization. Budgets and trade studies then find it by name everywhere.
• Name trade study criteria after attributes ("Top Speed" for topSpeed) so Pull Values from Model fills them.
• Keep requirement limits as named attributes (maxCurbMass) and bind constraints to them. One edit then updates every check.
• Use Solve on one constraint before Solve All in a large view, so you can review the changes in small sets.

Common mistakes

• A constraint shows Needs input. A parameter has no bound value, or the value it names has none. Drag from the parameter's pin to a value, or give the value a number.
• The budget shows no values. The message reads "No part under <root> has a value for "<quantity>". Enter values in the Unit Value column, or give the part definitions an attribute <name> with a value." Check the attribute's name: Power Draw reads powerDraw, not power_draw.
• A budget line has a warning instead of a value. The attribute's value does not evaluate to a number with units, for example because it names a feature that does not exist. Fix the value in the Editor.
• Solve All does not change a value. The value is an expression, not a number. Solve writes only numbers or empty values.
• Check Against Requirement finds no criterion. The requirement needs a require constraint that compares one unknown value with a known limit, such as tripTime <= 120 [s].

How it connects to other features

• Requirements: a requirement's require constraint gives the criterion for Check Against Requirement. When a value or constraint a requirement names changes, its links become suspect (see Requirements and Verification in SysML v2 Projects).
• Verification: Record Result… sets the status and result of a verification case; the RVTMRequirements Verification Traceability Matrix A table of each requirement with how it is verified, the tests that verify it and their latest result. shows it.
• Views: the Parametric View and the Action Flow View are views of the model (see SysML v2 Views).
• Documents: live values show attribute values with their units, such as 1650 [kg].
• Decisions: Record Decision… creates the decision on the Decisions page.

Parametric View reference

The Parametric View is a General View with the filter @SysML::ConstraintDefinition or @SysML::ConstraintUsage. It is drawn like the LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. Parametric Diagram.

What it shows

• Constraints: each constraint usage with its expression (its own, or its definition's) and its name.
• Parameters: pins on the constraint's bottom edge, labelled with their name and value. In, out and in-and-out parameters are marked.
• Bound values: a value that a parameter names. It appears inside its part when it belongs to one, or on its own for a package-level value such as maxCurbMass.
• Binding lines: from each parameter to the value it binds to.

Toolbar

Add panel

Each addition is one undo step and is written into the text.

Badges and states

Budgets & TPMs in SysML v2 projects

The page is the LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. Budgets & TPMsTechnical Performance Measure A key technical parameter, such as mass or power, tracked over time against its target and threshold. page; see Budgets & TPMs for every control, tile and column. In a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project it differs as follows.

Part tree

• Root: a part usage or part definition, chosen with Select Root Part….
• Lines: the part's own part usages, then the parts its definitions bring (typed by, specializes) and the parts of the features it redefines. A part that redefines an inherited one replaces it, so part redefines battery { … } counts once, with its own values.
• Count: the part's multiplicity. [2] counts 2, a range such as [0..1] counts its upper bound, and [0] counts nothing. Without a multiplicity, a redefining part takes the multiplicity of the part it redefines; otherwise it counts 1.

Values

• Unit Value: the attribute with the quantity's name, the part's own or redefining attribute first, then the inherited one. It is evaluated by the model with its units.
• Leaves contribute their own value × count. A part with valued parts shows the sum of its parts.
• Editing Unit Value writes the bound value where the attribute is declared, or adds a redefining attribute to the part. A plain number takes the budget's unit.
• Editing Count sets the part's multiplicity.

Messages

Trade Studies in SysML v2 projects

The page is the LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. Trade Studies page; see Risk and Decisions. In a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project:

• The study, its decision and its criteria (Measures) are Holarch items.
• + Existing… lists the model's part definitions and usages, and Holarch items. + New asks for a name and creates a part definition and its part.
• Pull Values from Model fills each cell from the alternative's attribute with the criterion's name, evaluated by the model and converted to the criterion's units. Without such an attribute, it takes the roll-up (current best estimate) of that quantity over the alternative's parts.
• Weights, scoring methods, the Pugh matrix, sensitivity and Record Decision… work as in LML projects.

How the Simulator reads the model

The Simulator is the LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. Simulator; see Simulation for the page, its panels and Monte Carlo statistics. In a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project it reads the model as follows.

Steps and order

Durations

A step takes the time of its attribute duration, or of an attribute typed DurationValue or TimeValue, its own or its definition's: attribute duration : DurationValue = 5 [s];.

Select the step to set a Duration in the simulator instead, also as a distribution. It takes precedence over the model's value. The inspector's Simulation section says where the duration comes from:

• "From the model: <value> (attribute duration)."
• "This duration is used in the simulator. Clear it to use the model's."
• "No duration in the model. Set one here, or write attribute duration : DurationValue = 5 [s]; in the text."
• For an action with its own flow: "Its steps take the time: simulated through its own flow."

Decisions and loops

Guards, if conditions and loop conditions that the model can evaluate decide on their own. The inspector then says "Evaluates to true: always taken." or "Evaluates to false: never taken."

Otherwise, set the numbers in the inspector's Simulation section:

These settings are Holarch data, stored with the project, not in the text. When the branch probabilities of a decision do not total 100 %, the warning reads "Branch probabilities add up to N %. Change them to total 100 %."

Check Against Requirement messages

Limits

• State machines are not simulated yet; only action flows run.
• Solve All writes only literal values (numbers, with or without units). Values written as expressions are not overwritten.
• 3D geometry is not drawn or evaluated.

Related pages

• SysML v2 Views: the Parametric View and the Action Flow View.
• Requirements and Verification in SysML v2 Projects: require constraints, verification cases and suspect links.
• SysML v2 Textual Notation: attributes, units and constraints in the text.
• Budgets & TPMs, Simulation and Risk and Decisions: the full page references.
• Holarch Features in SysML v2 Projects.

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams.® and OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI.® are registered trademarks of Object Management Group, Inc. in the United States and other countries.