TensorInterface¶

class samplomatic.tensor_interface.TensorInterface(specs: Iterable[Specification])[source]¶

Bases: MutableMapping

An interface described by strict value type specifications, with a focus on tensor values.

This object implements the mapping protocol against data that is present; if a possible value type has a Specification, it is not reported as being present (i.e. "name" in interface) until a value has been assigned to it. Assigning to a key without a specification, or an invalid value to a specified key, will raise an error.

Parameters:: specs – An iterable of specificaitons for the allowed data in this interface.

Attributes Summary

`bound_dimensions`	Those `free_dimensions` that have already been bound to a value.
`free_dimensions`	All free dimensions in the interface.
`fully_bound`	Whether all non-optional interfaces have data specified.
`ndim`	The number of dimensions, i.e. the length of `shape`.
`shape`	The shape of this interface broadcasted over all present broadcastable tensor values.
`size`	The total number of elements once broadcasted, i.e. the product of the `shape`.
`specs`	The interface specifacations, sorted by name.

Methods Summary

`bind`(**kwargs)	Bind data to this interface.
`describe`([include_bound, ...])	Return a human-readable description of this interface.
`get_specs`([pattern])	Return all specifications of this inteface whose names the pattern string.
`make_broadcastable`()	Return a new interface like this one where all tensor specifications are broadcastable.

Attributes Documentation

bound_dimensions¶: Those free_dimensions that have already been bound to a value.

free_dimensions¶: All free dimensions in the interface.

fully_bound¶: Whether all non-optional interfaces have data specified.

ndim¶: The number of dimensions, i.e. the length of shape.

shape¶

The shape of this interface broadcasted over all present broadcastable tensor values.

This shape does not include the native shapes of any particular tensor value. For example, if some broadastable value has shape (4, 5, 6, 7) and the associated tensor specification has shape (6, 7), then this value naturally contributes a shape of (4, 5) to this interface. Consequently, the shape here will always be () for an interface with no broadcastable specifications.

size¶: The total number of elements once broadcasted, i.e. the product of the shape.

specs¶: The interface specifacations, sorted by name.

Methods Documentation

bind(**kwargs) → Self[source]¶

Bind data to this interface.

A tensor interface is a flat data structure mapping names to values, where the values must conform to constraints specifed by the specs.

>>> from samplomatic.tensor_interface import TensorSpecification, TensorInterface
>>> import numpy as np
>>>
>>> interface = TensorInterface([
...     TensorSpecification("foo.bar", (2, 3), np.float64),
...     TensorSpecification("x", (15,), np.int64),
...     TensorSpecification("y", (4,), np.float32)
... ])
>>>
>>> # bind a single value
>>> interface.bind(x=np.arange(15), y=np.linspace(0, 1, 4))
TensorInterface(...)
>>>
>>> # bind a value that has a "."-separated name
>>> interface.bind(foo={"bar": np.zeros((2, 3))})
TensorInterface(...)
>>>
>>> # alternatively, items can be set directly
>>> interface["foo.bar"] = np.ones((2, 3))
>>> interface["y"] = [2.1, 2.2, 2.3, 2.4]

Parameters:: **kwargs – Key-value data to bind.
Raises:: ValueError – If a specification not present in this interface is in kwargs.
Returns:: This interface.

describe(include_bound: bool = True, include_free_dimensions: bool = False, prefix: str = '* ', bound_prefix: str | None = None, width: int = 0) → str[source]¶

Return a human-readable description of this interface.

Parameters:

include_bound – Whether to include interface specs that are already bound.
include_free_dimensions – Whether to include information about free dimensions and their bound values.
prefix – A string prefix for every specification in the interface that has no value.
bound_prefix – A string prefix for every specification in the interface that has a value, or None to use the same value as prefix.
width – The text width to wrap at, minimum 40, but where 0 specifies no wrapping.

Returns:

A description.

get_specs(pattern: str = '') → list[Specification][source]¶

Return all specifications of this inteface whose names the pattern string.

Parameters:: pattern – A pattern string. Regex is supported.
Returns:: Those specifications whose names match the pattern, sorted.

make_broadcastable() → TensorInterface[source]¶

Return a new interface like this one where all tensor specifications are broadcastable.

Returns:: A new TensorInterface.