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],wheelis theWheelelement itself, not its name. A reference cannot be misspelled. To refer to an element from the standard library, such asReal, get it first withfind_by_qualified_name().Values are Python values.
equals=0.6is the same as= 0.6in text, andbounds(4)is the same as[4]. For an expression such as4 * 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 untilresolve()is run. For details, see Re-resolve a model after building.
Where to go next
Edit a model with the Builder API – Load a model from a file, change values in it and add elements to it
Build a model from a bill of materials – Turn a bill of materials of any depth into part definitions whose masses add up
Re-resolve a model after building – What
resolve()re-derives after an edit, and the errors it reports
Every constructor, with the parameters each accepts, is listed in the
API reference.