Builder API

New in v1.1.0 Labs

With the Builder API you can create and change SysML v2 models from Python. There is one function for each keyword of the textual notation: for part def it is new_part_def(), and for part it is new_part(). Clauses written after a name, such as : Wheel or [4], are keyword arguments. To read or change an element after it is created, use the get_, set_, add_ and remove_ functions in experimental.query.

You need the Syside Python Library & CLI installed and a license activated; see Install the Python Library & CLI. The pages below assume you can read the SysML v2 textual notation. For the element objects that the functions take and return, see Models as Python objects.

Try it

The script below builds this model, with one function call for each declaration inside the package:

package Vehicles {
    private import ScalarValues::Real;

    part def Wheel {
        attribute diameter : Real = 0.6;
    }
    part def Vehicle {
        part wheels : Wheel [4];
        attribute mass : Real;
    }
    part def Car :> Vehicle {
        attribute redefines mass = 1200.0;
    }
}

Save the script as vehicles.py and run python vehicles.py:

import syside
from syside import query
from syside.experimental import builder

STANDARD_LIBRARY = frozenset({syside.DocumentTier.StandardLibrary})


def main() -> None:
    # New elements need an owner, so start from a model with an empty package
    model = syside.load_model(
        [("memory://vehicles.sysml", "package Vehicles;")]
    )
    vehicles = query.find_by_qualified_name(model, "Vehicles")
    real = query.find_by_qualified_name(
        model, "ScalarValues::Real", tiers=STANDARD_LIBRARY
    )
    assert isinstance(vehicles, syside.Package)
    assert isinstance(real, syside.DataType)
    assert real.owning_membership is not None

    builder.new_import(vehicles, real.owning_membership)

    wheel = builder.new_part_def(vehicles, "Wheel")
    builder.new_attribute(wheel, "diameter", defined_by=[real], equals=0.6)

    vehicle = builder.new_part_def(vehicles, "Vehicle")
    builder.new_part(
        vehicle, "wheels", defined_by=[wheel], multiplicity=builder.bounds(4)
    )
    mass = builder.new_attribute(vehicle, "mass", defined_by=[real])

    car = builder.new_part_def(vehicles, "Car", specializes=[vehicle])
    builder.new_attribute(car, redefines=[mass], equals=1200.0)

    diagnostics = builder.resolve(model)
    if diagnostics.contains_errors():
        raise syside.ModelError(model.unlock(), diagnostics)

    print(syside.pprint(vehicles))


if __name__ == "__main__":
    main()

The output is the built model in textual notation:

package Vehicles {
    private import ScalarValues::Real;
    part def Wheel { attribute diameter : Real = 0.6; }
    part def Vehicle {
        part wheels : Wheel [4];
        attribute mass : Real;
    }
    part def Car :> Vehicle { attribute :>> Vehicle::mass = 1200; }
} // package Vehicles

This is the same model as the target. Only the formatting from pprint is different: redefines mass is printed as :>> Vehicle::mass, and 1200.0 as 1200.

These four points apply to every use of the API:

  • The first argument is the owner. The new element is created inside the element you give as the first argument, as if it were nested inside it in the text. The owner must be a package, a definition or a usage. A script must therefore start from a model that already has a package. Here, that model is a one-line string.

  • References are elements, not names. In defined_by=[wheel], wheel is the Wheel element itself, not its name. A reference cannot be misspelled. To refer to an element from the standard library, such as Real, get it first with find_by_qualified_name().

  • Values are Python values. equals=0.6 is the same as = 0.6 in text, and bounds(4) is the same as [4]. For an expression such as 4 * wheel.mass, use templates. There is an example in Build a model from a bill of materials.

  • Call resolve() last. The builder functions change only what is written. The relationships that Syside derives, and the validation checks, are not updated until resolve() is run. For details, see Re-resolve a model after building.

Where to go next

Every constructor, with the parameters each accepts, is listed in the API reference.