SysML v2 Deep Dive 5 min read

Lesson 15: Attributes and the ISQ library: physics, not just numbers

Attributes and the ISQ library: physics, not just numbers

In 1999 NASA lost the Mars Climate Orbiter. One team sent impulse data in pound-force seconds. The software that received it expected newton-seconds. Both numbers were valid. Neither one carried its unit.

SysML v1 had an answer to this. A value type could carry a unit and a quantity kind, and SysML v1.6 shipped a units library called QUDV, plus ISO 80000 definitions, to back them. But that library sat in a non-normative annex. Tool support varied, and many teams built their own lightweight types instead.

SysML v2 puts quantities and units into the standard itself. A spacecraft's dry mass is typed by MassValue. Its payload mass can be expressed directly in grams (g) or kilograms (kg). Its power is typed by PowerValue. Every conforming tool ships the exact same library (ISQ and SI), allowing models to enforce dimensional consistency and unit compatibility natively.

The concept: what does this number mean?

An attribute links a structural component to a value. In SysML v2 that value can be a physical quantity with a unit, not a bare number.

  • attribute def defines a data type, such as MassValue. It replaces the v1 ValueType.
  • attribute uses that type on a part, such as dryMass: MassValue. It replaces the v1 value property.
  • The ISQ library defines standard international quantities like mass, length and power. It follows ISO/IEC 80000.
  • The SI library defines standard units like kg, g and W, and their mathematical conversion factors.
  • 1500 [kg] - An expression constructed using the bracket operator ([...]). It binds a numerical magnitude (1500) and a measurement reference (kg) into a single expression.

The code: a spacecraft that can't lie about its mass

We give a spacecraft a mass budget and a power figure. Then we state the rules they must obey.

package SpaceSystems {

    // Import the physics. This is the whole point.
    import ISQ::*;
    import SI::*;

    part def Spacecraft {

        // 1. TYPED BY QUANTITY, NOT BY NUMBER
        // MassValue is a distinct physical type. It is not a primitive Real.
        attribute dryMass : MassValue = 1500 [kg];

        // 2. MIXED UNITS, SAME DIMENSION
        // Declared in grams, but still a MassValue.
        // A conforming tool resolves the conversion automatically under the hood.
        attribute payloadMass : MassValue = 500000 [g];

        attribute totalMass : MassValue = 2000 [kg];
        attribute maxPower : PowerValue = 444 [W];

        // 3. AN ASSERTED RELATIONSHIP
        // 'assert constraint' guarantees that this equation must hold true at all times.
        assert constraint massRollup {
            totalMass == dryMass + payloadMass
        }

        assert constraint powerFloor {
            maxPower > 0 [W]
        }
    }
}

The two imports bring in MassValue, PowerValue, kg, g and W.

dryMass and payloadMass are both masses. One is in kilograms and one is in grams. The library knows how grams relate to kilograms, so the rollup works. maxPower is a power. You can't swap it for a mass.

Now try this:

assert constraint nonsense {
    totalMass == dryMass + maxPower
}

Every value here has a known dimension. Mass plus power is not a mass. A tool that checks dimensions can flag this type mismatch.

Deep dive: three things worth getting right

A value type and a quantity are different things

MassValue is an attribute definition. It describes what a mass value looks like, a number plus a unit.

ISQ::mass is an attribute in the library. It is the standard ISQ quantity called mass, and its type is MassValue.

Most of the time, type your attribute with the value type:

attribute dryMass : MassValue = 1500 [kg];

Sometimes an analysis or a library constraint needs the ISQ quantity itself. Then subset it instead:

attribute dryMass :> ISQ::mass = 1500 [kg];

Both work. Pick one style per project and stick to it. A model that mixes them at random leaves reviewers guessing whether the difference means something.

constraint describes, assert constraint enforces

A plain constraint describes a relationship. It is true or false depending on the values, and that's all.

constraint { totalMass == dryMass + payloadMass }

An assert constraint turns it into a rule the model must obey. If it comes out false, the model is inconsistent, and a tool can report it.

assert constraint { totalMass == dryMass + payloadMass }

If you want a wrong mass rollup to fail validation, use assert. This trips up a lot of people who wonder why their solver never complains.

The square brackets are syntax

In 1500 [kg], the brackets are not a label for humans. They are part of the value. The number and the unit kg become one quantity.

The SI library defines kg as the kilo prefix applied to g. That is why 1500 [kg] and 500000 [g] can sit in the same equation. The conversion lives in the model, not in someone's head.

V1 vs. v2 attributes and units cheat sheet

ConceptSysML v1SysML v2
Value featureValue propertyattribute usage
Units libraryQUDV and ISO 80000, in a non-normative annexISQ and SI, part of the standard
Typing a valueValueType with a unit and quantity kind, checked if the tool chose toLibrary types like MassValue and PowerValue
Writing a unitSet on the ValueType, values written as bare numbers1500 [kg], the unit is part of the value
Unit conversionBy hand, or tool-specificDefined in the library, kg is kilo times g
EquationsA ConstraintBlock bound through parametrics, or a constraint on the blockassert constraint inside the part

Next Lesson

Composite vs. reference with ref part. The numbers are honest now. Next comes structure, and one keyword that decides whether a shared power unit counts once in your mass budget or twice.

SysML v2

SysModeler Team

Engineering & Product