SysML v2
SysML v2 Variants and Configurations
Model a product line in a SysML v2 project: variation points, variants, rules and configurations in the Browser and the inspector, New Configuration…, views shown as one configuration, and trade studies of configurations.
On this page
Overview
A product line is one design with a few points where its products differ, such as the battery size or whether a charger is fitted. You model the line once and then look at, check and compare any one product without copying the model.
SysML v2 has this built into the language. Holarch shows it throughout the app:
- The Browser marks product lines, variation points, variants and configurations, and lists each product line's configurations.
- The inspector shows a product line's points, rules and configurations with a verdict for each, and lets you change a configuration's choices.
- New Configuration… creates a configuration from a dialog that checks the rules as you choose.
- View as ▾ in the top bar shows the views, the Database, the inspector and the Product Line page as one configuration.
- Trade Studies can compare a product line's configurations or a point's variants.
Variability in the text is available on every plan. On the Free plan the Product Line page, New Configuration… and changing a configuration's choices in the inspector are read-only; editing them is part of the Individual and Team plans. See Product Lines: Plans.
Concepts
Variation points and variants
A variation point is a place in the design where products differ. Its variants are the allowed choices.
- A variation usage is a point inside one design:
variation part charger : Component { variant part noCharger; variant part wallbox; }. - A variation definition is a reusable set of choices:
variation part def BatteryPack { variant part standardPack; variant part largePack; }. A usage typed by it, such aspart pack : BatteryPack;, is a point too.
Product lines
A product line is a definition or usage that owns or inherits variation points. In the Hybrid Car demo, CarLine is the product line: it specializes Car and adds the points pack and charger. A definition that specializes a product line is a product line too.
Rules
A rule is an assert constraint of the product line. It rules combinations of variants out. In the demo, wallboxNeedsLargePack says that the wallbox charger needs the large pack:
assert constraint wallboxNeedsLargePack { charger == charger::wallbox implies pack == BatteryPack::largePack }
While a point has no choice, a rule over it is neither met nor broken: its verdict is unknown.
Configurations
A configuration is one product of the line. It is a usage typed by the product line that binds one variant to each point. Holarch marks it with @HolarchConfiguration (package HolarchVariability), so the Editor notes each point it has not chosen yet:
part plugInHybrid : CarLine {
@HolarchConfiguration;
part :>> pack = BatteryPack::largePack;
part :>> charger = charger::wallbox;
}
Each configuration has a verdict:
| Verdict | Meaning |
|---|---|
| Valid | One variant is chosen for every point, and every rule is met. |
| Breaks the rule … | A rule is broken; the verdict names it. |
| Incomplete | A point has no variant chosen yet; the verdict names it. |
| Unknown | A rule could not be evaluated, for example because a value it reads is missing. |
Holarch also counts the combinations of variants and how many of them the rules allow. For a very large product line it checks the first combinations only and says how many it checked.
How to use it
When and why
Use variability when several products share most of one design: trims of a vehicle, export versions, sensor suites, a product with and without an option. Model the shared design once, mark the points where products differ, and add a configuration per product. Each product then stays in step with every change to the shared design.
Mark a variation point
- Open the Editor and the package that holds the design.
- Inside the product line's definition, choose Insert ▾ → Variation. Fill in the point's name and type.
- Inside the variation, choose Insert ▾ → Variant once for each choice.
- To reuse a set of choices, choose Insert ▾ → Variation at package level. It writes a variation definition; type a part by it.
The Browser now shows the product line with the stacked-boxes icon, and the point with a diamond.
Add a rule
- Inside the product line's definition, write an assert constraint over its points, for example
assert constraint r { charger == charger::wallbox implies pack == BatteryPack::largePack }. - Select the product line in the Browser.
You see the rule under Rules in the inspector's Product Line section, and the number of combinations it rules out.
Create a configuration
- In the Browser, open the row menu (⋯, right-click or Shift+F10) of the product line, or of its Configurations group.
- Choose New Configuration….
- Check Configures: the product line the configuration belongs to.
- Enter a Name, such as
longRangeHybrid. - Under Variant choices, choose one variant for each variation point. You see the verdict below the choices at once, for example Valid: meets every rule or Breaks the rule wallboxNeedsLargePack.
- Click Create.
The configuration is written into the text after the product line's last configuration, marked @HolarchConfiguration, and a single Undo takes it all back. The Browser selects it in the product line's Configurations group.
You can also open the dialog with New Configuration… in the inspector's Product Line section, or from ⌘K / Ctrl+K.
Change a configuration's choices
- Select the configuration in the Browser (or in a view).
- In the inspector's Configuration section, choose another variant in a point's list.
The binding in the text is rewritten (part :>> pack = BatteryPack::standardPack;) and the verdict updates; a single Undo takes it all back. Choose Not chosen to remove the choice. A choice that would add an error to the model is refused with the reason.
Show the model as one configuration
- In the top bar, click View as ▾ (it reads All configurations ▾ until you choose one) and choose a configuration. A banner under the top bar reads, for example, Viewing configuration plugInHybrid. and how many elements apply. In General, Interconnection and Grid Views, the variants it does not choose and the other configurations are hidden, and each variation point shows its choice, such as pack : BatteryPack = largePack. The Database, the inspector and the Product Line page follow the same choice.
- To go back, choose View as ▾ → All configurations, or click Leave in the banner.
On the Individual and Team plans you can edit while a configuration is shown; each edit is a SysML v2 text edit, checked before it is applied, and a single Undo takes each one back:
- Choosing a variant writes the binding in the configuration (
part :>> pack = BatteryPack::largePack;). - A changed attribute value becomes the configuration's own value; the definition keeps its value.
- New parts and actions belong to the configuration.
- Deleting an inherited element that may be left out writes
part :>> roofBox[0];in the configuration. A required inherited element cannot be deleted there; change it in the Editor. - A risk, task or other Holarch item you create applies to the configuration.
On the Free plan the configuration view is read only. From a configuration's inspector, Show in View ▾ opens a view of its product line shown as that configuration.
Compare configurations in a trade study
- Open Risks, Issues & Decisions → Trade Studies and a study (or click + New Trade Study).
- Under Alternatives, click + From Product Line….
- Under From, choose Configurations of … (a product line) or Variants of … (a variation point).
- Untick any item you do not want, and click Add.
Each configuration or variant becomes an alternative, linked to the model element. Add criteria and values as in any trade study, or use Pull Values from Model.
Worked example: the Hybrid Car demo
Create the demo with Project Files ▾ → New Demo Project → Hybrid Car (SysML v2) on Manage Projects.
- Open Model → Browser and expand Vehicles.
BatteryPackandCarLinecarry the product line icons;CarLinehas a Configurations group withlongRangeHybrid,plugInHybridandselfChargingHybrid. - Select
CarLine. The Product Line section lists the pointspack(standardPack, largePack) andcharger(noCharger, wallbox), the rulewallboxNeedsLargePack, and the three configurations, all Valid. It reports 4 combinations: 3 allowed by the rules, 1 ruled out (the wallbox with the standard pack). - Select
selfChargingHybridand change charger to wallbox. The verdict becomes Breaks the rule wallboxNeedsLargePack. Press ⌘Z / Ctrl+Z to undo. - Open the view
carLineVariants(Diagrams). Choose View as ▾ → plugInHybrid. TheBatteryPackbox keeps onlylargePack, and theCarLinebox shows pack : BatteryPack = largePack and variation charger : Component = wallbox. - Open Trade Studies → Configuration Line-up (TR-2). Its alternatives are the three configurations, scored on price, electric range and charging convenience.
Tips and good practice
- Keep the shared design in the product line and only the differences in variants. A variant redefines what it changes (
attribute :>> capacity = 12 [kW*h];). - Write rules as soon as you know a combination is not allowed. The verdicts then catch a bad configuration at once.
- Name configurations after the product, not the choices (
plugInHybrid, notlargePackWallbox). - Use one view per product line and switch it between configurations, instead of one view per configuration.
Common mistakes
- A configuration is not listed under its product line. It must be typed by the product line (
part x : CarLine). Check its Type in the inspector. - A verdict stays Unknown. A rule reads a value that has none in this configuration. Choose a variant for every point, or give the value a default.
- A choice is refused. The variant is not one of that point's variants. Choose from the list in the inspector, or fix the name in the text.
How it connects to other features
- Editor: Insert ▾ writes Variation, Variant, Configuration and Variant Choice. Everything here is ordinary SysML v2 text, so imports, exports and other SysML v2 tools read it.
- Trade Studies: configurations and variants as alternatives.
- Reliability Block Diagrams: a variation point's variants are alternatives, so the diagram counts only the variant chosen by the configuration in View as ▾. With all configurations shown, the point is one block with its own values, and the pane says to choose a configuration.
- Model Checks: Verification → Model Checks reports each configuration that breaks a rule or leaves a variation point without a variant (ProductLine.3, an error). The note is the verdict, such as Breaks the rule wallboxNeedsLargePack, and the broken rules are listed as related elements. Fix → Open Item opens the configuration. The API and MCP report the same finding (
run_model_checks,GET …/model-checks). - Change requests and history: every change is an ordinary model change, and a single Undo takes back each one.
Browser
- Icons: stacked boxes for a product line, a diamond for a variation point, a filled diamond for a variant, sliders for a configuration. Each icon has a tooltip.
- Configurations group: the first member of a product line's row. It lists the product line's configurations wherever they are declared; each row there stands for the configuration itself. Its row menu has New Configuration….
- Row menu: New Configuration… on a product line and on each of its configurations.
- Screen readers: a row's name says what it is, for example CarLine, part def, product line or plugInHybrid, part, configuration of CarLine.
Inspector
Product Line
- Variation points: each point with the variants it chooses from.
- Rules: the product line's assert constraints, or No rules: every combination of variants is allowed.
- Configurations: a table of the configurations and their verdicts.
- Combinations: how many combinations of variants exist and how many the rules allow, rule out or leave unknown.
- New Configuration…
Configuration
- Configures: the product line.
- Status: the verdict, announced to screen readers when it changes.
- One list per variation point: the chosen variant, or Not chosen. A single Undo takes a change back.
- Rules: each rule as Met, Broken or Unknown.
- Show in View ▾: the General, Interconnection and Grid Views that show the product line, opened as this configuration.
Variation Point and Variant
- A variation point lists its Variants and, under Chosen by, what each configuration chooses.
- A variant shows what it is a Variant of and which configurations choose it.
View as Configuration
- Where: the top bar, once the model has a configuration. One choice per browser tab: General, Interconnection and Grid Views, the Database, the inspector and the Product Line page follow it.
- Control: View as ▾ (it reads All configurations ▾ until you choose one). The menu lists All configurations, each product line's configurations with their verdicts, Effectivity ▸ (show the model at a serial number, a build date, or both: Serial Number and Date… is a unit with that serial built on that date) and Manage Product Line. The banner under the top bar has Change ▾ and Leave.
- What changes: variants the configuration does not choose and the other configurations of the same product line are hidden, with what they own. Variation points show their choice. Layouts are not rearranged and are shared by every configuration.
- Editing: Individual and Team plans. Edits follow the rules in Show the model as one configuration. On the Free plan, and for people with view access, the view is read only and the banner says why.
- Grid: the Table leaves the hidden elements out and names the choices above the table. The Matrix shows the whole product line.
- Per tab: the choice is kept for the browser tab until you change it. Pictures of the view in the Diagrams list show the whole product line.
- Screen readers: switching announces the configuration and how many elements apply, for example Viewing configuration plugInHybrid. … elements apply., with Read only. added when you cannot edit.
Messages
| Message | What to do |
|---|---|
| The model has no variation points yet. Add a variation in the Editor (Insert ▾ → Variation), then try again. | Mark a variation point first. |
| The model has no configurations or variants yet. … (+ From Product Line…) | Add a variation point or a configuration first. |
| Enter a name for the configuration. | Type a name in Name. |
| … is already used in …. Choose another name. | Another element in the same package has that name. |
| Names have 1 to 1,000 characters and no line breaks. Change the name. | Shorten the name or remove the line break. |
| A choice or configuration that is refused | It would add an error to the model; the message names the error. Fix the text, or choose another variant. |
| The SysML checker is not available, so the variation points cannot be read. | Reload the page, or create the configuration in the Editor with Insert ▾ → Configuration. |
Limits
- For a very large product line, the combination count checks only the first combinations; configurations are always checked in full.
- On the Free plan, a view shown as one configuration is read only.
- Not yet: releasing or retiring a SysML v2 configuration. Every SysML v2 configuration is Draft, so configuration control does not lock one.
- Variability covers the SysML v2 model. Holarch items next to it (risks, tests, tasks, document sections) apply to every configuration, except those created while a configuration is shown: they apply to that configuration. Their Applies To cannot be edited in a SysML v2 project yet.
Related pages
- SysML v2 Textual Notation: variations, variants and configurations
- SysML v2 Views
- SysML v2 Analysis: trade studies
SysML® and OMG® are registered trademarks of Object Management Group, Inc. in the United States and other countries.