Data Model Component Requirements

UML Diagram

@startuml DataModel skinparam classAttributeIconSize 0 abstract class BaseObject { +parent: ComplexInstance +_id: UUID +_name: String <<transient>> +_hash_name: String +attribute_dict: AttributeDict -- +id: UUID <<virtual, persistent, readonly>> +name: String <<virtual, writable>> +hash_name: String <<virtual, persistent, readonly>> +created_at: DateTime <<virtual, readonly>> +updated_at: DateTime <<virtual, readonly>> +path: String <<virtual, readonly>> +set_name(name: String): void +_refresh_hash_name(): void +get(key: String): Any +set(key: String, value: Any): void } abstract class LocatableInstance { +position: Point2D +size: Size2D -- +x: float <<virtual, writable>> +y: float <<virtual, writable>> +set_xy(pos: Point2DOrTuple): void } class ElementaryInstance { +type_key: String +pin: Map -- +in_pins: PinList <<derived>> +out_pins: PinList <<derived>> } class Variable { +value: Any +unit: String } class BasicOperator { +operation: BasicOperatorType } class ComplexInstance { +children: BaseObjectList +children_by_hash_name: HashNameMap -- +paste(obj: BaseObject): void +del(id: UUID): void +get_child(ref: String): BaseObject } class Connector { +source_instance_id: UUID +source_pin: String +target_instance_id: UUID +target_pin: String +directed: bool -- +validate_endpoints(): bool } class Pin { +name: String +direction: PinDirection +data_type: String } class Point2D { +x: float +y: float } class Size2D { +width: float +height: float } enum PinDirection { IN OUT } enum BasicOperatorType { PLUS MINUS MULTIPLY DIVIDE } note right of BasicOperatorType PLUS = "+" MINUS = "-" MULTIPLY = "*" DIVIDE = "/" end note class AttributeDict { +get(key: String): Any +set(key: String, value: Any): void +set_virtual(key: String, getter: Callable, setter: Callable): void +virtual(key: String): bool +exposed(key: String): bool +writable(key: String): bool } BaseObject <|-- LocatableInstance LocatableInstance <|-- ElementaryInstance LocatableInstance <|-- ComplexInstance ElementaryInstance <|-- Variable ElementaryInstance <|-- BasicOperator BaseObject <|-- Connector note bottom of ElementaryInstance FMU-oriented diagram blocks use **MODEL.ELEMENTARY** with a library ``type_key`` and optional ``fmu`` subtree (path, fmi_version, …) — no separate model type. end note ComplexInstance *-- BaseObject ElementaryInstance *-- Pin BaseObject *-- AttributeDict Connector --> ElementaryInstance @enduml

The requirements on this page are intended as a supplement to the UML diagram above. The software architecture of the data model must conform to this UML diagram.

CORE-COMP-MODEL-012 Model aggregate with explicit infrastructure boundary
status: Must

The data model shall provide a top-level model/document aggregate that owns the root object and a shared model context. The model context shall host infrastructure services such as ID management, while domain objects remain focused on domain behavior.
CORE-COMP-MODEL-013 Attached and detached object lifecycle
status: Must

Model objects may exist detached from a model context and become attached when inserted into a model. Attached objects shall have a model-registered ID; detached objects shall not be treated as persistent model members.
CORE-COMP-MODEL-014 Central ID factory and registry operations
status: Must

A central ID factory shall provide new_id, reserve, contains, and unregister operations. ID reservation shall reject duplicates within one model context.
CORE-COMP-MODEL-015 ID lifecycle for load, delete, and paste/import
status: Must

Loading an existing model shall reserve all existing IDs and fail on duplicates. Deleting objects shall unregister IDs for the full removed subtree. Pasting within the same model shall remap IDs by default.
CORE-COMP-MODEL-016 Tree-first navigation for CLI
status: Must

The data model shall support tree-oriented navigation semantics for CLI usage. Model objects shall provide get_root and get_root_model to resolve tree and model context ownership.
CORE-COMP-MODEL-001 Node/Connector Model with Pins
status: Must

Elements provide defined inputs/outputs, and connections are modeled explicitly.
CORE-COMP-MODEL-002 Stable Object Addressing
status: Must

Access by body key, name, display name, and ID is consistently supported.
CORE-COMP-MODEL-003 ObjectHandler as Central Variable Layer
status: Should

Variable instances are consolidated so mapping and recorder features rely on a central structure.
CORE-COMP-MODEL-004 Persistent Object Storage
status: Must

Objects are stored in a central SQLAlchemy + SQLite database, while model instances are represented in a model tree. A variable may appear multiple times in the model tree while still representing a single logical variable.
CORE-COMP-MODEL-005 Persistent hash_name lifecycle
status: Must

The BaseObject shall persist id and hash_name. hash_name shall be generated as <name>@<id> and updated when name changes while preserving the @<id> suffix.
CORE-COMP-MODEL-006 Virtual attributes exposure and write rules
status: Must

AttributeDict shall expose id, name, hash_name, and path as virtual attributes. id and hash_name shall be read-only; name shall be writable. path shall be read-only.
CORE-COMP-MODEL-017 Core model ``type`` (MODEL.*) stored and read-only
status: Must

Each model object shall carry a type attribute as a stored, exposed, non-writable MODEL.* string as specified in Core type system (model type attribute). The value shall be distinct from ElementaryInstance.type_key (library / functional element name).
CORE-COMP-MODEL-007 Child lookup and movement semantics
status: Must

ComplexInstance.get_child shall resolve children by id and by hash_name. LocatableInstance shall not provide a move_to method. Position updates shall be performed via set_xy only. set_xy shall accept either a Point2D value or a 2-tuple (x, y).
CORE-COMP-MODEL-008 BaseObject transient name and timestamps ownership
status: Must

BaseObject._name shall be transient and non-persistent. created_at and updated_at shall be managed by AttributeDict only.
CORE-COMP-MODEL-009 Hash-indexed children map
status: Must

ComplexInstance shall maintain a dictionary of children keyed by hash_name.
CORE-COMP-MODEL-010 ElementaryInstance specializations
status: Must

ElementaryInstance shall be specialized by Variable and BasicOperator. BasicOperator shall contain an operation field typed as a string enumeration with the values "+", "-", "*", and "/" to indicate the arithmetic operation.
CORE-COMP-MODEL-011 Data model architecture compliance
status: Must

The software architecture of the data model shall conform to the UML diagram on this page.