SysML v2
Simulation Metadata in SysML v2 Projects
The HolarchSimulation metadata library: how a SysML v2 model carries durations, branch probabilities, loop counts, resources, costs and state machine settings for the Simulator, and how to write and move them.
Overview
In a SysML v2 project the Simulator's settings are part of the model. They are metadata annotations from the library package HolarchSimulation, which every SysML v2 project loads. A model that uses them stays valid SysML v2: other tools read the annotations as ordinary metadata, and only the Simulator gives them meaning.
An annotation either sits inside the element it annotates or names that element with about:
succession toCruise first shift if speed > 30 then cruise {
@HolarchSimulation::Probability { percent = 70; }
}
metadata HolarchSimulation::Cost about DriveCycle::drive { amount = 0.4; unit = "USD"; label = "Energy"; }
Concepts
Nominal value and distribution
A step's duration is its attribute duration (or an attribute typed DurationValue or TimeValue). Its value is the nominal duration that other tools and Holarch's evaluation see. A distribution annotation on that attribute makes the Simulator draw the duration instead:
action cruise {
attribute duration : ISQ::DurationValue = 1 [min] {
@HolarchSimulation::Triangular { low = 45 [s]; mode = 1 [min]; high = 2 [min]; }
}
}
Which settings win
- A distribution annotation wins over the attribute's own value.
- A guard,
ifcondition or loop condition that the model can evaluate decides on its own. A Probability or LoopCount is used only when it cannot (a LoopCount always counts the passes). - Settings made before simulation settings moved into the model are kept as Holarch data next to the model. They still win, so runs give the same results, until you move them in (see Move older settings into the model).
Two simulators
The Simulator page shows which simulator runs the model, at the right of the settings: SysML engine (the Holarch Language Engine's simulator) or JavaScript simulator. Both read the same annotations. State machines, stimuli, resources from Resource, Consumes, Produces and Seizes, costs from Cost, and the other annotations under Annotations that need the SysML engine run only with the SysML engine.
How to use it
When and why
Write simulation settings into the model when the model is the record of the design: the numbers travel with the .sysml files, appear in reviews of the text, and are versioned with the rest of the model. Use them while you analyze an operational scenario (timelines, branch shares, resource use) and before you check a requirement against a Monte Carlo study.
Set a duration, probability or loop count
- Select the step, succession, decision, loop or
ifaction on an Action Flow View, in the Browser or in the Editor. - In the inspector's Simulation section, set Duration (a fixed value or a distribution), Probability (%), Iterations or Probability of then (%).
- Holarch writes the annotation into the model: Duration sets the attribute's value to the mean and adds the distribution annotation (or writes
attribute duration : ISQ::DurationValuewhen the step has none); Probability (%) writes Probability; Iterations writes LoopCount. Each change can be undone with a single Undo and shows in the text at once. - Clear a field to remove its annotation.
Holarch checks each change with the SysML checker before it writes it. A change that would add an error is not written, and a message names the problem.
Write annotations in the text
- Open the Editor.
- Add the annotation inside the element's body, as
@HolarchSimulation::Kind { field = value; }, or after it, asmetadata HolarchSimulation::Kind about element { … }. - For Consumes, Produces and Seizes, name the step first and the resource second:
metadata HolarchSimulation::Consumes about DriveCycle::drive, DrivenCar::powertrain::battery { amount = 1.5; }.
Move older settings into the model
Projects whose simulation settings were made before they moved into the model show Some simulation settings of this project are Holarch data, not part of the model. above the Simulator's settings.
- Click Move Simulation Settings into the Model….
- The preview lists each setting and the annotation that replaces it.
- Click Move into the Model. All settings move, and a single Undo takes it all back; runs give the same results.
Simulate a state machine
State machines run with the SysML engine.
- Open Behavior → Simulator and choose a state definition, or a part that exhibits states, as Root.
- Optional: under Run together with, choose a scenario action that sends signals to the part, such as the demo's TestDrive.
- Under Stimuli, click + Add Stimulus and set At (time and unit), Signal and To (a machine, or Every machine that accepts it).
- Press ▶ Play, ⏭ Step or ⏩ Run to End. State machine as it runs lights the active states and marks the transition that fired; the States tab shows States over time and Transitions fired.
- In Monte Carlo, the States tab shows Time in state and Transition counts. Check Against Requirement… offers each state's time in state and share of the run as outputs.
On a State Transition View, ▶ Simulate opens a bar with ▶ Play, ⏭ Step, ⏩ Run to End, Reset and Open in Simulator. The run uses the stimuli saved on the Simulator for that state definition.
Worked example: the Hybrid Car demo
The Hybrid Car demo (Manage Projects → Project Files ▾ → New Demo Project) uses the library:
- DriveCycle: the succession
toCruiseaftershifthas Probability 70; theelsebranch takes the remaining 30 %.cruisetakes 1 min nominal, drawn from a Triangular distribution (45 s, 1 min, 2 min). - DrivenCar: the powertrain's battery is a Resource of 62 Wh;
driveConsumes 1.5 Wh of it and has a Cost of 0.4 USD per use. - PowertrainStates: the transition
startElectrichas Probability 80 for its guard;accept when charge < 15changes to hybrid when the charge drops;accept after 30 [min]ends charging. - TestDrive: a scenario that sends
StartRequest, waits an hour, then sendsStopRequestandPlugIntodemoCar. Run Demo Car together with Test Drive to see the powertrain change states.
The demo checks with 0 diagnostics.
Tips and good practice
- Keep the nominal value meaningful: set it to the expected value of the distribution, as the inspector does.
- Name successions you annotate (
succession toCruise first …), so the annotation is easy to find in the text. - Prefer conditions the model can evaluate over probabilities; use Probability for what the model does not describe.
Common mistakes
- A probability has no effect: the guard can be evaluated, so it decides. The inspector says "Evaluates to true: always taken." or "Evaluates to false: never taken."
- Branch probabilities do not total 100 %: branches without a Probability share what is left; when the given ones exceed 100 %, the warning reads "Branch probabilities add up to N %. Change them to total 100 %."
- A duration annotation on the step itself: distributions belong on the duration attribute, not on the action.
How it connects
- Evaluation, Units and Analysis in SysML v2 Projects: how the Simulator reads steps, successions and durations.
- Simulation: the Simulator page, its panels and Monte Carlo statistics.
- SysML v2 Textual Notation: metadata and
aboutin the text.
Annotations
Distributions
Put a distribution on a duration attribute. Location and scale fields take a quantity with a unit (45 [s], 2 [min]); shape fields take a number.
| Annotation | Fields | Meaning |
|---|---|---|
| Normal | mean, sd | Normal distribution. |
| Triangular | low, mode, high | Triangular, with low ≤ mode ≤ high. |
| Uniform | low, high | Uniform between low and high. |
| Exponential | mean | Exponential with the given mean. |
| Gamma | shape, scale | Gamma; the mean is shape × scale. |
| LogNormal | median, sigma | The logarithm is normal around the median's logarithm. |
| Weibull | scale, shape | Weibull. |
| Beta | alpha, beta, scale | Beta on 0..1, times scale. |
| Poisson | mean, scale | A count with the given mean, times scale. |
| Binomial | trials, p, scale | Successes in a number of trials, times scale. |
Durations drawn below zero are drawn again.
Correlated inputs
Without a correlation, every value drawn from a distribution is independent of the others. Correlation makes two of them move together:
metadata HolarchSimulation::Correlation about findCharger::duration, charge::duration { coefficient = 0.6; }
| Annotation | On | Meaning |
|---|---|---|
Correlation coefficient | about a, b: two attributes, each with a distribution | The rank (Spearman) correlation of their values, from -1 to 1. 0 is independent, 1 always ranks them alike, -1 opposite. |
- Each attribute keeps its own distribution. The simulator joins all pairs into one correlation matrix (a Gaussian copula): the n-th value drawn for an attribute in a run goes with the n-th value of every attribute it is correlated with.
- The coefficients of a group of correlated attributes must fit together: a strongly with b, b strongly with c, but a opposite to c is impossible. The check reports such a group; weaken one of the coefficients.
- Durations and amounts (Consumes, Produces, Seizes) correlate alike. A run with the same seed gives the same values.
- On the Simulator, in Monte Carlo mode with the SysML engine, Correlated Inputs lists the pairs of the root. Choose two attributes and a coefficient and click + Add Correlation, change a coefficient, or click × to remove one; a single Undo takes back each change. After a study, Achieved shows the rank correlation of the values the runs drew.
- The Hybrid Car demo's
ChargeStopcorrelates the wait for a free charger with the charging time (0.6).
Chances and counts
| Annotation | On | Meaning |
|---|---|---|
Probability percent | A succession out of a decision | The branch's weight. Branches without one share what is left of 100. |
An if action | The chance of the then branch when the condition cannot be evaluated. | |
| A loop action | The chance to repeat after each pass. | |
| A transition | The chance its guard holds when the guard cannot be evaluated. | |
LoopCount count | A loop action | The number of passes; it takes precedence over the loop's conditions. |
| LoopExit | A succession to done in a loop body | Ends the whole loop, not just the pass. |
Resources and costs
| Annotation | On | Meaning |
|---|---|---|
Resource initial, minimum, maximum, unit | A part or item usage | A pool of an amount. If the usage declares attribute level : Real, the simulator keeps it equal to the amount, so guards can read it. |
Consumes amount | about step, pool | Taken when the step starts. |
Produces amount | about step, pool | Added when the step ends. |
Seizes amount | about step, pool | Taken when the step starts and given back when it ends. |
Utilization amount | A perform action usage | How much of the performing part the step occupies. |
Cost amount, rate, unit, label | A step or a performing part | A cost per use (CostRate::perUse) or per hour (CostRate::perHour). |
Annotations that need the SysML engine
| Annotation | Meaning |
|---|---|
Transfer latency, capacity, per | On a connection or interface: delays items and signals sent over it. |
Size size | On an item: its size for transfer delays. |
Timeout limit | On a join: stops unfinished branches when the limit expires. |
NotBefore time | On a step: it does not start before this run time. |
| ForkTargets, JoinSources | On a transition into or out of a parallel state: the substates entered, or the substates that must be active. |
History deep | On a composite state: re-entering resumes the substate active when it was left. |
HostHook key, points | Reserved for Holarch: the run pauses for input at the listed points. |
The JavaScript simulator reads Probability, LoopCount and the distributions.
Messages
| Message | Meaning |
|---|---|
| Some simulation settings of this project are Holarch data, not part of the model. | Older settings are still stored next to the model. Click Move Simulation Settings into the Model…. |
| Holarch data from before simulation settings moved into the model; it wins over the model. | Shown in the inspector's Simulation section. Change the field to write it into the model, or move all settings on the Simulator. |
| No duration in the model. Set one here (it writes attribute duration : ISQ::DurationValue), or write it in the text. | The step has no duration attribute. |
| @Normal: sd must be greater than zero. Change sd. (and similar for other distributions and parameters) | A distribution parameter is missing or out of range. With the SysML engine, the model check reports it in the Editor and the Simulator refuses to run until it is fixed. |
| @Normal: sd has another unit dimension than … | A location or scale parameter has other units than the attribute, for example metres on a duration. |
| @LoopCount does not apply to a part … | The annotation sits on a kind of element it does not apply to. Move it or delete it. |
| metadata Consumes … about needs an action and a part or item annotated @Resource. | The elements after about are wrong in number or kind. |
| A probability of N % is outside 0 to 100. | Enter a percent from 0 to 100. |
| The branch probabilities of this decision add up to N %; the simulator scales them to 100 %. | A warning: every branch has a weight and they do not total 100. |
| A correlation needs two different attributes …, … is not an attribute … or … has no distribution, so nothing is drawn to correlate … | A Correlation names one attribute twice, something that is not an attribute, or an attribute without a distribution. |
| The coefficient N is outside -1 to 1. or The correlation has no coefficient. | Enter a coefficient from -1 to 1. |
| “a” and “b” are already correlated; the first correlation is used. … | A warning: a second Correlation of the same pair is ignored. Remove one of the two. |
| The correlations of … contradict each other: no joint distribution has them … | The coefficients of a group cannot hold together (the matrix is not positive semidefinite). Weaken one. The Simulator refuses to run until it is fixed. |
| Deadlock at <time>: N steps wait for something that never comes. | Shown above the results with the SysML engine, with each waiting step. An accept with no sender, an item never produced or a resource never released stops the run. |
Limits
- Durations are written in seconds, minutes, hours or days (
SI::s,SI::min,SI::h,SI::d). Milliseconds are written as seconds; weeks, months and years as days. - State machines, stimuli and Run together with need the SysML engine.
- Correlated inputs need the SysML engine; the JavaScript simulator draws every value independently. At most 200 attributes can be correlated in one group.
- The check of contradicting coefficients covers the correlations written in one namespace; the Simulator checks all correlations of the run.
Related
SysML® and OMG® are registered trademarks of Object Management Group, Inc. in the United States and other countries.