Holarch

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.

How to use it →

On this page
  1. Overview
  2. Concepts
    1. Nominal value and distribution
    2. Which settings win
    3. Two simulators
  3. How to use it
    1. When and why
    2. Set a duration, probability or loop count
    3. Write annotations in the text
    4. Move older settings into the model
    5. Simulate a state machine
    6. Worked example: the Hybrid Car demo
    7. Tips and good practice
    8. Common mistakes
    9. How it connects
  4. Annotations
    1. Distributions
    2. Correlated inputs
    3. Chances and counts
    4. Resources and costs
    5. Annotations that need the SysML engine
  5. Messages
  6. Limits
  7. Related

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, if condition 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

  1. Select the step, succession, decision, loop or if action on an Action Flow View, in the Browser or in the Editor.
  2. In the inspector's Simulation section, set Duration (a fixed value or a distribution), Probability (%), Iterations or Probability of then (%).
  3. 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::DurationValue when 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.
  4. 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

  1. Open the Editor.
  2. Add the annotation inside the element's body, as @HolarchSimulation::Kind { field = value; }, or after it, as metadata HolarchSimulation::Kind about element { … }.
  3. 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.

  1. Click Move Simulation Settings into the Model….
  2. The preview lists each setting and the annotation that replaces it.
  3. 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.

  1. Open Behavior → Simulator and choose a state definition, or a part that exhibits states, as Root.
  2. Optional: under Run together with, choose a scenario action that sends signals to the part, such as the demo's TestDrive.
  3. Under Stimuli, click + Add Stimulus and set At (time and unit), Signal and To (a machine, or Every machine that accepts it).
  4. 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.
  5. 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 toCruise after shift has Probability 70; the else branch takes the remaining 30 %. cruise takes 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; drive Consumes 1.5 Wh of it and has a Cost of 0.4 USD per use.
  • PowertrainStates: the transition startElectric has Probability 80 for its guard; accept when charge < 15 changes to hybrid when the charge drops; accept after 30 [min] ends charging.
  • TestDrive: a scenario that sends StartRequest, waits an hour, then sends StopRequest and PlugIn to demoCar. 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

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.

AnnotationFieldsMeaning
Normalmean, sdNormal distribution.
Triangularlow, mode, highTriangular, with low ≤ mode ≤ high.
Uniformlow, highUniform between low and high.
ExponentialmeanExponential with the given mean.
Gammashape, scaleGamma; the mean is shape × scale.
LogNormalmedian, sigmaThe logarithm is normal around the median's logarithm.
Weibullscale, shapeWeibull.
Betaalpha, beta, scaleBeta on 0..1, times scale.
Poissonmean, scaleA count with the given mean, times scale.
Binomialtrials, p, scaleSuccesses 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; }
AnnotationOnMeaning
Correlation coefficientabout a, b: two attributes, each with a distributionThe 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 ChargeStop correlates the wait for a free charger with the charging time (0.6).

Chances and counts

AnnotationOnMeaning
Probability percentA succession out of a decisionThe branch's weight. Branches without one share what is left of 100.
An if actionThe chance of the then branch when the condition cannot be evaluated.
A loop actionThe chance to repeat after each pass.
A transitionThe chance its guard holds when the guard cannot be evaluated.
LoopCount countA loop actionThe number of passes; it takes precedence over the loop's conditions.
LoopExitA succession to done in a loop bodyEnds the whole loop, not just the pass.

Resources and costs

AnnotationOnMeaning
Resource initial, minimum, maximum, unitA part or item usageA 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 amountabout step, poolTaken when the step starts.
Produces amountabout step, poolAdded when the step ends.
Seizes amountabout step, poolTaken when the step starts and given back when it ends.
Utilization amountA perform action usageHow much of the performing part the step occupies.
Cost amount, rate, unit, labelA step or a performing partA cost per use (CostRate::perUse) or per hour (CostRate::perHour).

Annotations that need the SysML engine

AnnotationMeaning
Transfer latency, capacity, perOn a connection or interface: delays items and signals sent over it.
Size sizeOn an item: its size for transfer delays.
Timeout limitOn a join: stops unfinished branches when the limit expires.
NotBefore timeOn a step: it does not start before this run time.
ForkTargets, JoinSourcesOn a transition into or out of a parallel state: the substates entered, or the substates that must be active.
History deepOn a composite state: re-entering resumes the substate active when it was left.
HostHook key, pointsReserved for Holarch: the run pauses for input at the listed points.

The JavaScript simulator reads Probability, LoopCount and the distributions.

Messages

MessageMeaning
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.

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