Models as Python objects

Syside Automator 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 Automate your first model check; 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 Python objects. It returns two of them:

1. Model class instance containing all information from 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

2. Diagnostics class instance which contains any non-critical warnings that were found in the model

Example:

import syside

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

Note

Standard SysML v2 libraries are also imported when constructing a Model, but they are stored in Model.all_docs 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.