ExternalTensor¶

class onnx_ir.ExternalTensor(location, offset, length, dtype, *, shape, name, doc_string=None, metadata_props=None, base_dir='')¶

An immutable concrete tensor with its data store on disk.

This class uses memory mapping to avoid loading the tensor into memory, when the data type is supported by numpy. Otherwise, the tensor is loaded into memory lazily when accessed.

Calling shape does not incur IO. Checking shape before loading the tensor is recommended if IO overhead and memory usage is a concern.

To obtain an array, call numpy(). To obtain the bytes, call tobytes().

The location must be a relative path conforming to the ONNX specification. Given the correct base_dir, the path is computed to be the full path to the data file. Users should expect that the path always leads to the correct file. At initialization, paths are not checked. It is the user’s responsibility to ensure the paths are valid and accessible.

Parameters:

location (os.PathLike | str)
offset (int | None)
length (int | None)
dtype (_enums.DataType)
shape (Shape)
name (str)
doc_string (str | None)
metadata_props (dict[str, str] | None)
base_dir (os.PathLike | str)

location¶: The location of the data file. It is the path relative to the base directory.

base_dir¶: The base directory for the external data. It is used to resolve relative paths. At serialization, only the location is serialized into the “location” field of the TensorProto.

path¶: The path to the data file. This is computed by joining base_dir and location.

offset¶: The offset in bytes from the start of the file.

length¶: The length of the data in bytes.

dtype¶: The data type of the tensor.

shape¶: The shape of the tensor.

name¶: The name of the tensor. It must be specified.

doc_string¶: The documentation string.

metadata_props¶: The metadata properties.

raw¶

property base_dir: str | PathLike¶

display(*, page=False)¶

Pretty print the object.

Parameters:: page (bool) – Whether to page the output.
Return type:: None

property doc_string: str | None¶: The documentation string.

property dtype: DataType¶

invalidate()[source]¶

Invalidate the tensor.

The external tensor is invalidated when the data is known to be corrupted or deleted.

Return type:: None

property length: int | None¶

property location: str | PathLike¶

property meta: MetadataStore¶

The metadata store for intermediate analysis.

Write to the metadata_props if you would like the metadata to be serialized to the ONNX proto.

property metadata_props: dict[str, str]¶

property name: str | None¶: The name of the tensor.

property nbytes: int¶: The number of bytes in the tensor.

numpy()[source]¶

Return the tensor as a numpy array.

The data will be memory mapped into memory and will not taken up physical memory space.

Return type:: ndarray

property offset: int | None¶

property path: str¶

release()[source]¶

Delete all references to the memory buffer and close the memory-mapped file.

Return type:: None

property shape: Shape¶

property size: int¶: The number of elements in the tensor.

tobytes()[source]¶

Return the bytes of the tensor.

This will load the tensor into memory.

Return type:: bytes

valid()[source]¶

Check if the tensor is valid.

The external tensor is valid if it has not been invalidated.

Return type:: bool