sysml2py

https://github.com/westfall-io/sysml2py
Admin
sysml2py is an open source pure Python library for constructing python-based classes consistent with...
Tokens:9,748
Snippets:82
Trust Score:6.7
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Output of Part Creation Example

Source: https://github.com/westfall-io/sysml2py/blob/main/README.md

The expected output format for the part creation and modification example, showing attributes and their values.

```text
part <'3.1'> Stage_1 {
  attribute mass= 100.0 [kg];
  attribute thrust= 1199.0 [N];
}
```

--------------------------------

### Install sysml2py

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Install the sysml2py library using pip. You can install from PyPI or directly from the GitHub repository.

```bash
pip install sysml2py
# or from source:
pip install https://github.com/Westfall-io/sysml2py/archive/refs/heads/main.zip
```

--------------------------------

### Output of Nested Structure Example

Source: https://github.com/westfall-io/sysml2py/blob/main/README.md

The expected output for the nested Part and Item creation example, demonstrating hierarchical structure.

```text
part sensor {
   part camera {
      attribute mass;
   }
   item lens;
}
```

--------------------------------

### Retrieve and Modify Attribute Value

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to get the value of an attribute (as an astropy Quantity) and perform operations on it. This is useful for calculations and updates.

```python
# Retrieve the value (returns astropy Quantity)
val = mass.get_value()
print(val)          # 100.0 kg
print(val + 50*u.kg)  # 150.0 kg
```

--------------------------------

### Create and Dump Basic SysML Port

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates creating a simple SysML port. Use this for defining interaction points of a part.

```python
from sysml2py import Port

# Basic port
fuel_port = Port()._set_name("fuelPort")
print(fuel_port.dump())
```

--------------------------------

### Create Simple Named Package

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to create a SysML package with a name. Use this for organizing model elements.

```python
from sysml2py import Package, Part, Item

# Simple named package
pkg = Package()._set_name("RocketSystem")
print(pkg.dump())
```

--------------------------------

### Create Package with Short Name

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates creating a package with both a long name and a short reference ID. Use this for concise references within the model.

```python
# Package with short name (reference ID)
pkg2 = Package()._set_name("Rocket")._set_name("'R-001'", short=True)
print(pkg2.dump())
```

--------------------------------

### Create and Dump SysML Item Usage

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates how to create a SysML item usage and print its SysML representation. Use this for modeling flow or contained elements.

```python
from sysml2py import Item, Package

# Item usage
fuel_item = Item()._set_name("fuelSupply")
print(fuel_item.dump())
# Output: item fuelSupply;
```

--------------------------------

### Create Port with Directed Features

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Illustrates creating a port with specified input and output features. Use this to define the directionality of interactions.

```python
# Port with directed features
fuel_hose = Port()._set_name("FuelHose")
fuel_hose.add_directed_feature("in", "fuelIn")
fuel_hose.add_directed_feature("out", "fuelOut")
print(fuel_hose.dump())
```

--------------------------------

### Create and Modify Part with Attributes

Source: https://github.com/westfall-io/sysml2py/blob/main/README.md

Demonstrates creating a Part with attributes, setting their values, and updating them. Requires astropy for units.

```python
from sysml2py import Attribute, Part

import astropy.units as u
a = Attribute()._set_name('mass')
a.set_value(100*u.kg)
b = Attribute()._set_name('thrust')
b.set_value(1000*u.N)
c = Part()._set_name("Stage_1")._set_name("'3.1'", short=True)
c._set_child(a)
c._set_child(b)
v = "Stage_1.thrust"
c._get_child(v).set_value(c._get_child(v).get_value()+199*u.N)
print(c.dump())
```

--------------------------------

### Parse and Navigate SysML Model from String

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Load a SysML model from a string containing package definitions and navigate across packages using a feature chain.

```python
from sysml2py import Model

# Parse a multi-package model from string
model = Model().load("""
package Structures {
    part def Truss;
    part mainTruss : Truss;
}
package Propulsion {
    part def Engine;
    part mainEngine : Engine;
}
""")

# Navigate across packages
truss = model._get_child("Structures.mainTruss")
engine = model._get_child("Propulsion.mainEngine")
print(truss.dump())   # part mainTruss : Truss;
print(engine.dump())  # part mainEngine : Engine;
```

--------------------------------

### Build and Navigate Hierarchical SysML Structure

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates `_set_child` for building nested SysML structures and `_get_child` for traversing them using dot-separated feature chains. Handles missing paths and type errors.

```python
from sysml2py import Part, Item, Attribute
import astropy.units as u

# Build a 3-level hierarchy
stage = Part()._set_name("Stage")
engine = Part()._set_name("engine")
combustion = Part()._set_name("combustion")
thrust_attr = Attribute()._set_name("thrust")
thrust_attr.set_value(1500 * u.N)

stage._set_child(engine)
engine._set_child(combustion)
combustion._set_child(thrust_attr)

print(stage.dump())
# Output:
# part Stage {
#     part engine {
#         part combustion {
#             attribute thrust= 1500.0 [N];
#         }
#     }
# }

# Navigate with dot-separated path
t = stage._get_child("Stage.engine.combustion.thrust")
print(t.dump())  # attribute thrust= 1500.0 [N];

# Can also skip the root element name
t2 = stage._get_child("engine.combustion.thrust")
print(t2.dump())  # attribute তুইhrust= 1500.0 [N];

# Returns None for missing paths, raises TypeError for non-string
print(stage._get_child("Stage.nonexistent"))  # None
try:
    stage._get_child(42)
except TypeError:
    print("Feature chain must be a string")
```

--------------------------------

### Create Nested Packages

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Illustrates how to create a hierarchy of packages, where one package is contained within another. Use this for structuring complex models.

```python
# Nested packages
outer = Package()._set_name("VehicleSystem")
inner = Package()._set_name("EngineSubsystem")
outer._set_child(inner)
print(outer.dump())
```

--------------------------------

### Load Package from Parsed Grammar

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates loading a SysML model from a string containing SysML grammar and accessing elements within a package. Use this for parsing existing SysML definitions.

```python
# Load a package from parsed grammar
from sysml2py import Model
model = Model().load("""
package Rocket {
    item def Fuel;
    item propellant : Fuel;
}""")
p = model._get_child("Rocket")
print(p._get_name())  # Rocket
print(p._get_child("Rocket.propellant").dump())
```

--------------------------------

### Create and Dump SysML Port Definition

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to define a SysML port type. Use this when defining the schema for ports that will be used elsewhere.

```python
# Port definition
fuel_port_def = Port(definition=True)._set_name("FuelPort")
print(fuel_port_def.dump())
```

--------------------------------

### SysML2Py Model Initialization

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows the import statements for creating a SysML Model, Package, Part, and Item. The Model is the root container for parsed SysML documents.

```python
from sysml2py import Model, Package, Part, Item
```

--------------------------------

### Create and Dump SysML Item Definition

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to define a SysML item type. Use this when defining the schema for items that will be used elsewhere.

```python
# Item definition
fuel_def = Item(definition=True)._set_name("Fuel")
print(fuel_def.dump())
# Output: item def Fuel;
```

--------------------------------

### Programmatically Construct SysML Model

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Build a SysML model by creating and nesting packages programmatically. This method is useful for dynamic model generation.

```python
from sysml2py import Model, Package

# Construct programmatically
m = Model()
pkg1 = Package()._set_name("Avionics")
pkg2 = Package()._set_name("Power")
m._set_child(pkg1)
m._set_child(pkg2)
print(m.dump())
# Output:
# package Avionics;
# package Power;
```

--------------------------------

### Navigate Nested Package Content

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to access elements within nested packages using the `_get_child` method. This is useful for retrieving specific model elements.

```python
# Navigate nested content with _get_child
outer._set_child(Part()._set_name("engine"))
child = outer._get_child("VehicleSystem.engine")
print(child.dump())
```

--------------------------------

### Create Nested Parts and Items

Source: https://github.com/westfall-io/sysml2py/blob/main/README.md

Illustrates the creation of nested Parts and Items, along with an Attribute associated with a nested Part.

```python
a = Part()._set_name('camera')
b = Item()._set_name('lens')
d = Attribute()._set_name('mass')
c = Part()._set_name("sensor")
c._set_child(a)
c._set_child(b)
a._set_child(d)
print(c.dump())
```

--------------------------------

### Create Nested Items

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates how to model containment relationships between items, such as a container holding a contained item. Use this for hierarchical structures.

```python
# Nested items
container = Item()._set_name("fuelTank")
contained = Item()._set_name("fuel")
container._set_child(contained)
print(container.dump())
```

--------------------------------

### Create and Dump SysML Attribute Definition

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to define a SysML attribute type. Use this when defining the schema for attributes that will be used elsewhere.

```python
# Attribute definition
mass_def = Attribute(definition=True)._set_name("MassValue")
print(mass_def.dump())
```

--------------------------------

### Create Typed Item within a Package

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Illustrates defining an item type within a package and then using it to type another item. This is useful for organizing and relating item definitions.

```python
# Typed item in a package
pkg = Package()._set_name("FuelSystem")
fuel_def = Item(definition=True)._set_name("Fuel")
hydrogen = Item()._set_name("Hydrogen")
pkg._set_child(hydrogen)
hydrogen._set_typed_by(fuel_def)
print(pkg.dump())
```

--------------------------------

### Build SysML Tree Programmatically

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Construct a SysML model hierarchy by instantiating Part, Attribute, and Package objects and chaining methods like _set_name and _set_child. Use dump() to export the model to SysML v2.0 text. This is useful for generative workflows.

```python
solar = Part()._set_name("solar")
solar._set_child(power_attr)

bus = Part()._set_name("bus")
bus._set_child(solar)

pkg._set_child(bus)
print(pkg.dump())
```

--------------------------------

### Create Attribute with Physical Units

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Shows how to create an attribute with a value and associated physical units using astropy.units. Use this for quantifiable properties.

```python
from sysml2py import Attribute
import astropy.units as u

# Attribute with physical units
mass = Attribute()._set_name("mass")
mass.set_value(100 * u.kg)
print(mass.dump())
```

--------------------------------

### sysml2py.load_grammar(fp, debug=False, enforce=False)

Source: https://github.com/westfall-io/sysml2py/blob/main/docs/source/index.md

Loads a SysML v2.0 document from a file pointer or a string and deserializes it into a Python dictionary object.

```APIDOC
## sysml2py.load_grammar(fp, debug=False, enforce=False)

### Description
SysML load from file pointer. Deserialize `fp` (a `.read()`-supporting file-like object containing a SysML v2.0 document) or `s` (a `str` instance containing a SysML v2.0 document) to a Python dictionary object.

### Parameters
#### Path Parameters
- **fp** (*_io.TextIOWrapper* or *str*) – File pointer to SysML v2.0 document or string instance of SysML v2.0 document
- **debug** (*bool*) – Optional parameter for debug mode.
- **enforce** (*bool*) – Optional parameter for enforcement.

### Returns
Dictionary version structured utilizing SysML v2.0 grammar with some modifications to support available python libraries.

### Return type
dict

### Raises
**TypeError** – Input was not _io.TextIOWrapper
```

--------------------------------

### sysml2py.load(fp)

Source: https://github.com/westfall-io/sysml2py/blob/main/docs/source/index.md

Loads a SysML v2.0 document from a file pointer and deserializes it into a Python dictionary object.

```APIDOC
## sysml2py.load(fp)

### Description
SysML load from file pointer. Deserialize `fp` (a `.read()`-supporting file-like object containing a SysML v2.0 document) to a Python dictionary object.

### Parameters
#### Path Parameters
- **fp** (*_io.TextIOWrapper*) – File pointer to SysML v2.0 document

### Returns
Dictionary version structured utilizing SysML v2.0 grammar with some modifications to support available python libraries.

### Return type
dict

### Raises
**TypeError** – Input was not _io.TextIOWrapper
```

--------------------------------

### Create Dimensionless Attribute

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates creating an attribute without physical units, suitable for counts or simple numerical values. Use this for non-quantifiable properties.

```python
# Attribute without units (dimensionless)
count = Attribute()._set_name("cylinderCount")
count.set_value(4)
print(count.dump())
```

--------------------------------

### load_grammar(fp, debug=False, enforce=False) — Parse SysML to Raw Dictionary

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Low-level parser that returns the raw SysML parse tree as a Python dictionary, without wrapping it in the high-level `Model` class. Accepts either a file pointer or a plain string. Useful for inspecting the full grammar tree.

```APIDOC
## load_grammar(fp, debug=False, enforce=False)

### Description
Low-level parser that returns the raw SysML parse tree as a Python dictionary, without wrapping it in the high-level `Model` class. Accepts either a file pointer or a plain string. Useful for inspecting the full grammar tree.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **debug** (bool) - Optional - If True, enables debug mode for parsing.
- **enforce** (bool) - Optional - If True, enforces grammar rules during parsing.

#### Request Body
None

### Request Example
```python
from sysml2py import load_grammar
from sysml2py.formatting import classtree

sysml_text = """package 'Comment Example' {
    part def Automobile;
    alias Car for Automobile;
}"""

grammar_dict = load_grammar(sysml_text)

# grammar_dict is a raw dictionary representation of the parse tree
# Use classtree to render it back to SysML text
print(classtree(grammar_dict).dump())
# Output:
# package 'Comment Example' {
#     part def Automobile;
#     alias Car for Automobile;
# }

# Also accepts file pointers
with open("temp.sysml", "w") as f:
    f.write(sysml_text)
with open("temp.sysml", "r") as f:
    grammar_dict2 = load_grammar(f)

# Raises TypeError for invalid input
try:
    load_grammar({"not": "valid"})
except TypeError as e:
    print(e)
# the SysML object must be _io.TextIOWrapper or str not dict
```

### Response
#### Success Response (200)
- **grammar_dict** (dict) - A raw dictionary representing the SysML parse tree.

#### Response Example
```json
{
  "package": {
    "name": "'Comment Example'",
    "elements": [
      {
        "part": {
          "definition": true,
          "name": "Automobile"
        }
      },
      {
        "alias": {
          "name": "Car",
          "aliased_type": "Automobile"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Handle Model Loading Error for Non-Package Root

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Illustrates the ValueError raised when attempting to load a SysML model string where the root element is not a package.

```python
from sysml2py import Model

# Must be top-level package (not bare item/part)
try:
    Model().load("item def Fuel;")
except ValueError as e:
    print(e)  # Base Model must be encapsulated by a package.
```

--------------------------------

### load(fp) — Load a Model from a File

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Deserializes a `.sysml` or text file containing a SysML v2.0 document into a `Model` object. Raises `TypeError` if input is not a file pointer (`_io.TextIOWrapper`).

```APIDOC
## load(fp)

### Description
Deserializes a `.sysml` or text file containing a SysML v2.0 document into a `Model` object. Raises `TypeError` if input is not a file pointer (`_io.TextIOWrapper`).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from sysml2py import load

# Write a temp file for demonstration
with open("system.sysml", "w") as f:
    f.write("""
package VehicleSystem {
    part def Vehicle;
    part car : Vehicle;
}
""")

with open("system.sysml", "r") as f:
    model = load(f)

print(model._get_child("VehicleSystem.car").dump())
# Output: part car : Vehicle;

# TypeError is raised for wrong input type
try:
    load("not_a_file_pointer")
except TypeError as e:
    print(e)
# the SysML object must be _io.TextIOWrapper, not str
```

### Response
#### Success Response (200)
- **model** (`Model` object) - The parsed SysML model.

#### Response Example
```
part car : Vehicle;
```
```

--------------------------------

### Parse SysML to Raw Dictionary

Source: https://context7.com/westfall-io/sysml2py/llms.txt

The `load_grammar` function provides a low-level parser that returns the raw SysML parse tree as a Python dictionary. It accepts either a file pointer or a plain string and is useful for inspecting the full grammar tree.

```python
from sysml2py import load_grammar
from sysml2py.formatting import classtree

sysml_text = "package 'Comment Example' {
    part def Automobile;
    alias Car for Automobile;
}"

grammar_dict = load_grammar(sysml_text)

# grammar_dict is a raw dictionary representation of the parse tree
# Use classtree to render it back to SysML text
print(classtree(grammar_dict).dump())
# Output:
# package 'Comment Example' {
#     part def Automobile;
#     alias Car for Automobile;
# }

# Also accepts file pointers
with open("temp.sysml", "w") as f:
    f.write(sysml_text)
with open("temp.sysml", "r") as f:
    grammar_dict2 = load_grammar(f)

# Raises TypeError for invalid input
try:
    load_grammar({"not": "valid"})
except TypeError as e:
    print(e)
# the SysML object must be _io.TextIOWrapper or str not dict
```

--------------------------------

### Serialize SysML Model to SysML v2.0 Text

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates the `dump()` method for serializing a SysML model, including its parts, attributes with values (and units), and nested structures, into a SysML v2.0 compliant text format.

```python
from sysml2py import Package, Part, Item, Attribute
import astropy.units as u

# Full system model serialization
pkg = Package()._set_name("SpacecraftSystem")

# Part definitions
bus_def = Part(definition=True)._set_name("BusPart")
panel_def = Part(definition=True)._set_name("SolarPanel")

# Attribute with value
power_attr = Attribute()._set_name("power")
power_attr.set_value(500 * u.W)

# Example of adding definitions and attributes to the package (not fully shown in source, but implied by dump() usage)
# pkg._set_child(bus_def)
# pkg._set_child(panel_def)
# bus_def._set_child(power_attr) # Example of nesting attribute within a part

# print(pkg.dump()) # This would serialize the constructed model
```

--------------------------------

### Load SysML Model from File

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Use the `load` function to deserialize a `.sysml` or text file containing a SysML v2.0 document into a `Model` object. Raises `TypeError` if input is not a file pointer.

```python
from sysml2py import load

# Write a temp file for demonstration
with open("system.sysml", "w") as f:
    f.write("""
package VehicleSystem {
    part def Vehicle;
    part car : Vehicle;
}
""")

with open("system.sysml", "r") as f:
    model = load(f)

print(model._get_child("VehicleSystem.car").dump())
# Output: part car : Vehicle;

# TypeError is raised for wrong input type
try:
    load("not_a_file_pointer")
except TypeError as e:
    print(e)
# the SysML object must be _io.TextIOWrapper, not str
```

--------------------------------

### `dump()` — Serialize to SysML v2.0 Text

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Serializes a SysML element and its entire subtree into a SysML v2.0 text string. This method is available on all elements and utilizes the compiled TextX grammar for accurate serialization.

```APIDOC
## `dump()` — Serialize to SysML v2.0 Text

Available on all elements. Serializes the element and its entire subtree to a valid SysML v2.0 text string using the compiled TextX grammar.

```python
from sysml2py import Package, Part, Item, Attribute
import astropy.units as u

# Full system model serialization
pkg = Package()._set_name("SpacecraftSystem")

# Part definitions
bus_def = Part(definition=True)._set_name("BusPart")
panel_def = Part(definition=True)._set_name("SolarPanel")

# Attribute with value
power_attr = Attribute()._set_name("power")
power_attr.set_value(500 * u.W)

```
```

--------------------------------

### Create SysML Part Element

Source: https://context7.com/westfall-io/sysml2py/llms.txt

The `Part` class represents a SysML `part` usage or `part def` definition. It supports naming, short-name (reference ID), child elements, and typed-by relationships.

```python
from sysml2py import Part
import astropy.units as u
from sysml2py import Attribute

# Create a part usage
engine = Part()._set_name("engine")
print(engine.dump())
# Output: part engine;

# Create a part definition
engine_def = Part(definition=True)._set_name("Engine")
print(engine_def.dump())
# Output: part def Engine;

# Type a usage by a definition
from sysml2py import Package
pkg = Package()._set_name("VehicleModel")
eng_def = Part(definition=True)._set_name("Engine")
eng_part = Part()._set_name("eng")
pkg._set_child(eng_part)
eng_part._set_typed_by(eng_def)
print(pkg.dump())
# Output:
# package VehicleModel {
#     part def Engine;
#     part eng : Engine;
# }

# Nested parts with attributes
mass_attr = Attribute()._set_name("mass")
mass_attr.set_value(1500)
vehicle = Part()._set_name("vehicle")
vehicle._set_child(engine)
vehicle._set_child(mass_attr)
print(vehicle.dump())
```

--------------------------------

### Load SysML Model from String

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Use the `loads` function to parse a SysML v2.0 string into a navigable `Model` object. The top-level content must be wrapped in one or more `package` blocks.

```python
from sysml2py import loads

sysml_text = """
package RocketSystem {
    part def Stage;
    part def Engine;

    part stage1 : Stage {
        part eng : Engine;
    }
}
"""

model = loads(sysml_text)

# Navigate the tree
rocket_pkg = model._get_child("RocketSystem")
stage1 = model._get_child("RocketSystem.stage1")

# Serialize back to SysML text
print(model.dump())
# Output:
# package RocketSystem {
#     part def Stage;
#     part def Engine;
#     part stage1 : Stage {
#         part eng : Engine;
#     }
# }
```

--------------------------------

### Part — System Part Element

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Represents a SysML `part` usage or `part def` definition. Supports naming, short-name (reference ID), child elements, and typed-by relationships.

```APIDOC
## Part

### Description
Represents a SysML `part` usage or `part def` definition. Supports naming, short-name (reference ID), child elements, and typed-by relationships.

### Methods
- **_set_name(name: str)**: Sets the name of the part.
- **_get_child(name: str)**: Retrieves a child element by its name.
- **_set_child(child)**: Adds a child element to the part.
- **_set_typed_by(type_element)**: Sets the type definition for this part.
- **dump()**: Serializes the part and its children back to SysML v2.0 text.

### Parameters
- **definition** (bool) - Optional - If True, creates a part definition (`part def`); otherwise, creates a part usage.

### Request Example
```python
from sysml2py import Part
import astropy.units as u
from sysml2py import Attribute
from sysml2py import Package

# Create a part usage
engine = Part()._set_name("engine")
print(engine.dump())
# Output: part engine;

# Create a part definition
engine_def = Part(definition=True)._set_name("Engine")
print(engine_def.dump())
# Output: part def Engine;

# Type a usage by a definition
pkg = Package()._set_name("VehicleModel")
eng_def = Part(definition=True)._set_name("Engine")
eng_part = Part()._set_name("eng")
pkg._set_child(eng_part)
eng_part._set_typed_by(eng_def)
print(pkg.dump())
# Output:
# package VehicleModel {
#     part def Engine;
#     part eng : Engine;
# }

# Nested parts with attributes
mass_attr = Attribute()._set_name("mass")
mass_attr.set_value(1500)
vehicle = Part()._set_name("vehicle")
vehicle._set_child(engine)
vehicle._set_child(mass_attr)
print(vehicle.dump())
```

### Response
#### Success Response (200)
- **dump() output** (str) - SysML v2.0 text representation of the Part element and its subtree.

#### Response Example
```
part vehicle {
    part engine;
    attribute mass: 1500;
}
```
```

--------------------------------

### sysml2py.loads(s: str)

Source: https://github.com/westfall-io/sysml2py/blob/main/docs/source/index.md

Loads a SysML model from a string.

```APIDOC
## sysml2py.loads(s: str)

### Description
Loads a model from string. This shortcut function allows a user to build a model from a string by first instantiating a base model class which builds out a default namespace and then that model loads all elements underneath.

### Parameters
#### Path Parameters
- **s** (*str*) – String instance containing a SysML v2.0 document

### Returns
Dictionary version structured utilizing SysML v2.0 grammar with some modifications to support available python libraries.

### Return type
dict
```

--------------------------------

### Handle Empty Model Serialization Error

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates the expected ValueError when attempting to dump an empty SysML Model that has not been loaded or constructed with elements.

```python
from sysml2py import Model

# Model without children raises ValueError
empty = Model()
try:
    empty.dump()
except ValueError as e:
    print(e)  # Base Model has no elements to output.
```

--------------------------------

### loads(s: str) — Load a Model from a SysML String

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Parses a SysML v2.0 string and returns a Model object with navigable children. The top-level content must be wrapped in one or more package blocks.

```APIDOC
## loads(s: str)

### Description
Parses a SysML v2.0 string and returns a `Model` object with navigable children. The top-level content must be wrapped in one or more `package` blocks.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from sysml2py import loads

sysml_text = """
package RocketSystem {
    part def Stage;
    part def Engine;

    part stage1 : Stage {
        part eng : Engine;
    }
}
"""

model = loads(sysml_text)

# Navigate the tree
rocket_pkg = model._get_child("RocketSystem")
stage1 = model._get_child("RocketSystem.stage1")

# Serialize back to SysML text
print(model.dump())
```

### Response
#### Success Response (200)
- **model** (`Model` object) - The parsed SysML model.

#### Response Example
```
package RocketSystem {
    part def Stage;
    part def Engine;
    part stage1 : Stage {
        part eng : Engine;
    }
}
```
```

--------------------------------

### Type SysML Elements using Definitions

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Use `_set_typed_by` to link usage elements (like parts or items) to their corresponding definition elements. Includes error handling for invalid typing scenarios.

```python
from sysml2py import Part, Item, Package

# Type a part usage by a part definition
pkg = Package()._set_name("VehicleModel")
engine_def = Part(definition=True)._set_name("Engine")
engine_part = Part()._set_name("eng")
pkg._set_child(engine_part)
engine_part._set_typed_by(engine_def)
print(pkg.dump())
# Output:
# package VehicleModel {
#     part def Engine;
#     part eng : Engine;
# }

# Type an item usage by an item definition
pkg2 = Package()._set_name("FuelSystem")
fuel_def = Item(definition=True)._set_name("Fuel")
propellant = Item()._set_name("propellant")
pkg2._set_child(propellant)
propellant._set_typed_by(fuel_def)
print(pkg2.dump())
# Output:
# package FuelSystem {
#     item def Fuel;
#     item propellant : Fuel;
# }

# Error: cannot type a usage by another usage
try:
    Part()._set_typed_by(Part())
except ValueError as e:
    print(e)  # Typed by element was not a definition.

# Error: a definition cannot be typed
try:
    Part(definition=True)._set_typed_by(Part(definition=True))
except ValueError as e:
    print(e)  # A definition element cannot be defined.
```

--------------------------------

### `_set_child(child)` / `_get_child(featurechain)` — Tree Composition and Navigation

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Allows for the composition of element trees by appending child elements and navigating through the tree structure using a dot-separated feature chain string. `_set_child` adds a child, while `_get_child` retrieves elements from the tree.

```APIDOC
## `_set_child(child)` / `_get_child(featurechain)` — Tree Composition and Navigation

`_set_child` appends a child element to the current element's body. `_get_child` traverses the element tree using a dot-separated feature chain string.

```python
from sysml2py import Part, Item, Attribute
import astropy.units as u

# Build a 3-level hierarchy
stage = Part()._set_name("Stage")
engine = Part()._set_name("engine")
combustion = Part()._set_name("combustion")
thrust_attr = Attribute()._set_name("thrust")
thrust_attr.set_value(1500 * u.N)

stage._set_child(engine)
engine._set_child(combustion)
combustion._set_child(thrust_attr)

print(stage.dump())
# Output:
# part Stage {
#     part engine {
#         part combustion {
#             attribute thrust= 1500.0 [N];
#         }
#     }
# }

# Navigate with dot-separated path
t = stage._get_child("Stage.engine.combustion.thrust")
print(t.dump())  # attribute thrust= 1500.0 [N];

# Can also skip the root element name
t2 = stage._get_child("engine.combustion.thrust")
print(t2.dump())  # attribute thrust= 1500.0 [N];

# Returns None for missing paths, raises TypeError for non-string
print(stage._get_child("Stage.nonexistent"))  # None
try:
    stage._get_child(42)
except TypeError:
    print("Feature chain must be a string")
```
```

--------------------------------

### Set Element Name and Short Name

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Use `_set_name` to assign a regular name or a short name (reference ID) to SysML elements like Parts and Packages. Supports method chaining.

```python
from sysml2py import Part, Package

# Set regular name
p = Part()._set_name("FuelTank")
print(p.dump())  # part FuelTank;

# Set short name (requirement/document reference ID)
p2 = Part()._set_name("Stage_1")._set_name("'3.1'", short=True)
print(p2.dump())  # part <'3.1'> Stage_1;

# Retrieve the declared name
pkg = Package()._set_name("Rocket")
print(pkg._get_name())  # Rocket
```

--------------------------------

### SysML Round-trip: Parse, Modify, Dump

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Parse an existing SysML string into Python objects using loads(), inspect or modify the model, and then re-export it using dump(). This enables integration with existing toolchains for reading, inspecting, and modifying SysML models.

```python
from sysml2py import loads
model = loads("""
package Rocket {
    part def Stage;
    part stage1 : Stage;
}
""")
print(model.dump())
```

--------------------------------

### Handle Invalid Port Direction

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Demonstrates the error handling for invalid direction types when adding directed features to a port. The direction must be 'in', 'out', or 'inout'.

```python
# Invalid direction raises ValueError
try:
    fuel_hose.add_directed_feature("sideways", "fuel")
except ValueError:
    print("Direction must be 'in', 'out', or 'inout'")
```

--------------------------------

### `_set_typed_by(definition)` — Type a Usage by a Definition

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Links a usage element to its definition, analogous to the ':' typing operator in SysML. This method enforces that one element is a usage and the other is a definition, raising a `ValueError` if both are of the same type.

```APIDOC
## `_set_typed_by(definition)` — Type a Usage by a Definition

Links a usage element to its definition (the `:` typing operator in SysML). The definition must be an element constructed with `definition=True`. Raises `ValueError` if both elements are usages or both are definitions.

```python
from sysml2py import Part, Item, Package

# Type a part usage by a part definition
pkg = Package()._set_name("VehicleModel")
engine_def = Part(definition=True)._set_name("Engine")
engine_part = Part()._set_name("eng")
pkg._set_child(engine_part)
engine_part._set_typed_by(engine_def)
print(pkg.dump())
# Output:
# package VehicleModel {
#     part def Engine;
#     part eng : Engine;
# }

# Type an item usage by an item definition
pkg2 = Package()._set_name("FuelSystem")
fuel_def = Item(definition=True)._set_name("Fuel")
propellant = Item()._set_name("propellant")
pkg2._set_child(propellant)
propellant._set_typed_by(fuel_def)
print(pkg2.dump())
# Output:
# package FuelSystem {
#     item def Fuel;
#     item propellant : Fuel;
# }

# Error: cannot type a usage by another usage
try:
    Part()._set_typed_by(Part())
except ValueError as e:
    print(e)  # Typed by element was not a definition.

# Error: a definition cannot be typed
try:
    Part(definition=True)._set_typed_by(Part(definition=True))
except ValueError as e:
    print(e)  # A definition element cannot be defined.
```
```

--------------------------------

### `_set_name(name, short=False)` — Set Element Name

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Sets the declared name or short name (reference ID) for a SysML element. This method is available on all Usage-based elements and Packages and supports method chaining.

```APIDOC
## `_set_name(name, short=False)` — Set Element Name

Available on all `Usage`-based elements and `Package`. Sets the declared name (default) or the declared short name (reference ID) when `short=True`. Returns `self` for method chaining.

```python
from sysml2py import Part, Package

# Set regular name
p = Part()._set_name("FuelTank")
print(p.dump())  # part FuelTank;

# Set short name (requirement/document reference ID)
p2 = Part()._set_name("Stage_1")._set_name("'3.1'", short=True)
print(p2.dump())  # part <'3.1'> Stage_1;

# Retrieve the declared name
pkg = Package()._set_name("Rocket")
print(pkg._get_name())  # Rocket
```
```

--------------------------------

### Modify Nested Attribute Value

Source: https://context7.com/westfall-io/sysml2py/llms.txt

Illustrates how to access and modify a nested attribute's value through its parent part. Use this for updating properties within complex structures.

```python
# Modify a nested attribute via _get_child
from sysml2py import Part
thrust = Attribute()._set_name("thrust")
thrust.set_value(1000 * u.N)
rocket = Part()._set_name("Stage_1")._set_name("'3.1'", short=True)
rocket._set_child(thrust)

child = rocket._get_child("Stage_1.thrust")
child.set_value(child.get_value() + 199 * u.N)
print(rocket.dump())
```
Tokens:
Raw