Models as Python objects

The Syside Python Library & CLI hands your script a loaded SysML v2 model as Python objects. This page explains the objects every script touches: the model and its documents, the elements they contain, and the relationships that tie elements together. For a hands-on start, go straight to Your first Python example; for the exact API of each class, see the API reference.

The examples are plain SysML v2; if the notation is new to you, the SysML v2 specification introduces it.

From source files to a Model

The load_model function turns a SysML v2 model written in textual notation into a Model instance. It contains all information from the model defined by .sysml files, including elements, relationships, and their properties:

• Each .sysml file becomes an instance of class Document and is stored in the model’s documents attribute

• The model’s diagnostics attribute holds a Diagnostics instance, which contains any non-critical warnings that were found in the model

Example:

import syside

model = syside.load_model(["path_to_model.sysml"])

Note

Standard SysML v2 libraries are also imported when constructing a Model, but they are stored in the model’s Environment rather than documents since most users won’t need to access them directly.

Note

If the loaded model contains errors, load_model function will raise an exception. If you need to be able to load a model with errors, you can use try_load_model function instead. In that case, the diagnostics will contain the errors and warnings found in the model.

Elements and relationships

In SysML v2, a Document is constructed from Element (also known as nodes). An Element is a uniquely identified constituent of a model that can have Relationships with other Elements.

Consider this example:

part wheel{
   part wheel_rim;
   part tire;
}

Here, we have three unique elements: wheel, wheel_rim, and tire. In Python, these elements are represented as objects with properties assigned via attributes, such as .name.

Elements can be identified in several ways:

• .name – basic element name

• .qualified_name – includes hierarchy information

• .short_name – SysML v2 short names, in textual notation defined between < and > characters

• .declared_name – explicitly declared names

The hierarchy is maintained through relationships. In the example, wheel owns wheel_rim and tire, representing that the wheel is composed of these parts. A script walks it downward through .owned_elements and upward through .owner.

Tip

For deeper exploration of Element and other nodes:

• Refer to the SysML v2 Language Specification Document

• Use a Python debugger (e.g., through Visual Studio Code)

• Utilize sexp to explore model nodes

Element types

Elements can be of different types and have hierarchical relationships. For example:

part wheel{
   attribute mass;
   action rotate;
}

In this case:

• wheel is a PartUsage

• mass is a AttributeUsage

• rotate is a ActionUsage

A usage is one occurrence of a thing, and a definition is the kind of thing it is. The two are separate element types, and much of what a script asks turns on telling them apart:

part def Electrical;
part Battery : Electrical;

Electrical is a PartDefinition, a kind of part, and Battery is a PartUsage typed by it.

With the objects in hand, put them to work: the how-to guides answer single questions, starting with Find and navigate elements and Evaluate attribute values.