GitHub

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:

source
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:

source

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.

The repository also ships small CLI wrappers under bin/ for interoperability testing, including the canonical dense-HDF5 checker used by binsparse-tests.

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)

The alias keyword controls whether a predefined format name (e.g. "CSR") is used for the output. When alias=false, the output always uses a "custom" format. Otherwise (alias=true or alias=nothing), a predefined format name is used whenever one describes the tensor's layout.

Warning

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

source
Finch.bspread — Function

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

Read the Binsparse file into a Finch tensor.

The file version must have the same major and minor versions as BINSPARSE_VERSION and an equal or lower patch version.

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.

source

TensorMarket (.mtx, .ttx)

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

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

source

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

source
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

source