Classes
class	SpecError
class	_ModelScoped
class	ParamSpec
class	OptionSpec
class	PortSpec
class	StateSpec
class	ComponentSpec

Functions
str\|None	_bounds_problem (ParamSpec spec, Param param, str type_name)
list[str]	_duplicates (list[str] names)
ComponentSpec	register_component_spec (ComponentSpec spec)
ComponentSpec	get_component_spec (str type_name)
list[str]	registered_component_types ()
None	_ensure_loaded ()
list[ComponentSpec]	load_component_specs (Path path)
ComponentSpec	_spec_from_toml (str type_name, dict[str, Any] body)
dict[str, Any]	_table (str type_name, str block, str name, Any value)
Any	_require (str type_name, str block, str name, Any value, str key)
Param\|None	_maybe_param (Any value, str where)
float\|None	_maybe_float (Any value)
Param	default_param (float value, str unit, str reference)

Variables
dict	_SPECS = {}
	_SPECS_FILE = Path(__file__).with_name("components.toml")
bool	_LOADED = False

Detailed Description

What a component *is*, declared as data.

A :class:`ComponentSpec` says what a kind of hardware has: which parameters,
which ports, which internal states, and which fidelity models it can be
evaluated at. It is the single description that three very different things
read:

* **validation** -- is this configuration complete, dimensionally sound, and
  within bounds, before a solver touches it;
* **the property inspector** (Phase 10) -- the panel that appears when someone
  clicks a valve is generated from this, so a new component type arrives with a
  working editor and nobody writes a form;
* **documentation** -- the parameter table for a component is generated, so it
  cannot drift from what the code actually accepts.

Writing those three by hand is how "nothing hardcoded" quietly dies: the physics
grows a parameter, the UI does not, and the only way to set it becomes editing
YAML by hand.

Fidelity models
---------------
One component, several depths. A regulator can be an ideal setpoint, a
tabulated droop curve, a dome force balance, or pure measured data -- the same
hardware at four levels of detail, chosen per instance. Parameters that only one
model needs declare that in :attr:`ParamSpec.models`, so an ``ideal`` regulator
is not asked for a poppet mass it will never use.

Function Documentation

◆ _bounds_problem()

str \| None feedtwin.model.spec._bounds_problem	(	ParamSpec	spec,
		Param	param,
		str	type_name )

protected

Definition at line 419 of file spec.py.

Referenced by feedtwin.model.spec.ComponentSpec.validate().

◆ _duplicates()

list[str] feedtwin.model.spec._duplicates ( list[str] names )

protected

Definition at line 435 of file spec.py.

Referenced by feedtwin.model.spec.ComponentSpec.__post_init__().

◆ _ensure_loaded()

None feedtwin.model.spec._ensure_loaded ( )

protected

Read the shipped component declarations, once.

An explicit flag rather than "is the registry empty", for the reason
:mod:`feedtwin.props.species` learned the hard way: a program whose first
call registers a component would make the registry non-empty, and every
shipped declaration would then be silently missing for the rest of the run.

Definition at line 478 of file spec.py.

References load_component_specs().

Referenced by get_component_spec(), and registered_component_types().

◆ _maybe_float()

float | None feedtwin.model.spec._maybe_float ( Any value )

protected

Definition at line 610 of file spec.py.

Referenced by _spec_from_toml().

◆ _maybe_param()

Param \| None feedtwin.model.spec._maybe_param	(	Any	value,
		str	where )

protected

Definition at line 606 of file spec.py.

Referenced by _spec_from_toml().

◆ _require()

Any feedtwin.model.spec._require	(	str	type_name,
		str	block,
		str	name,
		Any	value,
		str	key )

protected

Definition at line 599 of file spec.py.

References _table().

Referenced by _spec_from_toml().

◆ _spec_from_toml()

ComponentSpec feedtwin.model.spec._spec_from_toml	(	str	type_name,
		dict[str, Any]	body )

protected

Definition at line 518 of file spec.py.

References _maybe_float(), _maybe_param(), _require(), and _table().

Referenced by load_component_specs().

◆ _table()

dict[str, Any] feedtwin.model.spec._table	(	str	type_name,
		str	block,
		str	name,
		Any	value )

protected

Definition at line 593 of file spec.py.

Referenced by _require(), and _spec_from_toml().

◆ default_param()

Param feedtwin.model.spec.default_param	(	float	value,
		str	unit,
		str	reference )

A library-supplied default, tagged as such.

A shorthand worth having: every default in a component declaration should
carry :attr:`Provenance.DEFAULT` and say where the number came from, and
making that a one-liner is what stops it being skipped.

Definition at line 614 of file spec.py.

◆ get_component_spec()

ComponentSpec feedtwin.model.spec.get_component_spec ( str type_name )

Definition at line 457 of file spec.py.

References _ensure_loaded().

◆ load_component_specs()

list[ComponentSpec] feedtwin.model.spec.load_component_specs ( Path path )

Load component declarations from a TOML file and register them.

A component's *schema* is data -- what parameters it takes, what they mean,
what units they are in, what its ports are. Only its *physics* is code. So
adding a component type is a data edit, and Phase 03 supplies behaviour
keyed by type name rather than a parallel set of declarations that can drift
from it.

Public, so a project can declare its own components without editing this
package; later definitions replace earlier ones by type name.

Definition at line 493 of file spec.py.

References _spec_from_toml(), and register_component_spec().

Referenced by _ensure_loaded().

◆ register_component_spec()

ComponentSpec feedtwin.model.spec.register_component_spec ( ComponentSpec spec )

Register a component type. Re-registering a name replaces it.

Phase 03 is expected to re-register the shipped declarations as it
implements their physics and learns which parameters each model really
needs; replacing by name is how that happens without a migration.

Definition at line 446 of file spec.py.

Referenced by load_component_specs().

◆ registered_component_types()

list[str] feedtwin.model.spec.registered_component_types ( )

Definition at line 469 of file spec.py.

References _ensure_loaded().

Variable Documentation

◆ _LOADED

bool feedtwin.model.spec._LOADED = False

protected

Definition at line 475 of file spec.py.

◆ _SPECS

dict feedtwin.model.spec._SPECS = {}

protected

Definition at line 443 of file spec.py.

◆ _SPECS_FILE

feedtwin.model.spec._SPECS_FILE = Path(__file__).with_name("components.toml")

protected

Definition at line 474 of file spec.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _bounds_problem()

◆ _duplicates()

◆ _ensure_loaded()

◆ _maybe_float()

◆ _maybe_param()

◆ _require()

◆ _spec_from_toml()

◆ _table()

◆ default_param()

◆ get_component_spec()

◆ load_component_specs()

◆ register_component_spec()

◆ registered_component_types()

Variable Documentation

◆ _LOADED

◆ _SPECS

◆ _SPECS_FILE