cottax.relational.consumers.declaration

The relational declaring part of a study’s surface, RelationalDeclaring, and the declarations it builds.

class RelationalDeclaring(locator: Locator[V, N], conventions: ~cottax.consumers.declaration.conventions.Conventions = Conventions(reads=ParameterReads(by_name=True), term=<function term_of>, per_place=<function per_place_of>))

Bases: Declaring

The relational declarations: implicit models and constraints as functions, and the relational conditions over them.

residual

A function returning a residual per unknown, and the problem where each vanishes: residual(fn, *unknowns), or @residual(*unknowns).

fixed_point

A function returning each unknown’s next value, and the problem holding each equal to it: fixed_point(fn, *unknowns), or @fixed_point(*unknowns).

inequality_constraint

A function computing its outputs, each within its (lo, hi) – one pair for the one output there is, or a mapping of pairs – and with none given at most zero: inequality_constraint(fn, *outputs, within=(None, ‘g_max’)), or the decorator.

equality_constraint

A function computing its outputs, each equal to its target – one for the one output there is, or a mapping – and with none given zero: equality_constraint(fn, *outputs, against=’h_target’), or the decorator.

requirement(condition: Place, op: type[Rel] = Eq)

c op 0, determining nothing: held by a problem subject to it, or where an architecture puts it.

Return type:

RelationalCondition

satisfy(*, design: Design, subject_to: SubjectTo = ())

Any point of design (names, or a mapping to (lo, hi)) meeting the constraints it is subject to (one, or a collection), nothing minimised: a root find where those are equalities.

Return type:

Problem

optimise(*, design: Design, minimise: Place | None = None, maximise: Place | None = None, subject_to: SubjectTo = ())

Minimise or maximise one objective over design (names, or a mapping to (lo, hi)), subject to constraints – one, or a collection: constraint wrappers in the model, or bare requirements, held by the problem.

Return type:

Problem

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 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

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]

Submodules

• cottax.relational.consumers.declaration.declarations module
  • Implicit
  • Residual
  • FixedPoint
  • Bounds
  • check_held()
  • Constraint
  • InequalityConstraint
  • EqualityConstraint
  • check_subject_to()
  • check_bounds_on_unknowns()
  • check_condition()
  • Problem
  • AgainstNoOutput
  • HeldAgainstNothing
  • BoundNotUnknown
  • NotHeldAs
  • NotAPair
• cottax.relational.consumers.declaration.vocabulary module
  • Pair
  • Within
  • Against
  • SubjectTo
  • Design
  • within_of()
  • against_of()
  • RelationalDeclaring
  • bounds_of()
  • design_of()
  • targets_of()