TensorInterface
class samplomatic.tensor_interface.TensorInterface(specs: Iterable[Specification])
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
Column 1 | Column 2 |
|---|---|
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
Column 1 | Column 2 |
|---|---|
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. |
num_bytes(**dimensions) | Return the total number of bytes required to represent all data in this interface. |
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
bind(**kwargs: Mapping[str, Any]) → Self
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
describe(include_bound: bool = True, include_free_dimensions: bool = False, prefix: str = '* ', bound_prefix: str | None = None, width: int = 0) → str
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
Noneto use the same value asprefix. - width – The text width to wrap at, minimum 40, but where 0 specifies no wrapping.
Returns
A description.
get_specs
get_specs(pattern: str = '') → list[Specification]
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
make_broadcastable() → TensorInterface
Return a new interface like this one where all tensor specifications are broadcastable.
Returns
A new TensorInterface.
num_bytes
num_bytes(**dimensions: int) → int
Return the total number of bytes required to represent all data in this interface.
This sums num_bytes over all specifications, multiplied by the product of all free dimensions that each specification depends on.
This estimate is not overly concerned with accounting for memory required, say, for builtin Python container objects. It is more interested in the large data limit where memory is dominated by sources like NumPy buffers.
Parameters
**dimensions – Values for free dimensions. These override any already-bound dimensions.
Raises
ValueError – If any free dimensions are not specified.