Format | TensorSuite

Bundle Layout

One folder per tensor record.

TensorSuite stores each tensor as a folder, called a bundle. The *_metadata.json file is the canonical schema for tensor attributes and metadata; .tns and .tnsb are data representations inside the bundle. README.md saves the extra information that doesn't fit in the metadata JSON file.

Named Files

A tensor-name folder uses matching file prefixes, such as example-tensor_metadata.json, example-tensor.tns, and example-tensor.tnsb.

Metadata

*_metadata.json records identity, attributes, tensor size information, and file mappings for the tensor folder.

Data Files

Data files store coordinate-oriented tensor records in text or binary form or both.

README

README.md documents auxiliary data and any details that do not fit in the metadata JSON file.

Example tensor bundle

example-tensor/
  example-tensor_metadata.json
  example-tensor.tns
  example-tensor.tnsb
  README.md

Example binary-only tensor bundle

large-tensor/
  large-tensor_metadata.json
  large-tensor.tnsb
  README.md

Tensor Data Files

Coordinate data in text and binary files.

Tensor data files keep a minimal cross-check header, size information, and coordinate records. This section introduces both the element-wise and block-wise sparse tensor layouts.

Element-wise

Element-wise sparse tensor files.

Element-wise sparse tensors store each non-zero entry as explicit coordinates followed by one value. The .tns and .tnsb data layouts stay consistent with the FROSTT collection, with a few simple information lines added on top.

Minimal Header

The first line is %%TensorSuite-TNS. Then % version and % name let users cross-check the file against the metadata JSON.

Tensor Size Line

One line gives the tensor order, all mode/dimension sizes, and the total number of non-zero elements so users can preallocate memory and validate the entry count.

Entries

Each data row stores one-based or zero-based coordinates, optionally followed by a non-zero value. Values may be omitted to allow users to generate them according to metadata constraints such as value_domain and any README notes.

Example element-wise text tensor file

%%TensorSuite-TNS
% version: 0.1
% name: example-tensor
3 4 3 2 5
1 1 1 1.0000000000000000
1 2 1 2.5000000000000000
2 2 1 -1.2500000000000000
3 1 2 4.0000000000000000
4 3 2 0.5000000000000000

Example element-wise binary tensor file

%%TensorSuite-TNSB
% version: 0.1
% name: example-tensor
3 4 3 2 5
[binary coordinate/value records begin here]

Block-wise

Block-wise sparse tensor files.

Block-wise files use the same .tns text suffix and .tnsb binary suffix as element-wise files. The metadata JSON identifies the tensor as block-wise in the sparsity_type attribute. The header lines and the tensor size line are the same as in element-wise files, while they are followed by a block size line, block partitions, and entries that record the coordinates of non-zero blocks instead of non-zero elements. This block-wise format has only slight differences from NVIDIA's cuTENSOR file format and is compatible with the cuTENSOR API.

Block Size Line

Following the tensor size line for the full tensor: 3 2000 2000 20 nnz, add a second size line giving the number of block partitions for each mode (called block grid) and the total number of non-zero blocks: 110 110 19 nnz_block.

Block Partitions

Then the file stores one block-partition array per mode to indicate the size of each block partition. Summing the values in an array yields the dimension size of that mode. For a 110 x 110 x 19 block grid, the next three arrays have lengths 110, 110, and 19, respectively.

Entries (for Non-Zero Blocks)

If a tensor has block-sparse structure, the data file omit values for benchmarking purposes. Users can fill values according to metadata constraints and any README notes.

Example block-sparse tensor file

%%TensorSuite-TNS
% version: 0.1
% name: block-example
3 2000 2000 20 768000
110 110 19 1200
18 18 18 ... 20
18 18 18 ... 20
1 1 1 ... 2
1 1 1
4 7 2
9 2 3
[remaining nonzero block coordinates]

Metadata JSON File

Canonical metadata and tensor attributes.

The JSON file provides the same schema for element-wise and block-wise tensors, with attributes used to distinguish them. The meanings of metadata and attributes, along with allowed values, are documented below.

version, name, order, dimensions, and nnz are used to cross-check with the .tns or .tnsb file to weakly ensure the tensor record is correct. For block-wise tensors, block_partitions and nnz_block are also used for this cross-check.

Attribute	Allowed Values	Meaning
`version`	String, `0.1` for this release	It should match the version recorded in the tensor data file.
`name`	String	Human-readable tensor name. The value should match the bundle file prefix.
`group`	String	Dataset family or category grouping tensors from the same application or scenario.
`id`	Four-digit number, e.g., `0001`	Short tensor identifier within TensorSuite.
`time`	ISO date string, e.g., `2026-05-06`	Date associated with the tensor record.
`source_type`	`synthetic`, `real`	Whether the tensor is generated or collected from a real application.
`source`	String	Application, method, generator, or provenance description. This can be a longer free-form string.
`source_url`	URL or empty string	External source link when available.
`value_type`	`float32`, `float64`, `int32`, `int64`	Numeric type used to store tensor values.
`value_domain`	`general`, `nonnegative`, `binary`	Numerical value constraint. `nonnegative` means all values are greater than or equal to zero; `binary` means values are restricted to `0` and `1`.
`values_provided`	`true`, `false`	Whether the tensor data file explicitly stores nonzero values. If `false`, values may be generated by users under metadata and README constraints.
`index_type`	`uint32`, `uint64`	Integer type used by coordinate indices.
`endianness`	`none`, `little`, `big`	Byte order used by `.tnsb` tensor files. Use `none` when the bundle has no binary tensor file.
`index_base`	`0`, `1`	Whether coordinates are zero-based or one-based.
`sorted`	`none`, `lexicographic`	Whether entries are sorted lexicographically by coordinates, using the 1-based mode priority in `sort_order`.
`sort_order`	1-based mode-id permutation, e.g., `[1,2,3]`	1-based mode-id priority used for lexicographic sorting.
`duplicates`	`allowed`, `disallowed`	Policy for repeated coordinates.
`explicit_zeros`	`allowed`, `disallowed`	Whether stored entries may have numerical value zero.
`pattern_symmetry`	`full`, `partial`, `no`	Symmetry of the nonzero coordinate pattern.
`numerical_symmetry`	`full`, `partial`, `no`	Symmetry of both coordinate pattern and mirrored values.
`sparsity_type`	`no`, `semi`, `element`, `block`	Dense, semi-sparse, element-sparse, or block-sparse structure.
`dense_modes`	1-based mode-id list, such as `[]` or `[1,2]`	1-based mode-id list for dense or semi-sparse tensors.
`block_partitions`	Mode-size list for block-sparse tensors, e.g., `[110,110,19]`, or `null`	Number of block partitions in each tensor mode. Use `null` for tensors without block-sparse structure.
`nnz_block`	Nonnegative integer, or `null`	Number of nonzero blocks. Use `null` for tensors without block-sparse structure.

Example element-wise metadata JSON file

{
  "version": "0.1",
  "name": "example-tensor",
  "group": "TensorSuite-example",
  "id": "0001",
  "time": "2026-05-06",
  "source_type": "synthetic",
  "source": "Generated element-wise tensor for format illustration.",
  "source_url": "",
  "value_type": "float64",
  "value_domain": "general",
  "values_provided": true,
  "index_type": "uint64",
  "index_base": 1,
  "sorted": "lexicographic",
  "sort_order": [1, 2, 3],
  "duplicates": "disallowed",
  "explicit_zeros": "allowed",
  "pattern_symmetry": "no",
  "numerical_symmetry": "no",
  "sparsity_type": "element",
  "dense_modes": [],
  "endianness": "little",
  "order": 3,
  "dimensions": [4, 3, 2],
  "nnz": 5,
  "block_partitions": null,
  "nnz_block": null,
  "files": {
    "text": "example-tensor.tns",
    "binary": "example-tensor.tnsb",
    "readme": "README.md"
  }
}

Example block-wise metadata JSON file

{
  "version": "0.1",
  "name": "block-example",
  "group": "TensorSuite-example",
  "id": "0002",
  "time": "2026-05-06",
  "source_type": "real",
  "source": "Generated block-sparse tensor for format illustration.",
  "source_url": "",
  "value_type": "float64",
  "value_domain": "nonnegative",
  "values_provided": false,
  "index_type": "uint64",
  "index_base": 1,
  "sorted": "lexicographic",
  "sort_order": [1, 2, 3],
  "duplicates": "disallowed",
  "explicit_zeros": "disallowed",
  "pattern_symmetry": "no",
  "numerical_symmetry": "no",
  "sparsity_type": "block",
  "dense_modes": [],
  "endianness": "little",
  "order": 3,
  "dimensions": [2000, 2000, 20],
  "nnz": 768000,
  "block_partitions": [110, 110, 19],
  "nnz_block": 1200,
  "files": {
    "text": "block-example.tns",
    "binary": "block-example.tnsb",
    "readme": "README.md"
  }
}

Reference IO

Reference Python helpers for TensorSuite bundles.

A small reference implementation builds, validates, reads, and writes metadata against the canonical TensorSuite schema, then reads and writes .tns and .tnsb files and cross-checks them against that metadata. For now, reading, cross-checking, and validation only verify the tensor size information; the other tensor attributes recorded in the metadata still need to be applied by users to generate the tensors they need.