Advent of SysML v2 | Lesson 2 – Navigating textual models

Hello and welcome back to the Advent of SysML v2 – a daily, hands-on mini-course designed to bring you up to speed with the new SysML v2 standard and the modern Syside tooling that makes you productive from day one.

Yesterday, you modeled a Christmas tree and took on your first challenge: designing Santa’s Sleigh. We hope you had fun unleashing your creativity! Today, we’re diving into something equally exciting – learning how to navigate textual SysML v2 models like a Systems as Code pro.

As your models grow beyond simple examples, you’ll need powerful tools to explore and understand them quickly.

By the end of this lesson, you will:

See our Santa’s Sleigh model
Learn how to navigate textual SysML models efficiently
Learn about Syside Automator and how to use it to extract part hierarchy

Santa’s Sleigh model

Throughout the Advent of SysML v2 series, we will help Santa redesign his famous sleigh with cutting-edge technology. This was also your first challenge: we hope you have a beautiful design ready in Syside Cloud. Here is our version:

package Day2_SantaSleigh {
    private import ScalarValues::*;

    part def SantaSleigh {
        // Components of the sleigh
        part cockpit {
            doc /* This is where Santa sits. */
            ref item driver = santa;
        }
        part cargoBay  { doc /* Place for the GiftBag. */  }
        part dashboard { doc /* Naughty-Nice dashboard. */ }

        // Entities related to the sleigh
        ref item santa;
        abstract ref part reindeer : Reindeer [9];
       
        ref part dasher  subsets reindeer { constant redefines noseColor = Color::orange; }
        ref part dancer  subsets reindeer { constant redefines noseColor = Color::yellow; }
        ref part prancer subsets reindeer { constant redefines noseColor = Color::green;  }
        ref part vixen   subsets reindeer { constant redefines noseColor = Color::blue;   }
        ref part comet   subsets reindeer { constant redefines noseColor = Color::indigo; }
        ref part cupid   subsets reindeer { constant redefines noseColor = Color::violet; }
        ref part donner  subsets reindeer { constant redefines noseColor = Color::silver; }
        ref part blitzen subsets reindeer { constant redefines noseColor = Color::gold;   }
        ref part rudolph subsets reindeer { constant redefines noseColor = Color::red;    
                                            attribute redefines energyLevel := 200.0;      }
    }

    part def Reindeer {
        constant attribute noseColor : Color;
        attribute energyLevel : Real default := 100.0;
    }

    enum def Color {
        enum orange; enum yellow; enum green;
        enum blue;   enum indigo; enum violet;
        enum silver; enum gold;   enum red;
    }
}

As we did yesterday, we’ve put the design of Santa’s sleigh in a package for today’s lesson. We start by importing some common datatypes from the “ScalarValues” standard library, giving us access to primitive types like Real numbers for attributes.

Inside the package, we define what Santa’s sleigh is. The sleigh has three main components: a cockpit where Santa sits, a cargo bay for the gift bag, and a dashboard that displays whether the next child is naughty or nice. Notice how the cockpit has a reference to its driver, who happens to be Santa himself.

The sleigh also references entities around it. Santa is declared as an item, and we have nine reindeer pulling the sleigh. What exactly is a reindeer? Well, we define that too. Each reindeer has a nose color and an energy level that defaults to 100. The nose colors come from an enumeration we define: orange, yellow, green, blue, indigo, violet, silver, gold, and red.

After declaring there are nine reindeer, we list them all individually: Dasher, Dancer, Prancer, Vixen, Comet, Cupid, Donner, Blitzen, and of course, Rudolph. Each reindeer is declared as a subset of the nine reindeer and gets its own unique nose color. Rudolph is special – not only does he have a red nose, but his energy level is 200 instead of the default 100. That’s the power needed to lead the sleigh!

This model uses several SysML v2 concepts we haven’t covered yet, like references, subsets, and redefinitions. Don’t worry if these seem unfamiliar. We’ll explore them in detail in upcoming lessons. For now, let’s focus on learning how to navigate models like this efficiently.

Navigating SysML v2 textual models like a pro

Now that we understand the Santa’s Sleigh model structure, you might be wondering: “How do I navigate efficiently when models grow to hundreds or thousands of lines?” Great question! This is where Syside Modeler shines.

Syside Modeler transforms Visual Studio Code into a professional-grade environment for SysML v2, treating models as navigable codebases. This reduces the cognitive load of manually tracking dependencies and lets you focus on design intent rather than hunting through files.

Let’s explore the key navigation features. Try them yourself in Syside Cloud!

Document outline

Working with a textual model, you’ll want to see the big picture at a glance. The Outline view is like a table of contents for your model, showing all elements in the current file hierarchically.

To open it:

Press Ctrl+Shift+P on Windows/Linux, Command+Shift+P on macOS to open the Command Palette
Type outline and select “User View Container: Focus on Outline View”

The outline lets you quickly jump to any element. Try clicking on Reindeer or Color in the outline to navigate instantly to those definitions.

Model navigation

Ever wonder where a type is defined? In our Santa’s Sleigh model, we use the Real datatype for energyLevel. Where does Real come from?

Syside language server provides navigation and refactoring tools that work across your entire model in the workspace:

Go to Definition: Ctrl/Cmd+Click any element to jump to its definition
Find References: Ctrl/Cmd+Click a definition to see all its usages

For example, clicking on Electrical next to Battery will jump to its definition. Clicking on the definition itself shows all references in a preview panel, including:

The definition itself
The Battery element
The Motor element

These features work across all .sysml files in your project, making it easy to navigate and refactor even complex models.

References

Before changing or deleting an element, you’ll want to know where it’s used. Find References shows you every location where an element is referenced throughout your model.

This gives you complete visibility into the impact of your changes across the entire model.

Renaming

What if you want to rename Color to ReindeerColor or ColorPalette? In a large model, manually finding and updating every reference would be error-prone. Syside’s Rename Symbol feature does this automatically and safely:

Rename Symbol: Select an element and press F2 to rename it everywhere

Syside updates the definition and all references across your entire workspace automatically.

Folding

As models grow, you’ll want to hide details temporarily to focus on structure. Folding lets you collapse and expand sections based on the syntactic structure.

Use folding to hide nested elements and make large models more manageable. Hover next to any element to reveal the fold arrow:

Click the arrow to fold/unfold the element. You can also use the Command Palette Ctrl+Shift+P on Windows/Linux, Command+Shift+P on macOS to find the ‘Toggle Fold’ command and its keyboard shortcut.

So far, we’ve been navigating SysML v2 models using Syside Modeler – an extension for Visual Studio Code (and similar editors like VSCodium or Cursor). Modeler provides features for quicker textual modeling and visualization.

But what if you want to analyze your models programmatically? Extract information? Automate workflows? Build custom applications? That’s where Syside Automator comes in.

First glimpse at Syside Automator

Syside Automator is a Python library that enables the analysis of SysML v2 models, automation of workflows, and building custom applications. It acts as the bridge between your models and the broader Python ecosystem. You can analyze, validate, generate reports, or integrate with other tools.

Let’s see it in action by extracting the part hierarchy from our Santa’s Sleigh model.

Extracting part hierarchy with Automator

Suppose we want to automatically list all the parts within SantaSleigh. Here’s a simple script that does exactly that:

import pathlib
import syside

# Path to our SysML model file
LESSON_DIR = pathlib.Path(__file__).parent.parent
MODEL_FILE_PATH = LESSON_DIR / “models” / “L02_SantaSleigh.sysml”


def find_element_by_name(model: syside.Model, name: str) -> syside.Element | None:
    “””Search the model for a specific element by name.”””

    # Iterates through all model elements that subset Element type
    # e.g. PartUsage, ItemUsage, OccurrenceUsage, etc.
    for element in model.elements(syside.Element, include_subtypes=True):
        if element.name == name:
            return element
    return None


def show_part_decomposition(element: syside.Element, part_level: int = 0) -> None:
    “””
    Print parts and all sub-parts in a tree structure.
    Skips attributes, connections, and other non-part elements.
    “””

    # Print root element regardless of type
    # e.g. if it is a Package or PartDefinition
    if part_level == 0:
        print(element.name)
    elif type(element) is syside.PartUsage:
        # Indent based on nesting depth
        print(”  ” * part_level, “â”””, element.name)

    # Print subparts by calling the same function again for each child
    for owned_element in element.owned_elements:
        show_part_decomposition(owned_element, part_level + 1)


def main() -> None:
    # Load SysML model and get diagnostics (errors/warnings)
    (model, diagnostics) = syside.load_model([MODEL_FILE_PATH])

    # Make sure the model contains no errors before proceeding
    assert not diagnostics.contains_errors(warnings_as_errors=True)

    root_element = find_element_by_name(model, “SantaSleigh”)

    print(“\nPrinting part decomposition tree:\n“)
    show_part_decomposition(root_element)


if __name__ == “__main__”:
    main()

What this script does:

Loads the SysML v2 model file and checks for errors
Searches for the `SantaSleigh` element by name
Recursively prints all owned parts in a tree structure

Output:

Now, if we add more parts to the model and rerun the script, it automatically picks them up.

We’ve automated the process of extracting model information! In future lessons, we’ll extend scripts like this to do more interesting and useful things.

This is the power of Systems as Code! Your models aren’t just diagrams. They’re structured data you can analyze, validate, and integrate into your engineering workflows.

Challenge

Now that you’ve seen how easy it is to extract part information using Syside Automator, here’s your challenge: extract attribute data from the Santa’s Sleigh model.

In Syside Cloud, you’ll find:

Today’s Santa Sleigh model
The script for extracting part data (shown above)
A partially complete script for extracting attribute data

The process for extracting both pieces of information is very similar. The task requires only a little Python programming knowledge. Your goal is to complete the script so it prints out all attributes (like noseColor and energyLevel) for each part.

If you run into issues or aren’t sure how to proceed, check the Automator Documentation pages for examples or head to the Sensmetry forum and ask questions in the Advent of SysML v2 forum section. The community is here to help!

Summary

In this lesson, you learned how to navigate textual SysML v2 models like a true Systems as Code pro. You explored powerful features in Syside Modeler that make working with large models effortless: Document Outline, Go to Definition, Find References, Rename Symbol, and Folding.

You also got your first glimpse at Syside Automator, a Python library that lets you programmatically analyze and extract information from your models. You saw how to extract part hierarchy automatically, and now you have the challenge of extracting attribute data.

Tomorrow, we’ll dive deeper into SysML v2 concepts and continue strengthening Santa’s sleigh design. Don’t forget to:

Complete today’s challenge in Syside Cloud
Join the discussion at the Sensmetry forum
Come back tomorrow for Lesson 3!