Finch Tensor File Input/Output

All of the file formats supported by Finch are listed below. Each format has a corresponding read and write function, and can be selected automatically based on the file extension with the following functions:

Finch.fread — Function
fread(filename::AbstractString)

Read the Finch tensor from a file using a file format determined by the file extension. The following file extensions are supported:

Finch.fwrite — Function
fwrite(filename::AbstractString, tns::Finch.Tensor)

Write the Finch tensor to a file using a file format determined by the file extension. The following file extensions are supported:

Binsparse Format (.bsp)

Finch supports the most recent revision of the Binsparse binary sparse tensor format, including the v2.0 tensor extension. This is a good option for those who want an efficient way to transfer sparse tensors between supporting libraries and languages. The Binsparse format represents the tensor format as a JSON string in the underlying data container, which can be either HDF5 or a combination of NPY or JSON files. Binsparse arrays are stored 0-indexed.

Finch.bspwrite — Function
bspwrite(::AbstractString, tns)
bspwrite(::HDF5.File, tns)
bspwrite(::NPYPath, tns)

Write the Finch tensor to a file using Binsparse file format.

Supported file extensions are:

  • .bsp.h5: HDF5 file format (HDF5 must be loaded)
  • .bspnpy: NumPy and JSON directory format (NPZ must be loaded)
Warning

The Binsparse spec is under development. Additionally, this function may not be fully conformant. Please file bug reports if you see anything amiss.

Finch.bspread — Function

bspread(::AbstractString) bspread(::HDF5.File) bspread(::NPYPath)

Read the Binsparse file into a Finch tensor.

Supported file extensions are:

  • .bsp.h5: HDF5 file format (HDF5 must be loaded)
  • .bspnpy: NumPy and JSON directory format (NPZ must be loaded)
Warning

The Binsparse spec is under development. Additionally, this function may not be fully conformant. Please file bug reports if you see anything amiss.

TensorMarket (.mtx, .ttx)

Finch supports the MatrixMarket and TensorMarket formats, which prioritize readability and archiveability, storing matrices and tensors in plaintext.

Finch.fttwrite — Function
fttwrite(filename, tns)

Write a sparse Finch tensor to a TensorMarket file.

TensorMarket must be loaded for this function to be available.

See also: ttwrite

Finch.fttread — Function
fttread(filename, infoonly=false, retcoord=false)

Read the TensorMarket file into a Finch tensor. The tensor will be dense or COO depending on the format of the file.

TensorMarket must be loaded for this function to be available.

See also: ttread

FROSTT (.tns)

Finch supports the FROSTT format for legacy codes that still use it.

Finch.ftnswrite — Function
ftnswrite(filename, tns)

Write a sparse Finch tensor to a FROSTT .tns file.

TensorMarket must be loaded for this function to be available.

Danger

This file format does not record the size or eltype of the tensor, and is provided for archival purposes only.

See also: tnswrite

Finch.ftnsread — Function
ftnsread(filename)

Read the contents of the FROSTT .tns file 'filename' into a Finch COO Tensor.

TensorMarket must be loaded for this function to be available.

Danger

This file format does not record the size or eltype of the tensor, and is provided for archival purposes only.

See also: tnsread