---
title: TensorSpecification (latest version)
description: API reference for samplomatic.tensor_interface.TensorSpecification in the latest version of samplomatic
source: https://quantum.cloud.ibm.com/docs/en/api/samplomatic/auto/tensor-interface-tensor-specification
---

# TensorSpecification

*class* `samplomatic.tensor_interface.TensorSpecification(name: str, shape: tuple[int | str, ...], dtype: dtype, description: str = '', broadcastable: bool = False, optional: bool = False)`

[GitHub](https://github.com/Qiskit/samplomatic/tree/main/samplomatic/tensor_interface.py#L174-L301)

Bases: [`Specification`](/docs/api/samplomatic/auto/tensor-interface-specification "samplomatic.tensor_interface.Specification")\[[`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)]

A specification for tensor-valued interface values of a specific type and shape.

**Parameters**

- **name** – The name of the interface.
- **shape** – The shape of the input array.
- **dtype** – The data type of the array.
- **description** – A description of what the interface represents.
- **broadcastable** – Whether values in an interface that are constrained by this specification are allowed to be broadcastable with other broadcastable values in the same interface.
- **optional** – Whether the specification is optional.

**Attributes Summary**

|                                                                                                                                                           |                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [`description`](#samplomatic.tensor_interface.TensorSpecification.description "samplomatic.tensor_interface.TensorSpecification.description")             | A description of this specification.                                              |
| [`free_dimensions`](#samplomatic.tensor_interface.TensorSpecification.free_dimensions "samplomatic.tensor_interface.TensorSpecification.free_dimensions") | Named dimensions whose sizes are free until an interface value binds their value. |
| [`name`](#samplomatic.tensor_interface.TensorSpecification.name "samplomatic.tensor_interface.TensorSpecification.name")                                  | The name of this specification.                                                   |
| [`ndim`](#samplomatic.tensor_interface.TensorSpecification.ndim "samplomatic.tensor_interface.TensorSpecification.ndim")                                  | The number of dimensions, i.e. the length of `shape`.                             |
| [`num_bytes`](#samplomatic.tensor_interface.TensorSpecification.num_bytes "samplomatic.tensor_interface.TensorSpecification.num_bytes")                   | The number of bytes required to represent data for this specification.            |
| [`optional`](#samplomatic.tensor_interface.TensorSpecification.optional "samplomatic.tensor_interface.TensorSpecification.optional")                      | Whether this is an optional specification.                                        |

**Methods Summary**

|                                                                                                                                                                              |                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`describe`](#samplomatic.tensor_interface.TensorSpecification.describe "samplomatic.tensor_interface.TensorSpecification.describe")()                                       | Return a human-readable description of this specification. |
| [`validate_and_coerce`](#samplomatic.tensor_interface.TensorSpecification.validate_and_coerce "samplomatic.tensor_interface.TensorSpecification.validate_and_coerce")(value) | Coerce a value into a correct type if valid.               |

**Attributes Documentation**

### description

### free\_dimensions

### name

### ndim

The number of dimensions, i.e. the length of `shape`.

### num\_bytes

### optional

**Methods Documentation**

### describe

`describe() → str`

[GitHub](https://github.com/Qiskit/samplomatic/tree/main/samplomatic/tensor_interface.py#L231-L237)

Return a human-readable description of this specification.

### validate\_and\_coerce

`validate_and_coerce(value)`

[GitHub](https://github.com/Qiskit/samplomatic/tree/main/samplomatic/tensor_interface.py#L239-L281)

Coerce a value into a correct type if valid.

**Parameters**

**value** – A value to validate and coerce with respect to this specification.

**Raises**

[**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the value cannot be coerced into a valid type.

**Returns**

The coerced value, and a dictionary mapping each member of [`free_dimensions`](#samplomatic.tensor_interface.TensorSpecification.free_dimensions "samplomatic.tensor_interface.TensorSpecification.free_dimensions") to a size implied by the `value`.