cottax.relational.consumers.declaration.declarations module

The relational declarations: a function paired with a condition node over what it outputs (an implicit model, a constraint), and a problem holding the constraints it is subject to.

class Implicit[N: Label, V: Place](fn: Body, function_reads: tuple[PlaceWithValue[V], ...], outputs: tuple[V, ...], *, output_tags: Tags[V] = {})

Bases: Paired[N, V], Generic[N, V]

An implicit model: a function writing ^cond.u per unknown (its outputs), in that order, and at ^solve.at the problem determining the unknowns.

terms: AbstractVar[tuple[Optional[PlaceWithValue[V]], ...]] = ()

What else it writes where a place is due, each a place (with the value where one was written) or None for zero: a constraint’s bounds or targets; none for most.

condition_mint

alias of Solve

property function_outputs: tuple[V, ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

condition_node(at: N)

The condition node as bound at at, its own name: condition, or one whose places derive from its name.

Return type:

ConditionalNode[V]

property problem: N

Where its problem binds, the model handed to declare loose: ^solve.<fn>.

class Residual[N: Label, V: Place](fn: Body, function_reads: tuple[PlaceWithValue[V], ...], outputs: tuple[V, ...], *, output_tags: Tags[V] = {})

Bases: Implicit[N, V], Generic[N, V]

The function returns a residual per unknown, each held at zero: ^cond.u = 0.

property condition: RelationalCondition[V]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

class FixedPoint[N: Label, V: Place](fn: Body, function_reads: tuple[PlaceWithValue[V], ...], outputs: tuple[V, ...], *, output_tags: Tags[V] = {})

Bases: Implicit[N, V], Generic[N, V]

The function returns the next value of each unknown, each held equal to it: a fixed point, u = ^cond.u.

property condition: RelationalCondition[V]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

class Bounds[V: Place](at_least: OrderedMap[V, Optional[PlaceWithValue[V]]], at_most: OrderedMap[V, Optional[PlaceWithValue[V]]])

Bases: Frozen, Generic[V]

Per place, a lower side, an upper side, or both: each a place (with its value where a number was written), or None for zero; a place absent from a side is unbounded there.

at_least: OrderedMap[V, Optional[PlaceWithValue[V]]]

at_most: OrderedMap[V, Optional[PlaceWithValue[V]]]

relations(among: tuple[V, ...])

lo <= x and x <= hi for each of among that a side bounds; a side of None is zero.

Return type:

tuple[Relation[V], ...]

property bounded: tuple[V, ...]

Every place a side bounds, once.

property parameters: tuple[V, ...]

held fixed while the bounded places move.

Type:

Every side that is a place, once

property terms: tuple[Optional[PlaceWithValue[V]], ...]

Each side as written, the lower then the upper.

check_held(constraint: Constraint)

Every place held against something is an output, and every output is held.

Return type:

Iterator[Violation]

class Constraint[N: Label, V: Place](fn: Body, function_reads: tuple[PlaceWithValue[V], ...], outputs: tuple[V, ...], *, output_tags: Tags[V] = {})

Bases: Paired[N, V], Generic[N, V]

A function computing its outputs, and at condition_at (^require.at) the requirement holding each against something. It determines nothing: an architecture absorbs it into the problem its conditions reach.

held_against: AbstractVar[tuple[V, ...]]

each output, and nothing else.

Type:

Every place the constraint holds against something

checks: PerLevel[tuple[Callable[[Any], object], ...]] = (<function check_held>,)

Callable [self] -> iterable of violations, which are raised at construction unless skipped (see unchecked).

condition_mint

alias of Require

property function_outputs: tuple[V, ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

condition_node(at: N)

The condition node as bound at at, its own name: condition, or one whose places derive from its name.

Return type:

ConditionalNode[V]

property requirement: N

Where its requirement binds, the constraint handed to declare loose: ^require.<fn>.

class InequalityConstraint[N: Label, V: Place](fn: Body, function_reads: tuple[PlaceWithValue[V], ...], outputs: tuple[V, ...], bounds: Bounds[V], *, output_tags: Tags[V] = {})

Bases: Constraint[N, V], Generic[N, V]

Each output within its bounds: g <= g_max, q >= q_min, lo <= t <= hi, zero where a side is None.

bounds: Bounds[V]

property held_against: tuple[V, ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

property terms: tuple[Optional[PlaceWithValue[V]], ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

property condition: RelationalCondition[V]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

class EqualityConstraint[N: Label, V: Place](fn: Body, function_reads: tuple[PlaceWithValue[V], ...], outputs: tuple[V, ...], targets: OrderedMap[V, Optional[PlaceWithValue[V]]], *, output_tags: Tags[V] = {})

Bases: Constraint[N, V], Generic[N, V]

Each output equal to its target: h = h_target, or h = 0 where it is None.

targets: OrderedMap[V, Optional[PlaceWithValue[V]]]

Each output’s target (with its value where a number was written), or None for zero.

property held_against: tuple[V, ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

property terms: tuple[Optional[PlaceWithValue[V]], ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

property condition: RelationalCondition[V]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

check_subject_to(problem: Problem)

A problem is subject to constraint wrappers and requirements, nothing else.

Return type:

Iterator[Violation]

check_bounds_on_unknowns(problem: Problem)

Every bounded place is an unknown: a bound on anything else would hold nothing.

Return type:

Iterator[Violation]

check_condition(problem: Problem)

Its condition is a condition node: refused here, where it is written, not when declared.

Return type:

Iterator[Violation]

class Problem[N: Label, V: Place](unknowns: tuple[V, ...], bounds: Bounds[V], objectives: tuple[Objective[V], ...], subject_to: tuple[Union[Constraint[N, V], RelationalCondition[V]], ...])

Bases: Declaration[N, V], Generic[N, V]

A relational condition node declared alone, with no body: the unknowns it determines, their bounds, its objectives, and the constraints and requirements it is subject to.

unknowns: tuple[V, ...]

bounds: Bounds[V]

(lo, hi) as written.

Type:

On the unknowns

objectives: tuple[Objective[V], ...]

One for optimise, none for satisfy.

subject_to: tuple[Union[Constraint[N, V], RelationalCondition[V]], ...]

Constraints and requirements held in this problem’s one condition node.

checks: PerLevel[tuple[Callable[[Any], object], ...]] = (<function check_subject_to>, <function check_bounds_on_unknowns>, <function check_condition>)

Callable [self] -> iterable of violations, which are raised at construction unless skipped (see unchecked).

property holds: tuple[Union[Constraint[N, V], RelationalCondition[V]], ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

property outputs: tuple[V, ...]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

nodes_when_held(at: N)

Nothing: what holds it takes its condition.

Return type:

tuple[tuple[N, NodeDefinition[V]], ...]

property held: tuple[RelationalCondition[V], ...]

The requirement of each constraint it is subject to.

property condition: RelationalCondition[V]

property given: OrderedMap[V, Any]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

property tags: Tags[V]

abstract to ABC until a subclass binds the name, and absent on a class that declares it as a field.

Type:

What the level binds in place of the annotation

nodes(at: N)

What this declares, bound at at and at names derived from it.

Return type:

tuple[tuple[N, NodeDefinition[V]], ...]

loose_at(names: DerivedNames[N, V])

^solve.<objective>; none with no objective.

Return type:

Optional[N]

class AgainstNoOutput(fn: str, places: tuple)

Bases: Violation

fn: str

places: tuple

template: AbstractClassVar[str] = '{fn}: a limit given for {places!r}, which it does not output'

e.g. ‘output {place!r} is owned by both {other!r} and {node!r}’

Type:

Wording

class HeldAgainstNothing(fn: str, places: tuple)

Bases: Violation

fn: str

places: tuple

template: AbstractClassVar[str] = '{fn}: {places!r} held against nothing -- once any limit is given every output is named, `0` for zero'

e.g. ‘output {place!r} is owned by both {other!r} and {node!r}’

Type:

Wording

class BoundNotUnknown(places: tuple)

Bases: Violation

places: tuple

template: AbstractClassVar[str] = 'bounds on {places!r}, which are not unknowns of the problem'

e.g. ‘output {place!r} is owned by both {other!r} and {node!r}’

Type:

Wording

class NotHeldAs(constraint: str)

Bases: Violation

constraint: str

template: AbstractClassVar[str] = '{constraint}: a problem is subject to a constraint or a requirement'

e.g. ‘output {place!r} is owned by both {other!r} and {node!r}’

Type:

Wording

class NotAPair(place: object, written: str)

Bases: Violation

place: object

written: str

template: AbstractClassVar[str] = '{place!r}: its bounds are a pair `(lo, hi)`, each a name, a value or None, and {written} is not one'

e.g. ‘output {place!r} is owned by both {other!r} and {node!r}’

Type:

Wording