mdxml 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,103 @@
1
+ """The FMI 3.0 Model Structure: outputs, state derivatives, clocked states, initial unknowns and event indicators.
2
+
3
+ Every entry refers to a Model Variable by value reference, exactly as
4
+ written; nothing is resolved (ADR 0002).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Mapping
10
+ from dataclasses import dataclass
11
+ from enum import Enum
12
+ from types import MappingProxyType
13
+
14
+ from mdxml import _convert as c
15
+ from mdxml._grammar import SKIP, Grammar
16
+ from mdxml._schema import EMPTY, Attr, Frame, attributes, table
17
+
18
+
19
+ class DependenciesKind(str, Enum):
20
+ """How an unknown depends on one of its ``dependencies``."""
21
+
22
+ DEPENDENT = "dependent"
23
+ CONSTANT = "constant"
24
+ FIXED = "fixed"
25
+ TUNABLE = "tunable"
26
+ DISCRETE = "discrete"
27
+
28
+
29
+ @dataclass(frozen=True, slots=True, kw_only=True)
30
+ class Unknown:
31
+ """One entry of the Model Structure.
32
+
33
+ ``dependencies`` is ``None`` when the attribute is absent, which the
34
+ standard defines as "may depend on all knowns", and ``()`` when it's
35
+ present but empty ("depends on none").
36
+ """
37
+
38
+ value_reference: int
39
+ """Value reference of the unknown."""
40
+ dependencies: tuple[int, ...] | None = None
41
+ """Value references of the knowns it depends on."""
42
+ dependencies_kind: tuple[DependenciesKind | str, ...] | None = None
43
+
44
+
45
+ @dataclass(frozen=True, slots=True, kw_only=True)
46
+ class ModelStructure:
47
+ """The ``ModelStructure`` element."""
48
+
49
+ outputs: tuple[Unknown, ...] = ()
50
+ continuous_state_derivatives: tuple[Unknown, ...] = ()
51
+ clocked_states: tuple[Unknown, ...] = ()
52
+ initial_unknowns: tuple[Unknown, ...] = ()
53
+ event_indicators: tuple[Unknown, ...] = ()
54
+
55
+
56
+ UNKNOWN_ATTRS = table(
57
+ Attr("valueReference", "value_reference", c.UNSIGNED_INT, required=True),
58
+ Attr("dependencies", "dependencies", c.ListOf(c.UNSIGNED_INT)),
59
+ Attr("dependenciesKind", "dependencies_kind", c.ListOf(c.EnumConverter(DependenciesKind))),
60
+ )
61
+
62
+ _ELEMENTS: Mapping[str, str] = MappingProxyType(
63
+ {
64
+ "Output": "outputs",
65
+ "ContinuousStateDerivative": "continuous_state_derivatives",
66
+ "ClockedState": "clocked_states",
67
+ "InitialUnknown": "initial_unknowns",
68
+ "EventIndicator": "event_indicators",
69
+ }
70
+ )
71
+
72
+
73
+ def build_unknown(frame: Frame, *, strict: bool) -> Unknown:
74
+ """Build an entry; in strict mode its two lists must have the same length."""
75
+ unknown = Unknown(**attributes(frame, UNKNOWN_ATTRS, strict=strict))
76
+ if strict and unknown.dependencies_kind is not None:
77
+ count = len(unknown.dependencies or ())
78
+ if unknown.dependencies is None or len(unknown.dependencies_kind) != count:
79
+ raise frame.error(
80
+ f"<{frame.tag} valueReference={unknown.value_reference}> has {len(unknown.dependencies_kind)} "
81
+ f"dependenciesKind entries for {count} dependencies"
82
+ )
83
+ return unknown
84
+
85
+
86
+ def build_model_structure(frame: Frame, *, strict: bool) -> ModelStructure:
87
+ """Build the ``ModelStructure`` from its entries, grouped by element in document order."""
88
+ attributes(frame, EMPTY, strict=strict)
89
+ return ModelStructure(**{field: tuple(frame.all(tag)) for tag, field in _ELEMENTS.items()})
90
+
91
+
92
+ STRUCTURE_GRAMMAR = Grammar(
93
+ root="ModelStructure",
94
+ stop_at="",
95
+ build_root=build_model_structure,
96
+ children={
97
+ "ModelStructure": dict.fromkeys(_ELEMENTS, build_unknown),
98
+ **{tag: {"Annotations": SKIP} for tag in _ELEMENTS},
99
+ },
100
+ )
101
+
102
+ AFTER_MODEL_STRUCTURE = frozenset({"Annotations"})
103
+ """Root elements allowed after ``ModelStructure``; skipped."""