relation

fusdb.relation

Acausal relation object and @relation decorator.

RelationSolveError

Bases: ValueError

Raised when a relation cannot be solved or verified.

RelationUnderdeterminedError

Bases: RelationSolveError

Raised when too few variable values are supplied to a standalone relation.

RelationVerificationError

Bases: RelationSolveError

Raised when a solved value does not verify against the canonical relation.

Relation dataclass

One equation or inequality over FusDB variables.

Parameters:

Name	Type	Description	Default
name	str	User-facing relation name.	required
func	Callable[..., Any]	Python implementation.	required
input_names	tuple[str, ...]	Function input variable names.	required
outputs	tuple[str, ...]	Declared output variable names.	()
op	str	Comparison operator for outputless numeric residuals.	'=='
rhs	Any	Right side for outputless numeric residuals.	0.0
tags	tuple[str, ...]	Descriptive/applicability tags.	()
enforce	bool	Whether this relation is solver-enforced.	True
constraints	Any	Relation-local constraints or applicability guards.	None
source_kind	str	Diagnostic source category.	'relation'
source_name	str	Diagnostic source name.	''
constant_names	tuple[str, ...]	Function parameters with defaults.	()
dependency	str	Dependency hint used for graph reports.	'dense'
function_name	str	Decorated Python function name.	''

output_names property

output_names: tuple[str, ...]

Declared output names.

variables property

variables: tuple[str, ...]

Variables touched by the relation.

implicit property

implicit: bool

Whether an output also appears as an input.

__post_init__

__post_init__() -> None

Normalize metadata and build local constraint relations.

__call__

__call__(**kwargs: Any) -> Any

Use the relation with strict standalone acausal semantics.

Let n be the number of relation variables, i.e. declared inputs plus declared outputs. Constants with defaults are not counted.

• If all n variables are supplied, return True/False from canonical verification.
• If exactly n - 1 variables are supplied, compute the single missing variable and return its value.
• If fewer than n - 1 variables are supplied, raise a clear underdetermined error.

The returned value from an inverse solve is accepted only after the canonical relation and local relation constraints verify within the registry tolerances.

evaluate

evaluate(namespace: Mapping[str, Any]) -> Any

Evaluate the implementation function in its declared direction.

Parameters:

Name	Type	Description	Default
namespace	Mapping[str, Any]	Mapping of variable names to values.	required

Returns:

Type	Description
Any	Raw function return value.

output_map

output_map(result: Any) -> dict[str, Any]

Map a raw implementation result to declared outputs.

Parameters:

Name	Type	Description	Default
result	Any	Raw function result.	required

Returns:

Type	Description
dict[str, Any]	Output name/value mapping.

comparisons

comparisons(namespace: Mapping[str, Any]) -> list[tuple[Any, str, Any, str | None]]

Return comparison tuples (lhs, op, rhs, output_name).

Parameters:

Name	Type	Description	Default
namespace	Mapping[str, Any]	Variable values.	required

Returns:

Type	Description
list[tuple[Any, str, Any, str | None]]	Comparison tuples used by verification and residual compilation.

solve

solve(values: Mapping[str, Any] | None = None) -> Any

Evaluate, verify, or invert a standalone relation.

Parameters:

Name	Type	Description	Default
values	Mapping[str, Any] | None	Supplied relation variable values. Constants may also be supplied, but they are not counted as relation variables.	None

Returns:

Type	Description
Any	bool when all relation variables are supplied, otherwise the
Any	single missing variable value.

residual_vector

residual_vector(ns: Mapping[str, Any], *, scales: Mapping[str, Any] | None = None, rel_tols: Mapping[str, float] | None = None, abs_tols: Mapping[str, float] | None = None, safe: bool = False) -> np.ndarray

Return a finite scaled residual vector.

Parameters:

Name	Type	Description	Default
ns	Mapping[str, Any]	Variable namespace.	required
scales	Mapping[str, Any] | None	Optional variable scale mapping.	None
rel_tols	Mapping[str, float] | None	Optional variable relative tolerance mapping.	None
abs_tols	Mapping[str, float] | None	Optional variable absolute tolerance mapping.	None
safe	bool	Convert evaluation failures/non-finite values into large finite residuals.	False

Returns:

Type	Description
ndarray	One-dimensional residual vector.

verify_status

verify_status(ns: Mapping[str, Any], *, scales: Mapping[str, Any] | None = None, rel_tols: Mapping[str, float] | None = None, abs_tols: Mapping[str, float] | None = None) -> dict[str, Any]

Verify one relation and its local constraints.

Parameters:

Name	Type	Description	Default
ns	Mapping[str, Any]	Variable namespace.	required
scales	Mapping[str, Any] | None	Optional variable scale mapping.	None
rel_tols	Mapping[str, float] | None	Optional variable relative tolerance mapping.	None
abs_tols	Mapping[str, float] | None	Optional variable absolute tolerance mapping.	None

Returns:

Type	Description
dict[str, Any]	Diagnostic dictionary.

from_function classmethod

from_function(func: Callable[..., Any], *, outputs: Any = None, name: str | None = None, tags: Iterable[str] | None = None, enforce: bool = True, constraints: Any = None, dependency: str = 'dense') -> 'Relation'

Build a relation from a decorated Python function.

Parameters:

Name	Type	Description	Default
func	Callable[..., Any]	Python implementation function.	required
outputs	Any	Explicit output name or names.	None
name	str | None	Optional user-facing relation name.	None
tags	Iterable[str] | None	Relation tags.	None
enforce	bool	Whether relation is solver-enforced.	True
constraints	Any	Local constraints/applicability guards.	None
dependency	str	Dependency hint.	'dense'

Returns:

Type	Description
'Relation'	Relation object.

relation

relation(_func: Callable[..., Any] | None = None, *, outputs: Any | None = None, name: str | None = None, tags: Iterable[str] | None = None, enforce: bool = True, constraints: Any = None, dependency: str = 'dense') -> Callable[[Callable[..., Any]], Relation] | Relation

Decorate a function as a FusDB relation.

Parameters:

Name	Type	Description	Default
_func	Callable[..., Any] | None	Function when used as @relation without parentheses.	None
outputs	Any | None	Explicit output name or names.	None
name	str | None	User-facing relation name.	None
tags	Iterable[str] | None	Relation tags.	None
enforce	bool	Whether the relation is enforced.	True
constraints	Any	Local constraints or applicability guards.	None
dependency	str	Dependency hint.	'dense'

Returns:

Type	Description
Callable[[Callable[..., Any]], Relation] | Relation	Relation object or decorator.

constraint_from_expression

constraint_from_expression(text: str, *, name: str | None = None, enforce: bool = True, tags: Iterable[str] | None = None, source_kind: str = 'constraint', source_name: str = '') -> Relation

Parse a simple comparison into an outputless relation.

Parameters:

Name	Type	Description	Default
text	str	Constraint expression such as x <= y.	required
name	str | None	Optional relation name.	None
enforce	bool	Whether the relation is solver-enforced.	True
tags	Iterable[str] | None	Optional tags.	None
source_kind	str	Diagnostic source kind.	'constraint'
source_name	str	Diagnostic source name.	''

Returns:

Type	Description
Relation	Relation object.