cottax.consumers.declaration.interface_types module

What a declaration is written with and built on: a term as written (Side), a tag or a value beside a place (Tagged, PlaceWithValue), a function described (Description), what a vocabulary’s kinds extend (Declaration, Wrapper, Paired) and cottax’s own (Explicit), and a kind as a declaring part’s method (declares, reading its `Keyword`s).

type Side[P] = Named | Any

A term written where a place is due: a name, a path, or a value (a number, an array, a tagged one).

class Tagged(value: Any)

Bases: Frozen

What is written (a name, a path, a value or a model in a slot) with a tag the declarations carry but never read: the feature that gives the tag its meaning reads it (Static: part of the compile key). Around a name or a path the place carries it, around a value the place minted for it, around a model the node name its slot gives.

value: Any

untagged(x: Any)

What is written under its tags, and the tags, outermost first, each without what it wraps.

Return type:

tuple[Any, tuple[Tagged, ...]]

class PlaceWithValue[V: Place](place: V, value: Any | None = None, tags: tuple[Tagged, ...] = ())

Bases: Frozen, Generic[V]

A place, the value written for it (None where none was), and the tags written on the place.

place: V

value: Any | None = None

tags: tuple[Tagged, ...] = ()

given_in[V: Place](*groups: Iterable[Optional[PlaceWithValue[V]]])

Every value written among groups, by its place: what a declaration gives.

Return type:

OrderedMap[V, Any]

type Tags[K] = OrderedMap[K, tuple[Tagged, ...]]

The tags written on each place, or each node name.

merged_tags[K](pairs: Iterable[tuple[K, tuple[Tagged, ...]]])

Each name’s tags, once each, in the order written; a name with none left out.

Return type:

Tags[K]

class Description

Bases: Frozen

A function described rather than given: what a wrapper needs of it, its parameters in order. Its node is implemented by the description (a RepoRef to code elsewhere, say), which no backend runs until one resolves it.

parameters: AbstractVar[tuple[str, ...]]

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 Unimplemented(parameters: tuple[str, ...])

Bases: Description

A function yet to be written: its parameters, and nothing else. Its node has no implementation.

parameters: tuple[str, ...]

type Body = Callable[[...], Any] | Description

What a wrapper wraps: a function, or a description of one.

parameters_of(fn: Body)

The parameters of a function, in order: a description’s, or a callable’s signature.

Return type:

tuple[str, ...]

check_outputs(wrapper: Wrapper)

At least one place written: a node owning nothing is unreachable.

Return type:

Iterator[Violation]

check_signature(wrapper: Wrapper)

Each parameter a read, bound by position, and one place in function_reads for each.

Return type:

Iterator[Violation]

class Declaration[N: Label, V: Place]

Bases: Frozen, Generic[N, V]

What a model declares: the nodes it binds at a name, and the values and tags written for its places.

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

a residual’s or a problem’s unknowns.

Type:

The places it writes, as written

given: AbstractVar[OrderedMap[V, Any]]

Each value written, by the place minted for it.

tags: AbstractVar[Tags[V]]

The tags written on each place it reads or writes.

holds: AbstractVar[tuple[Any, ...]]

each keeps only nodes_when_held at its own name.

Type:

What it takes over

abstractmethod nodes(at: N)

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

Return type:

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

abstractmethod nodes_when_held(at: N)

What stays at at when another declaration holds this one.

Return type:

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

abstractmethod loose_at(names: DerivedNames[N, V])

The node name it takes handed over loose, outside a slot, names its place’s; None for none: then it goes in a slot.

Return type:

Optional[N]

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

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

A function, the place each parameter reads, by position, and the places it writes. It carries no name: where it is put names it (nodes(at)), and a name it derives it asks the place (DerivedNames). A final is declared by a vocabulary method declares makes.

fn: Body

The function, or a description of one (Unimplemented, a reference to code elsewhere).

function_reads: tuple[PlaceWithValue[V], ...]

The place each parameter of fn reads, in signature order, with the value where one was written.

outputs: tuple[V, ...]

a residual’s or a problem’s unknowns.

Type:

The places it writes, as written

output_tags: Tags[V] = {}

The tags written on its outputs.

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

a residual’s are places of their own, not the unknowns’.

Type:

The places its return values are written to, in order

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.

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

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

holds: AbstractVar[tuple[Any, ...]] = ()

each keeps only nodes_when_held at its own name.

Type:

What it takes over

property inputs: tuple[V, ...]

outputs’ mirror.

Type:

The place each parameter of fn reads, in signature order

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_when_held(at: N)

Its function: what holds it takes its condition.

Return type:

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

loose_at(names: DerivedNames[N, V])

Its function’s name, as a slot of that name gives it; none for a lambda or a callable value.

Return type:

Optional[N]

function_node()

The node running fn: reading function_reads, owning function_outputs; with no implementation where fn is Unimplemented.

Return type:

Union[Function[V], ImplementedFunction[V]]

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

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

A function computing its outputs, returned in that order.

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.

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

nodes(at: N)

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

Return type:

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

class Solve

Bases: Mint

Where the problem beside a model binds, or a problem named after its objective: ^solve.at.

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

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

A function, and beside it a condition node over what it outputs, at the function’s name under condition_mint (^solve.at, ^require.at): an implicit model, a constraint, an ODE.

condition_mint: AbstractClassVar[type[Mint]]

Solve, Require.

Type:

The purpose the condition node’s name is derived for

condition: AbstractVar[ConditionalNode[V]]

The condition node over what the function outputs.

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

condition_at(at: N)

The wrapper’s name -> the condition node’s.

Return type:

N

nodes(at: N)

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

Return type:

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

loose_condition()

Where the condition node binds when the wrapper is handed to declare loose: beside its function’s name. In a slot the slot names it, and this name is bound nowhere.

Return type:

N

class Keyword(keyword: str, read: Callable[..., Any])

Bases: Frozen

A wrapper field read from a keyword argument of its own: read(surface, fn, outputs, written), outputs the places written and written the argument, None if not given.

keyword: str

read: Callable[..., Any]

built_from[V: Place](surface: Declaring, fn: Body, outputs: tuple, reads: Any = OrderedMap(), read_in: Mapping[Surface, str | tuple[str, ...]] = OrderedMap())

What a wrapper is built from: fn, a place per parameter (the surface’s parameter_reads, each read_in surface’s place its rule, a value minted beside the first output), the outputs as places, and the tags written on them.

Return type:

tuple[Body, tuple[PlaceWithValue[V], ...], tuple[V, ...], Tags[V]]

declares[W: Wrapper](kind: type[W], doc: str, **keywords: Keyword)

A surface’s method declaring kind: residual = declares(Residual, doc).

Return type:

Declares[W]

class Declares[W: Wrapper](kind: type[W], doc: str, keywords: Mapping[str, Keyword])

Bases: Generic[W]

A declaring part’s method declaring a kind, method(fn, *outputs) or @method(*outputs), built from built_from(surface, fn, outputs, reads, read_in) and each field named in keywords read from its Keyword. Named where it is bound; doc is its docstring.

class BoundDeclares[W: Wrapper](declares: Declares[W], surface: Declaring)

Bases: Generic[W]

A Declares on its surface: the call form returns the kind, the decorator form a decorator returning it.

now_or_as_decorator(args: tuple, build: Callable[[Body, tuple], Any])

build(fn, outputs) now, where a function (or its description) comes first: residual(fn, ‘u’). Else args are the outputs, and what is returned is a decorator, at a def only, that builds from it: @residual(‘u’). The wrapper takes the function’s name, so the function is re-pointed to be found through it (disc2.fn): a graph holding the function still pickles.

Return type:

Any