`tg_model.model`¶

Public modeling API: elements, definition context, refs, and expression helpers.

Everything here is definition-time (define(cls, model)): symbolic refs, declarations recorded on ModelDefinitionContext, and helpers such as sum_attributes() for unitflow-safe roll-ups.

See also

tg_model.execution: Configure (instantiate) and evaluate compiled models.

class tg_model.model.AttributeRef(owner_type, path, kind, target_type=None, metadata=None)[source]¶

Bases: Ref

Reference to a declared attribute or parameter (value slot at configure time).

For attribute() expr=, passing another slot’s ref compiles as an identity passthrough. Use sym when you need that slot inside unitflow Expr arithmetic (for example other.sym + …).

Parameters:

owner_type (type)
path (tuple[str, ...])
kind (str)
target_type (type | None)
metadata (dict[str, Any] | None)

property sym: Any¶

Canonical unitflow symbol for this reference (cached per ref identity).

Returns:: Unitflow symbol with unit from declaration metadata.
Return type:: Symbol
Raises:: ValueError – If metadata has no unit (symbols cannot be constructed).

to(target_unit)[source]¶

Parameters:: target_unit (Any)
Return type:: Any

kind¶

metadata¶

owner_type¶

path¶

target_type¶

class tg_model.model.Element[source]¶

Bases: object

Abstract base for all model element types.

Subclasses implement define() to record structure; compilation produces a cached dict artifact consumed by instantiation and graph compilation.

Notes

compile() is idempotent per class. Use _reset_compilation() only in tests.

classmethod define(model)[source]¶

Declare this type’s structure (override in subclasses).

Parameters:: model (ModelDefinitionContext) – Definition-time recorder passed by the compiler.
Return type:: None

classmethod compile()[source]¶

Compile this type’s definition (cached on the class).

Returns:: Compiled artifact (nodes, edges, registries) used by instantiate().
Return type:: dict

class tg_model.model.ModelDefinitionContext(owner_type, *, symbol_owner=None, symbol_path_prefix=())[source]¶

Bases: object

Records declarations during define(cls, model) (the model argument).

Framework-controlled: only recording is allowed until freeze(). All declaration names share one namespace per owner type; duplicates raise ModelDefinitionError.

For Requirement, symbol_owner and symbol_path_prefix thread the configured root type and path prefix so requirement_input() builds AttributeRef paths the graph compiler resolves after allocate() inputs= bindings.

Parameters:

owner_type (type)
symbol_owner (type | None)
symbol_path_prefix (tuple[str, ...])

owner_type¶

The Element subclass whose define() is running.

Type:: type

symbol_owner¶

Root type used as AttributeRef.owner_type for threaded requirement inputs.

Type:: type

symbol_path_prefix¶

Prefix of requirement-block names under the root (internal threading).

Type:: tuple[str, …]

nodes¶

Declarations keyed by local name.

Type:: dict[str, NodeDecl]

edges¶

Structural and semantic edges (connect, allocate, references, …).

Type:: list[dict]

behavior_transitions¶

Recorded state-machine transitions (Phase 6).

Type:: list[dict]

part() → PartRef[source]¶

part(name: str, part_type: type) → PartRef

Declare a child part, or return a ref to this block as the configured root.

No arguments — does not register a child. Returns a PartRef to this block: the parent you are defining in define(). All other model.part(name, Type) calls in the same define() become children of that parent at instantiate() time (same root PartInstance owns them). Two arguments — register a composed child part and return its ref.

Parameters:

name (str, optional) – Child part declaration name (required with part_type).
part_type (type, optional) – Subclass of Part / System.

Returns:

Root ref (empty path) or child ref.

Return type:

PartRef

Raises:

ModelDefinitionError – On wrong arity (only one of name / part_type), duplicate name, or frozen context.

Examples

Typical root + child pattern:

rocket = model.part()
tank = model.part("tank", TankType)
model.allocate(req, rocket)

root_block()[source]¶

Return a ref to this type as the configured structural root (empty path).

Returns:: path=() and target_type=self.owner_type.
Return type:: PartRef

Notes

Same as part() with no arguments. Prefer part() when mixing root and child declarations in one call style.

See also

part, owner_part

owner_part()[source]¶

Alias of root_block() (historical name).

Returns:: Same as root_block().
Return type:: PartRef

port(name, direction, **metadata)[source]¶

Declare a structural port on this part or system.

Parameters:

name (str) – Local port name (unique in this type’s node namespace).
direction (str) – Flow direction label (e.g. in, out, inout — project convention).
**metadata – Additional port metadata stored on the compiled node.

Returns:

Reference for use in connect().

Return type:

PortRef

Raises:

ModelDefinitionError – On duplicate name or if the context is frozen.

attribute(name, *, expr=None, computed_by=None, **metadata)[source]¶

Declare an attribute (bindable/computed value slot).

Root System types may not declare attributes. Keep System.define() focused on composition and top-level parameters; move derived values into an owned Part or requirement package.

Parameters:

name (str) – Local attribute name.
expr (Any | None) – Optional unitflow expression or RollupDecl for derived values.
computed_by (Any | None) – Optional ExternalComputeBinding for external computation.
**metadata (Any) – Must include unit= (and any other declaration metadata) for symbol construction.

Returns:

Reference for constraints, expressions, and graph compilation.

Return type:

AttributeRef

Raises:

ModelDefinitionError – On duplicate name, frozen context, or when called from System.define().

Notes

Chaining a + b + c is left-associative; use a + (b + c), .sym, or sum_attributes() to avoid mixed Expr / AttributeRef errors.

parameter(name, **metadata)[source]¶

Declare an externally bindable parameter (input slot at evaluation time).

Parameters:

name (str) – Local parameter name.
**metadata – Typically includes unit= for quantity inputs.

Returns:

kind='parameter' reference.

Return type:

AttributeRef

Raises:

ModelDefinitionError – On duplicate name, frozen context, or when called from System.define().

parameter_ref(root_block_type, name)[source]¶

Call parameter_ref() (same resolution rules and errors).

Parameters:

root_block_type (type)
name (str)

Return type:

AttributeRef

attribute_ref(root_block_type, name)[source]¶

Call attribute_ref() (same resolution rules and errors).

Parameters:

root_block_type (type)
name (str)

Return type:

AttributeRef

requirement_ref(root_block_type, path)[source]¶

Call requirement_ref() (same resolution rules and errors).

Parameters:

root_block_type (type)
path (tuple[str, ...])

Return type:

Ref

citation(name, **metadata)[source]¶

Declare an external provenance node (standards, reports, URIs, clauses).

Parameters:

name (str) – Citation node name.
**metadata – Free-form citation fields (URI, clause id, revision, …).

Returns:

kind='citation' for references() edges.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

Notes

v0 does not execute citations in the evaluator; they support export and traceability hooks.

requirement(name, text, *, expr=None, **metadata)[source]¶

Declare a requirement (human text plus optional executable acceptance).

Parameters:

name (str) – Requirement node name.
text (str) – Human-readable statement (not evaluated).
expr (Any | None) – Optional boolean acceptance expression (same family as constraint()).
**metadata (Any) – Additional requirement metadata.

Returns:

kind='requirement'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

Notes

With expr=, symbols must resolve against the allocate() target subtree at compile time, and an allocate edge must exist. Prefer requirement_input() and requirement_accept_expr() inside Requirement when acceptance should use only requirement-local inputs bound via allocate(..., inputs=).

requirement_input(requirement, name, **metadata)[source]¶

Advanced / rare — leaf reqcheck input slot on requirement.

Warning

For new requirement packages, use ``model.parameter`` at package scope instead. requirement_input is a low-level helper for INCOSE-style leaf acceptance rows wired via allocate(..., inputs=...). See the Requirement class docstring.

Registers a value-bearing symbol under the configured root (threaded symbol_owner / symbol_path_prefix). Bind each input with allocate() inputs={name: part_ref.…}.

Parameters:

requirement (Ref) – kind='requirement' ref declared in this block.
name (str) – Input slot name (referenced in acceptance expressions).
**metadata – Forwarded to the internal parameter declaration (e.g. unit=).

Returns:

Symbol for use in requirement_accept_expr() (kind='parameter' on symbol_owner).

Return type:

AttributeRef

Raises:

ModelDefinitionError – If not inside a requirement block, requirement is wrong, inputs conflict with requirement(..., expr=), or names duplicate.

requirement_attribute(requirement, name, *, expr, **metadata)[source]¶

Advanced / rare — derived value on a leaf requirement.

Warning

For new requirement packages, use ``model.attribute`` at package scope instead. requirement_attribute is a low-level helper for INCOSE-style leaf acceptance rows. See the Requirement class docstring.

Registers a requirement-local attribute whose value is computed from an expression (typically over requirement_input() symbols, other requirement_attribute symbols declared earlier in the same define(), and root parameters). Use unit= in metadata so AttributeRef.sym can be built.

Unlike requirement_input(), attributes are not wired via allocate() inputs=; they are evaluated from their expr= and materialized as value slots on the configured root for graph compilation.

Parameters:

requirement (Ref) – kind='requirement' ref declared in this block.
name (str) – Attribute name (must not collide with a requirement_input name on the same requirement).
expr (Any) – Scalar expression (same family as attribute() expr=).
**metadata (Any) – Must include unit= (and any other declaration metadata).

Returns:

kind='attribute' symbol for use in requirement_accept_expr() or in later requirement_attribute calls.

Return type:

AttributeRef

Raises:

ModelDefinitionError – If not in a block, requirement is wrong, names collide, expr is missing, or acceptance was already set via requirement_accept_expr.

requirement_accept_expr(requirement, *, expr)[source]¶

Advanced / rare — set executable acceptance for a leaf requirement.

Warning

For new requirement packages, use ``model.constraint`` at package scope instead. requirement_accept_expr is a low-level helper for INCOSE-style leaf acceptance rows. See the Requirement class docstring.

Parameters:

requirement (Ref) – Requirement ref from this block (single-segment path only).
expr (Any) – Boolean expression over requirement input symbols (and unitflow quantities).

Raises:

ModelDefinitionError – If not in a block, ref is invalid, path is not a single segment, or acceptance was already set via requirement(..., expr=) or a prior call.

Return type:

None

requirement_package(name, package_type)[source]¶

Declare a nested composable requirements package (Requirement).

Parameters:

name (str) – Package name in this owner’s namespace.
package_type (type) – Subclass of Requirement.

Returns:

Dot-access ref to nested requirements.

Return type:

RequirementRef

Raises:

ModelDefinitionError – If package_type is not a composable requirement, on duplicate name, or frozen context.

Notes

Compiles package_type eagerly so requirement_ref() and sibling dot access work within the same define() call. The internal node kind remains requirement_block for artifact compatibility.

Inside package_type.define(), package-level parameter(), attribute(), and constraint() are allowed when Requirement compile policy permits them.

constraint(name, *, expr, **metadata)[source]¶

Declare a constraint (boolean check over realized slot values).

Root System types may not declare constraints. Put executable checks on the owning Part or requirement package so the top-level system stays structural.

Parameters:

name (str) – Constraint name (appears in ConstraintResult).
expr (Any) – Boolean expression over AttributeRef / unitflow symbols.
**metadata (Any) – Extra metadata attached to the compiled node.

Returns:

kind='constraint'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name, frozen context, or when called from System.define().

state(name, *, initial=False, **metadata)[source]¶

Declare a discrete behavioral state (state machine vertex).

Parameters:

name (str) – State name (used in transition() and runtime state string).
initial (bool, default False) – Mark the initial state for this part type (exactly one should be initial).
**metadata – Optional extra state metadata.

Returns:

kind='state'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

event(name, **metadata)[source]¶

Declare a discrete behavioral event (state machine stimulus).

Parameters:

name (str) – Event name string used with dispatch_event().
**metadata – Optional event metadata.

Returns:

kind='event'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

action(name, *, effect=None, **metadata)[source]¶

Declare a named action (callable side effect on a part instance).

Parameters:

name (str) – Action name referenced by transitions, sequences, decisions, etc.
effect (callable, optional) – (RunContext, PartInstance) -> None executed under behavior subtree scope.
**metadata – Stored on the compiled action node if effect is omitted (legacy inline hook).

Returns:

kind='action'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

guard(name, *, predicate, **metadata)[source]¶

Declare a reusable guard for decisions and transitions.

Parameters:

name (str) – Guard name.
predicate (Any) – (RunContext, PartInstance) -> bool evaluated under behavior subtree scope.
**metadata (Any) – Optional metadata.

Returns:

kind='guard'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

merge(name, *, then_action=None, **metadata)[source]¶

Declare a merge node (shared continuation after branching).

Parameters:

name (str) – Merge node name.
then_action (str, optional) – Action name to run when dispatch_merge() fires.
**metadata – Optional metadata.

Returns:

kind='merge'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

Notes

When decision() uses merge_point= to this merge, dispatch_decision() runs the continuation automatically; do not also call dispatch_merge() for that path.

item_kind(name, **metadata)[source]¶

Declare an item kind label for inter-part flows (emit_item()).

Parameters:

name (str) – Kind / event name carried across connections.
**metadata – Optional metadata.

Returns:

kind='item_kind'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

decision(name, *, branches, default_action=None, merge_point=None, **metadata)[source]¶

Declare an exclusive decision (first matching guard wins).

Parameters:

name (str) – Decision node name.
branches (list[tuple[Ref | None, str]]) – Each entry is (guard_ref or None, action_name). None guard is unconditional.
default_action (str, optional) – Action name when no branch matches.
merge_point (Ref, optional) – kind='merge' ref for automatic continuation (see merge()).
**metadata – Extra metadata.

Returns:

kind='decision'.

Return type:

Ref

Raises:

ModelDefinitionError – On malformed branches, wrong ref kinds/owners, unknown merge, duplicate name, or frozen context.

Notes

Runtime API: dispatch_decision().

fork_join(name, *, branches, then_action=None, **metadata)[source]¶

Declare a fork/join activity region (serial branch execution in v0).

Parameters:

name (str) – Block name.
branches (list[list[str]]) – Each inner list is one branch: action names run in order within the branch.
then_action (str, optional) – Action name after all branches complete.
**metadata – Extra metadata.

Returns:

kind='fork_join'.

Return type:

Ref

Raises:

ModelDefinitionError – On empty/malformed branches, duplicate name, or frozen context.

Notes

v0 runs branches serially in list order; see dispatch_fork_join().

sequence(name, *, steps, **metadata)[source]¶

Declare a linear sequence of action names (in-order execution).

Parameters:

name (str) – Sequence node name.
steps (list[str]) – Non-empty list of declared action names.
**metadata – Extra metadata.

Returns:

kind='sequence'.

Return type:

Ref

Raises:

ModelDefinitionError – On empty/non-string steps, duplicate name, or frozen context.

See also

tg_model.execution.behavior.dispatch_sequence

transition(from_state, to_state, on, *, when=None, guard=None, effect=None)[source]¶

Record one state-machine transition for this part type.

Parameters:

from_state (Ref) – kind='state' refs on this type.
to_state (Ref) – kind='state' refs on this type.
on (Ref) – kind='event' ref.
when (callable, optional) – (RunContext, PartInstance) -> bool inline guard (mutually exclusive with guard=).
guard (Ref, optional) – kind='guard' ref (mutually exclusive with when=).
effect (str, optional) – Declared action name run after the state advances.

Raises:

ModelDefinitionError – If both when and guard are set, refs have wrong kinds/owners, or context is frozen.

Return type:

None

Notes

Determinism: at most one transition per (from_state, event) (checked at compile time).

scenario(name, *, expected_event_order, initial_behavior_state=None, expected_final_behavior_state=None, expected_interaction_order=None, expected_item_kind_order=None, **metadata)[source]¶

Declare a behavioral scenario contract (partial trace checks).

Parameters:

name (str) – Scenario node name.
expected_event_order (list[Ref]) – Event refs in expected firing order for the scenario owner type.
initial_behavior_state (str, optional) – Expected from_state of the first transition on part_path under validation.
expected_final_behavior_state (str, optional) – Expected discrete state after the trace (needs ctx in validation).
expected_interaction_order (list[tuple[str, str]], optional) – (relative_part_path, event_name) pairs from this type’s root for global ordering checks.
expected_item_kind_order (list[str], optional) – Expected ItemFlowStep item_kind sequence.
**metadata – Extra scenario metadata.

Returns:

kind='scenario'.

Return type:

Ref

Raises:

ModelDefinitionError – If event refs are wrong, duplicate name, or frozen context.

See also

tg_model.execution.behavior.validate_scenario_trace

solve_group(name, *, equations, unknowns, givens, **metadata)[source]¶

Declare a coupled equation solve group (requires SciPy at evaluation).

Parameters:

name (str) – Solve group name.
equations (list) – Scalar expressions (same count as unknowns) compiled to residuals.
unknowns (list[AttributeRef]) – Attributes to solve for.
givens (list[AttributeRef]) – Bound inputs to the solver.
**metadata – Extra metadata.

Returns:

kind='solve_group'.

Return type:

Ref

Raises:

ModelDefinitionError – On duplicate name or frozen context.

Notes

Execution uses scipy.optimize; see tg_model.execution.solve_groups.

references(source, citation)[source]¶

Record a provenance edge from source to citation.

Parameters:

source (Ref) – Any declared node on this type (part, port, parameter, requirement, …).
citation (Ref) – Must be kind='citation' on this type.

Raises:

ModelDefinitionError – If kinds/ownership are invalid or context is frozen.

Return type:

None

allocate(requirement_ref, target_ref, *, inputs=None)[source]¶

Declare an allocation from a requirement to a model element.

Optional inputs maps requirement_input() names to part parameter/attribute refs. Required when acceptance uses only requirement-local symbols.

Parameters:

requirement_ref (Ref) – kind='requirement' ref being allocated.
target_ref (Ref) – Part or root ref that supplies values for acceptance (per compiler rules).
inputs (dict[str, AttributeRef], optional) – Maps input name → AttributeRef on the allocated subtree.

Raises:

ModelDefinitionError – If context is frozen or inputs values are not AttributeRef.

Return type:

None

allocate_to_system(requirement_ref)[source]¶

Preferred shorthand for allocate(requirement_ref, root_block()).

Parameters:: requirement_ref (Ref) – Requirement to allocate to this type’s structural system/root block.
Raises:: ModelDefinitionError – Same as allocate().
Return type:: None

allocate_to_root(requirement_ref)[source]¶

Compatibility alias for allocate_to_system().

Parameters:: requirement_ref (Ref) – Requirement to allocate to this type’s structural root.
Raises:: ModelDefinitionError – Same as allocate().
Return type:: None

connect(source, target, carrying=None)[source]¶

Declare a structural connection between two ports.

Parameters:

source (PortRef) – Port refs declared on (possibly different) composed types under one configured root.
target (PortRef) – Port refs declared on (possibly different) composed types under one configured root.
carrying (str, optional) – When set, emit_item() only uses this binding if item_kind matches.

Raises:

ModelDefinitionError – If either endpoint is not a PortRef, or context is frozen.

Return type:

None

parts()[source]¶

Return the internal selector token for “all child parts” in roll-up expressions.

Returns:: The sentinel "ALL_PARTS" understood by roll-up compilation.
Return type:: str

See also

tg_model.model.declarations.values.RollupBuilder.sum

link_external_routes(binding, routes)[source]¶

Wire output_routes on an ExternalComputeBinding.

Call after declaring attributes so AttributeRef targets exist.

Parameters:

binding (ExternalComputeBinding) – Binding created for this type.
routes (dict[str, AttributeRef]) – External output name → attribute slot ref.

Raises:

ModelDefinitionError – If binding is not an ExternalComputeBinding.

Return type:

None

freeze()[source]¶

Freeze the context so no further declarations or edges are allowed.

Notes

Invoked by compile_type() after define returns.

Return type:: None

class tg_model.model.Part[source]¶

Bases: Element

Structural part in a hierarchy (may own child parts, ports, values, behavior).

class tg_model.model.PartRef(owner_type, path, kind, target_type=None, metadata=None)[source]¶

Bases: Ref

Reference to a declared part; dot access chains into the child compiled type.

Raises:

AttributeError – If target_type is missing, the type is not compiled, or the member does not exist.

Parameters:

owner_type (type)
path (tuple[str, ...])
kind (str)
target_type (type | None)
metadata (dict[str, Any] | None)

kind¶

metadata¶

owner_type¶

path¶

target_type¶

class tg_model.model.PortRef(owner_type, path, kind, target_type=None, metadata=None)[source]¶

Bases: Ref

Reference to a declared port.

Use with tg_model.model.definition_context.ModelDefinitionContext.connect().

Parameters:

owner_type (type)
path (tuple[str, ...])
kind (str)
target_type (type | None)
metadata (dict[str, Any] | None)

kind¶

metadata¶

owner_type¶

path¶

target_type¶

class tg_model.model.Ref(owner_type, path, kind, target_type=None, metadata=None)[source]¶

Bases: object

Symbolic reference to one declared model element.

Parameters:

owner_type (type) – Type whose compiled artifact owns this path (often the configured root).
path (tuple[str, ...]) – Declaration names from that owner (() for the root part ref).
kind (str) – Node kind (requirement, constraint, event, …).
target_type (type, optional) – Composed type for part / requirement_block refs.
metadata (dict, optional) – Declaration metadata copied from compile records.

owner_type¶

path¶

kind¶

target_type¶

metadata¶

property local_name: str¶: Dotted path string for this ref (a.b.c).

to_dict()[source]¶

Serialize ref to a JSON-friendly dict (owner name, path, kind, optional target).

Returns:: Keys: owner, path, kind; optional target_type, metadata.
Return type:: dict

class tg_model.model.Requirement[source]¶

Bases: Element

Composable requirements package — use ``parameter`` / ``attribute`` / ``constraint``.

DEFAULT PATTERN (always start here): Inside define(cls, model), declare model.parameter, model.attribute, and model.constraint at package scope — the same value/check authoring surface as Part (unlike System, which is restricted to structural composition and top-level parameters). Use model.requirement(id, text) for leaf traceability statements, model.citation for provenance, model.references for edges, and model.allocate for structural allocation. This is the standard, recommended API for all new requirement packages.

Advanced (rare — leaf reqcheck only): requirement_input, requirement_attribute, and requirement_accept_expr are low-level helpers for INCOSE-style executable acceptance on a single leaf model.requirement(...), wired through allocate(..., inputs=...). Use them only when you need summarize_requirement_satisfaction per-requirement rows. Do not use them as the default pattern. If your check can be a package-level constraint, use that instead.

Notes

Package-level parameter, attribute, and constraint nodes become ValueSlot / graph nodes under the configured root (dot access e.g. configured_root.pkg.param_name); expressions are validated during compile(). Package-level slots do not yet support computed_by= or RollupDecl in graph compilation; every package constraint must supply expr= (including constant expressions with no symbols).

class tg_model.model.RequirementRef(owner_type, path, kind, target_type=None, metadata=None)[source]¶

Bases: Ref

Reference to a declared composable requirement package (dot access like PartRef).

Raises:

AttributeError – If the package type is not compiled yet, the member is missing, or the kind cannot be projected (only requirement subtree kinds are allowed).

Parameters:

owner_type (type)
path (tuple[str, ...])
kind (str)
target_type (type | None)
metadata (dict[str, Any] | None)

kind¶

metadata¶

owner_type¶

path¶

target_type¶

class tg_model.model.System[source]¶

Bases: Element

Top-level system element for composition and top-level input parameters.

System.define() is intentionally structural: compose child parts, declare ports/requirements/citations as needed, and keep mission or scenario inputs as top-level parameter(...) declarations. Derived values and executable checks belong on owned Part instances or requirement packages, not on the root System itself.

classmethod instantiate()[source]¶

Build a ConfiguredModel for this root type.

Delegates to instantiate() — same behavior and no extra compilation path.

Returns:: Frozen topology for graph compile and evaluation. A new instance on every call; there is no shared singleton configured model.
Return type:: ConfiguredModel

Notes

Call this on a concrete System subclass that implements Element.define() for your program root. That is the same requirement as passing that class to instantiate().

The base System type itself is not a valid configured root; System.instantiate() fails the same way as instantiate(System).

Configured roots that are Part subclasses still use instantiate() only (no class method on Part).

See also

tg_model.execution.configured_model.instantiate

tg_model.model.as_expr_leaf(x)[source]¶

Promote AttributeRef to unitflow expr leaf.

Parameters:: x (Any) – Attribute ref or already-expression value.
Returns:: x.sym for refs; otherwise x.
Return type:: Any

Notes

Use when hand-building sums so expr + AttributeRef never hits unitflow’s _promote.

tg_model.model.attribute_ref(root_block_type, name)[source]¶

Return a reference to an attribute on the configured (or compiling) root type.

Same resolution order as parameter_ref(), but the named node must be kind='attribute'. Use when a nested Requirement (or part) should derive package slots from an allowed root-block attribute, such as a configured root Part. Root System types may not declare attribute(...); move those derived values into an owned part or requirement package instead.

Parameters:

root_block_type (type)
name (str)

Return type:

AttributeRef

tg_model.model.parameter_ref(root_block_type, name)[source]¶

Return a reference to a parameter on the configured (or compiling) root type.

Use inside nested define() to point at mission / scenario parameters on the root without globals—e.g. for ExternalComputeBinding inputs or constraint expressions.

Parameters:

root_block_type (type) – The root System / Part subclass that owns the parameter declaration.
name (str) – Parameter declaration name on root_block_type.

Returns:

Symbolic ref (kind='parameter') for graph compilation and expressions.

Return type:

AttributeRef

Raises:

ModelDefinitionError – If the node is missing, is not a parameter, or root_block_type is neither compiling nor compiled.

Notes

Resolution order:

If root_block_type is fully compiled, read from the cached artifact.
If mid-compile, read from the active definition context; declare parameters on the root before child model.part(...) types that call this function.

tg_model.model.requirement_ref(root_block_type, path)[source]¶

Return a Ref to a requirement under the root type.

path is declaration names from the root (e.g. ("mission", "range") for requirement range inside package mission). Use from nested Part.define() when dot notation from a PartRef is not available.

Parameters:

root_block_type (type) – Configured root type owning the requirement subtree.
path (tuple[str, ...]) – Non-empty path of segments: intermediate steps are composable requirement packages (internal compiled kind requirement_block); the last segment is a leaf requirement.

Returns:

kind='requirement' ref with metadata from the compiled declaration.

Return type:

Ref

Raises:

ModelDefinitionError – If path is empty, a segment is missing, kinds along the path are wrong, or the root is neither compiling nor compiled.

Notes

Resolution matches parameter_ref(): prefer the compiled root artifact; while compiling, the first segment comes from the active context and nested segments from compiled composable-requirement artifacts (eager compile when registering via ModelDefinitionContext.requirement_package()).

tg_model.model.sum_attributes(*terms)[source]¶

Sum two or more attribute refs and/or expressions (associative-safe).

Avoids the Python a + b + c left-association trap with mixed AttributeRef and Expr.

Parameters:: *terms (Any) – Two or more refs and/or unitflow expressions.
Returns:: Left-folded unitflow expression after as_expr_leaf() on each term.
Return type:: Any
Raises:: ValueError – If fewer than two terms are passed.

Examples

model.attribute("total_kg", unit=kg, expr=sum_attributes(a, b, c))

tg_model.model¶

`tg_model.model`¶