sysml2kit 0.0.1__py3-none-any.whl

sysml2kit/model/builder.py

@@ -0,0 +1,239 @@
+"""Fluent authoring helpers: the API humans and agents actually type.
+
+Each helper constructs an element, registers it in the model under the given
+owner, and returns it. The raw element classes stay the interchange-faithful
+layer; nothing here adds state the classes lack.
+"""
+
+from __future__ import annotations
+
+from sysml2kit.model.analysis import AnalysisCaseDefinition, AnalysisCaseUsage
+from sysml2kit.model.base import Element, Ref
+from sysml2kit.model.container import Model
+from sysml2kit.model.metadata import MetadataUsage
+from sysml2kit.model.relations import (
+    AllocateRelationship,
+    DeriveRelationship,
+    SatisfyRelationship,
+    VerifyRelationship,
+)
+from sysml2kit.model.requirements import RequirementDefinition, RequirementUsage
+from sysml2kit.model.structure import (
+    AttributeDefinition,
+    AttributeUsage,
+    ConnectionUsage,
+    Package,
+    PartDefinition,
+    PartUsage,
+    PortDefinition,
+    PortUsage,
+)
+from sysml2kit.model.values import AttributeValue
+
+
+def pkg(
+    model: Model, name: str, *, owner: Element | None = None, doc: str | None = None
+) -> Package:
+    """Create a package."""
+    return model.add(Package(declared_name=name, doc=doc), owner=owner)  # type: ignore[return-value]
+
+
+def part_def(
+    model: Model, name: str, *, owner: Element | None = None, doc: str | None = None
+) -> PartDefinition:
+    """Create a part definition."""
+    return model.add(PartDefinition(declared_name=name, doc=doc), owner=owner)  # type: ignore[return-value]
+
+
+def part(
+    model: Model,
+    name: str,
+    *,
+    owner: Element | None = None,
+    definition: Element | None = None,
+    multiplicity: str | None = None,
+    doc: str | None = None,
+) -> PartUsage:
+    """Create a part usage, optionally typed by a part definition."""
+    usage = PartUsage(
+        declared_name=name,
+        definition=Ref.to(definition) if definition else None,
+        multiplicity=multiplicity,
+        doc=doc,
+    )
+    return model.add(usage, owner=owner)  # type: ignore[return-value]
+
+
+def port_def(
+    model: Model, name: str, *, owner: Element | None = None, doc: str | None = None
+) -> PortDefinition:
+    """Create a port definition."""
+    return model.add(PortDefinition(declared_name=name, doc=doc), owner=owner)  # type: ignore[return-value]
+
+
+def port(
+    model: Model,
+    name: str,
+    *,
+    owner: Element | None = None,
+    definition: Element | None = None,
+) -> PortUsage:
+    """Create a port usage on a part."""
+    usage = PortUsage(
+        declared_name=name,
+        definition=Ref.to(definition) if definition else None,
+    )
+    return model.add(usage, owner=owner)  # type: ignore[return-value]
+
+
+def connect(
+    model: Model,
+    source: Element,
+    target: Element,
+    *,
+    owner: Element | None = None,
+    name: str | None = None,
+) -> ConnectionUsage:
+    """Create a connection between two ports (or parts)."""
+    usage = ConnectionUsage(declared_name=name, source=Ref.to(source), target=Ref.to(target))
+    return model.add(usage, owner=owner)  # type: ignore[return-value]
+
+
+def attr_def(
+    model: Model,
+    name: str,
+    *,
+    owner: Element | None = None,
+    unit: str | None = None,
+    doc: str | None = None,
+) -> AttributeDefinition:
+    """Create an attribute definition, optionally with a default unit."""
+    return model.add(  # type: ignore[return-value]
+        AttributeDefinition(declared_name=name, unit=unit, doc=doc), owner=owner
+    )
+
+
+def attr(
+    model: Model,
+    name: str,
+    value: float | str | bool | None = None,
+    *,
+    owner: Element | None = None,
+    unit: str | None = None,
+    definition: Element | None = None,
+    source: str | None = None,
+) -> AttributeUsage:
+    """Create an attribute usage holding a value with optional unit and provenance."""
+    usage = AttributeUsage(
+        declared_name=name,
+        definition=Ref.to(definition) if definition else None,
+        value=AttributeValue(value=value, unit=unit, source=source) if value is not None else None,
+    )
+    return model.add(usage, owner=owner)  # type: ignore[return-value]
+
+
+def req_def(
+    model: Model, name: str, *, owner: Element | None = None, doc: str | None = None
+) -> RequirementDefinition:
+    """Create a requirement definition."""
+    return model.add(RequirementDefinition(declared_name=name, doc=doc), owner=owner)  # type: ignore[return-value]
+
+
+def req(
+    model: Model,
+    short_name: str,
+    name: str,
+    *,
+    owner: Element | None = None,
+    text: str | None = None,
+    subject: Element | None = None,
+    definition: Element | None = None,
+) -> RequirementUsage:
+    """Create a requirement usage; ``short_name`` is the requirement id (e.g. REQ-001)."""
+    usage = RequirementUsage(
+        declared_short_name=short_name,
+        declared_name=name,
+        text=text,
+        subject=Ref.to(subject) if subject else None,
+        definition=Ref.to(definition) if definition else None,
+    )
+    return model.add(usage, owner=owner)  # type: ignore[return-value]
+
+
+def analysis_def(
+    model: Model, name: str, *, owner: Element | None = None, doc: str | None = None
+) -> AnalysisCaseDefinition:
+    """Create an analysis case definition."""
+    return model.add(AnalysisCaseDefinition(declared_name=name, doc=doc), owner=owner)  # type: ignore[return-value]
+
+
+def analysis(
+    model: Model,
+    name: str,
+    *,
+    owner: Element | None = None,
+    subject: Element | None = None,
+    objective: str | None = None,
+    definition: Element | None = None,
+) -> AnalysisCaseUsage:
+    """Create an analysis case usage."""
+    usage = AnalysisCaseUsage(
+        declared_name=name,
+        subject=Ref.to(subject) if subject else None,
+        objective=objective,
+        definition=Ref.to(definition) if definition else None,
+    )
+    return model.add(usage, owner=owner)  # type: ignore[return-value]
+
+
+def metadata(
+    model: Model,
+    annotated: Element,
+    values: dict[str, str | float | int | bool],
+    *,
+    owner: Element | None = None,
+    name: str | None = None,
+) -> MetadataUsage:
+    """Attach a key-value metadata annotation to an element."""
+    usage = MetadataUsage(declared_name=name, annotated=Ref.to(annotated), values=dict(values))
+    return model.add(usage, owner=owner if owner is not None else annotated)  # type: ignore[return-value]
+
+
+def _relate(
+    model: Model,
+    cls: type[SatisfyRelationship | VerifyRelationship | DeriveRelationship | AllocateRelationship],
+    source: Element,
+    target: Element,
+    owner: Element | None,
+) -> Element:
+    rel = cls(source=Ref.to(source), target=Ref.to(target))
+    fallback = model.owner_of(source)
+    return model.add(rel, owner=owner if owner is not None else fallback)
+
+
+def satisfy(
+    model: Model, *, source: Element, target: Element, owner: Element | None = None
+) -> SatisfyRelationship:
+    """Record that ``source`` (a design element) satisfies ``target`` (a requirement)."""
+    return _relate(model, SatisfyRelationship, source, target, owner)  # type: ignore[return-value]
+
+
+def verify(
+    model: Model, *, source: Element, target: Element, owner: Element | None = None
+) -> VerifyRelationship:
+    """Record that ``source`` (an analysis/test) verifies ``target`` (a requirement)."""
+    return _relate(model, VerifyRelationship, source, target, owner)  # type: ignore[return-value]
+
+
+def derive(
+    model: Model, *, source: Element, target: Element, owner: Element | None = None
+) -> DeriveRelationship:
+    """Record that requirement ``source`` derives from requirement ``target``."""
+    return _relate(model, DeriveRelationship, source, target, owner)  # type: ignore[return-value]
+
+
+def allocate(
+    model: Model, *, source: Element, target: Element, owner: Element | None = None
+) -> AllocateRelationship:
+    """Record that ``source`` is allocated to ``target`` (a part)."""
+    return _relate(model, AllocateRelationship, source, target, owner)  # type: ignore[return-value]

sysml2kit/model/container.py

@@ -0,0 +1,220 @@
+"""The Model container: element registry, identity, and ownership.
+
+Ownership lives here (owner/owned maps keyed by element id), not on the
+elements, mirroring how the Systems Modeling API keeps owning-relationship
+records separate from element payloads.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterator, Sequence
+from uuid import UUID
+
+from sysml2kit.model.base import Element, Ref, Relationship
+
+#: Namespace for stable UUIDv5 ids derived from qualified names.
+STABLE_ID_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS, "sysml2kit")
+
+
+class Model:
+    """A set of elements with identity, ownership, and lookup."""
+
+    def __init__(self) -> None:
+        self.elements: dict[UUID, Element] = {}
+        self.owner: dict[UUID, UUID] = {}
+        self.owned: dict[UUID, list[UUID]] = {}
+        self.roots: list[UUID] = []
+
+    # ------------------------------------------------------------- mutation
+    def add(self, element: Element, owner: Element | UUID | None = None) -> Element:
+        """Register an element, optionally under an owner already in the model."""
+        eid = element.element_id
+        if eid in self.elements:
+            raise ValueError(f"duplicate element id {eid}")
+        self.elements[eid] = element
+        if owner is None:
+            self.roots.append(eid)
+        else:
+            oid = owner if isinstance(owner, UUID) else owner.element_id
+            if oid not in self.elements:
+                raise KeyError(f"owner {oid} is not in the model")
+            self.owner[eid] = oid
+            self.owned.setdefault(oid, []).append(eid)
+        return element
+
+    def remove(self, element: Element | UUID) -> None:
+        """Remove an element and reparent nothing: its owned elements become roots."""
+        eid = element if isinstance(element, UUID) else element.element_id
+        if eid not in self.elements:
+            raise KeyError(f"element {eid} is not in the model")
+        for child in self.owned.pop(eid, []):
+            del self.owner[child]
+            self.roots.append(child)
+        oid = self.owner.pop(eid, None)
+        if oid is None:
+            self.roots.remove(eid)
+        else:
+            self.owned[oid].remove(eid)
+        del self.elements[eid]
+
+    # --------------------------------------------------------------- lookup
+    def resolve(self, ref: Ref | UUID) -> Element:
+        """Return the element a ref (or id) points at."""
+        eid = ref.target if isinstance(ref, Ref) else ref
+        return self.elements[eid]
+
+    def owner_of(self, element: Element | UUID) -> Element | None:
+        """Return the owning element, or None for a root."""
+        eid = element if isinstance(element, UUID) else element.element_id
+        oid = self.owner.get(eid)
+        return self.elements[oid] if oid is not None else None
+
+    def owned_by(self, element: Element | UUID) -> list[Element]:
+        """Return the owned elements, in insertion order."""
+        eid = element if isinstance(element, UUID) else element.element_id
+        return [self.elements[cid] for cid in self.owned.get(eid, [])]
+
+    def qualified_name(self, element: Element | UUID) -> str:
+        """Return the ``::``-joined name path from the root to this element.
+
+        Unnamed elements contribute their kind and a positional index, so the
+        path is always defined (and usable for stable-id hashing).
+        """
+        eid = element if isinstance(element, UUID) else element.element_id
+        parts: list[str] = []
+        current: UUID | None = eid
+        while current is not None:
+            el = self.elements[current]
+            parts.append(el.declared_name or self._positional_name(current))
+            current = self.owner.get(current)
+        return "::".join(reversed(parts))
+
+    def _positional_name(self, eid: UUID) -> str:
+        el = self.elements[eid]
+        oid = self.owner.get(eid)
+        siblings = self.owned.get(oid, []) if oid is not None else self.roots
+        index = siblings.index(eid)
+        return f"{type(el).__name__}#{index}"
+
+    def find(
+        self,
+        *,
+        name: str | None = None,
+        kind: type[Element] | None = None,
+    ) -> list[Element]:
+        """Return elements matching a declared name and/or a class."""
+        out: list[Element] = []
+        for el in self.iter_elements(kind=kind):
+            if name is not None and el.declared_name != name:
+                continue
+            out.append(el)
+        return out
+
+    def find_by_qualified_name(self, qualified: str) -> Element | None:
+        """Return the element with this exact qualified name, if any."""
+        for eid in self.elements:
+            if self.qualified_name(eid) == qualified:
+                return self.elements[eid]
+        return None
+
+    def iter_elements(self, *, kind: type[Element] | None = None) -> Iterator[Element]:
+        """Iterate elements in ownership (depth-first) order."""
+        for eid in self._walk():
+            el = self.elements[eid]
+            if kind is None or isinstance(el, kind):
+                yield el
+
+    def _walk(self) -> Iterator[UUID]:
+        stack = list(reversed(self.roots))
+        while stack:
+            eid = stack.pop()
+            yield eid
+            stack.extend(reversed(self.owned.get(eid, [])))
+
+    def relationships(
+        self,
+        *,
+        kind: type[Relationship] | None = None,
+        source: Element | UUID | None = None,
+        target: Element | UUID | None = None,
+    ) -> list[Relationship]:
+        """Return relationships filtered by class and/or endpoint."""
+        sid = source.element_id if isinstance(source, Element) else source
+        tid = target.element_id if isinstance(target, Element) else target
+        out: list[Relationship] = []
+        for el in self.elements.values():
+            if not isinstance(el, Relationship):
+                continue
+            if kind is not None and not isinstance(el, kind):
+                continue
+            if sid is not None and el.source.target != sid:
+                continue
+            if tid is not None and el.target.target != tid:
+                continue
+            out.append(el)
+        return out
+
+    # ------------------------------------------------------------ integrity
+    def check_refs(self) -> list[tuple[UUID, str, UUID]]:
+        """Return (element_id, field_name, missing_target) for dangling refs."""
+        dangling: list[tuple[UUID, str, UUID]] = []
+        for el in self.elements.values():
+            for field, ref in self._refs_of(el):
+                if ref.target not in self.elements:
+                    dangling.append((el.element_id, field, ref.target))
+        return dangling
+
+    @staticmethod
+    def _refs_of(element: Element) -> list[tuple[str, Ref]]:
+        refs: list[tuple[str, Ref]] = []
+        for field in type(element).model_fields:
+            value = getattr(element, field)
+            if isinstance(value, Ref):
+                refs.append((field, value))
+            elif isinstance(value, Sequence) and not isinstance(value, str | bytes):
+                refs.extend((field, item) for item in value if isinstance(item, Ref))
+        return refs
+
+    def assign_stable_ids(self) -> dict[UUID, UUID]:
+        """Rewrite every element id as a UUIDv5 hash of its qualified name.
+
+        Returns the old-to-new id mapping. Refs, ownership maps, and roots are
+        remapped in place. Run this before committing generated interchange
+        files so regeneration produces stable diffs.
+        """
+        mapping = {
+            eid: uuid.uuid5(STABLE_ID_NAMESPACE, self.qualified_name(eid)) for eid in self.elements
+        }
+        if len(set(mapping.values())) != len(mapping):
+            raise ValueError(
+                "duplicate qualified names; stable ids need unique name paths "
+                "(rename the clashing siblings, see validation rule S2K003)"
+            )
+        new_elements: dict[UUID, Element] = {}
+        for eid, el in self.elements.items():
+            updates: dict[str, object] = {"element_id": mapping[eid]}
+            for field, ref in self._refs_of(el):
+                value = getattr(el, field)
+                if isinstance(value, Ref):
+                    updates[field] = Ref(target=mapping.get(ref.target, ref.target))
+            for field in type(el).model_fields:
+                value = getattr(el, field)
+                if (
+                    isinstance(value, Sequence)
+                    and not isinstance(value, str | bytes)
+                    and any(isinstance(item, Ref) for item in value)
+                ):
+                    updates[field] = [
+                        Ref(target=mapping.get(item.target, item.target))
+                        if isinstance(item, Ref)
+                        else item
+                        for item in value
+                    ]
+            new_el = el.model_copy(update=updates)
+            new_elements[new_el.element_id] = new_el
+        self.elements = new_elements
+        self.owner = {mapping[k]: mapping[v] for k, v in self.owner.items()}
+        self.owned = {mapping[k]: [mapping[c] for c in v] for k, v in self.owned.items()}
+        self.roots = [mapping[r] for r in self.roots]
+        return mapping

sysml2kit/model/metadata.py

@@ -0,0 +1,19 @@
+"""Metadata annotation elements."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from sysml2kit.model.base import Element, Ref
+
+
+class MetadataDefinition(Element):
+    """A reusable definition of a metadata annotation kind."""
+
+
+class MetadataUsage(Element):
+    """A metadata annotation on another element, as a key-value mapping."""
+
+    definition: Ref | None = None
+    annotated: Ref | None = None
+    values: dict[str, str | float | int | bool] = Field(default_factory=dict)

sysml2kit/model/relations.py

@@ -0,0 +1,26 @@
+"""Reified traceability relationships.
+
+The spec models some of these as membership forms; sysml2kit reifies each as
+a first-class relationship with ``source``/``target`` refs (a documented
+deviation, see SPEC.md).
+"""
+
+from __future__ import annotations
+
+from sysml2kit.model.base import Relationship
+
+
+class SatisfyRelationship(Relationship):
+    """``source`` (a part or design element) satisfies ``target`` (a requirement)."""
+
+
+class VerifyRelationship(Relationship):
+    """``source`` (an analysis or test case) verifies ``target`` (a requirement)."""
+
+
+class DeriveRelationship(Relationship):
+    """``source`` (a requirement) is derived from ``target`` (a requirement)."""
+
+
+class AllocateRelationship(Relationship):
+    """``source`` (a function or requirement) is allocated to ``target`` (a part)."""

sysml2kit/model/requirements.py

@@ -0,0 +1,23 @@
+"""Requirement and constraint elements."""
+
+from __future__ import annotations
+
+from sysml2kit.model.base import Element, Ref
+
+
+class RequirementDefinition(Element):
+    """A reusable definition of a requirement kind."""
+
+
+class RequirementUsage(Element):
+    """A requirement occurrence with an optional subject and statement text."""
+
+    definition: Ref | None = None
+    subject: Ref | None = None
+    text: str | None = None
+
+
+class ConstraintUsage(Element):
+    """A constraint; the expression is an opaque string in v0.1."""
+
+    expression: str | None = None

sysml2kit/model/structure.py

@@ -0,0 +1,60 @@
+"""Structural elements: packages, parts, ports, interfaces, connections."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from sysml2kit.model.base import Element, Ref
+from sysml2kit.model.values import AttributeValue
+
+
+class Package(Element):
+    """A namespace for other elements; maps to a top-level ``.sysml`` file."""
+
+    imports: list[str] = Field(default_factory=list)
+
+
+class PartDefinition(Element):
+    """A reusable definition of a system component kind."""
+
+
+class PartUsage(Element):
+    """A component occurrence, optionally typed by a :class:`PartDefinition`."""
+
+    definition: Ref | None = None
+    multiplicity: str | None = None
+
+
+class PortDefinition(Element):
+    """A reusable definition of an interaction point kind."""
+
+
+class PortUsage(Element):
+    """A port occurrence on a part, optionally typed by a :class:`PortDefinition`."""
+
+    definition: Ref | None = None
+
+
+class InterfaceDefinition(Element):
+    """A definition of how two ports connect."""
+
+
+class ConnectionUsage(Element):
+    """A connection between two port (or part) ends."""
+
+    definition: Ref | None = None
+    source: Ref | None = None
+    target: Ref | None = None
+
+
+class AttributeDefinition(Element):
+    """A reusable definition of a value kind, e.g. a quantity with a unit."""
+
+    unit: str | None = None
+
+
+class AttributeUsage(Element):
+    """A value occurrence, optionally typed and optionally holding a value."""
+
+    definition: Ref | None = None
+    value: AttributeValue | None = None

sysml2kit/model/values.py

@@ -0,0 +1,31 @@
+"""Attribute values with units and provenance.
+
+Follows the ``Assumption`` pattern from spacedc-mdao: a number in a model
+should say where it came from. Units are stored as text (what the textual
+notation carries, e.g. ``"dBW"``); ``sysml2kit.units`` checks them against
+pint during validation.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AttributeValue(BaseModel):
+    """A literal value with optional unit text and provenance."""
+
+    model_config = ConfigDict(frozen=True)
+
+    value: float | int | str | bool | None = None
+    unit: str | None = None
+    source: str | None = None
+    confidence: Literal["low", "medium", "high"] | None = None
+
+    def render(self) -> str:
+        """Render as textual-notation value text, e.g. ``52.0 [dBW]``."""
+        body = f'"{self.value}"' if isinstance(self.value, str) else str(self.value)
+        if self.unit:
+            return f"{body} [{self.unit}]"
+        return body

sysml2kit/units.py

@@ -0,0 +1,60 @@
+"""Unit-string helpers backed by pint.
+
+Models store units as text (round-trip fidelity with the textual notation);
+these helpers check and convert them. A few decibel spellings common in
+engineering practice are registered on top of pint's defaults.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+import pint
+
+_EXTRA_DEFINITIONS = (
+    # Referenced-quantity decibels: dimensionally plain decibels; the reference
+    # (isotropic antenna, dipole, carrier, per-kelvin) is bookkeeping the model
+    # keeps in the unit text.
+    "dBi = decibel",
+    "dBd = decibel",
+    "dBc = decibel",
+    "dBK = decibel",
+)
+
+
+@lru_cache(maxsize=1)
+def registry() -> Any:
+    """Return the shared pint unit registry (created on first use)."""
+    reg: Any = pint.UnitRegistry()
+    for definition in _EXTRA_DEFINITIONS:
+        reg.define(definition)
+    return reg
+
+
+def parse_unit(text: str) -> Any:
+    """Parse unit text into a pint unit; raises ValueError on unknown units."""
+    try:
+        return registry().Unit(text)
+    except Exception as exc:
+        raise ValueError(f"unparseable unit {text!r}: {exc}") from exc
+
+
+def is_valid_unit(text: str) -> bool:
+    """Return whether pint can parse this unit text."""
+    try:
+        parse_unit(text)
+    except ValueError:
+        return False
+    return True
+
+
+def convert(value: float, from_unit: str, to_unit: str) -> float:
+    """Convert a value between two unit texts."""
+    quantity = registry().Quantity(value, parse_unit(from_unit))
+    return float(quantity.to(parse_unit(to_unit)).magnitude)
+
+
+def check_dimensionality(unit_a: str, unit_b: str) -> bool:
+    """Return whether two unit texts share a dimensionality."""
+    return bool(parse_unit(unit_a).dimensionality == parse_unit(unit_b).dimensionality)