@spec from_tensor(
  Nx.Tensor.t(),
  keyword()
) :: {:ok, ExZarr.Array.t()} | {:error, term()}

Converts Nx tensor to ExZarr array using direct binary transfer.

Creates a new ExZarr array and writes the tensor data efficiently without converting to nested tuples.

Required Options

• :chunks - Chunk shape as tuple (required)

Optional Options

• :storage - Storage backend atom (default: :memory)
• :path - Path for filesystem storage
• :compressor - Compression codec (default: :zlib)
• :fill_value - Fill value for uninitialized chunks (default: 0)
• :zarr_version - Zarr format version, 2 or 3 (default: 2)

Returns

• {:ok, array} - Successfully created ExZarr.Array
• {:error, reason} - Conversion failed

Examples

# Basic conversion to memory
tensor = Nx.iota({1000, 1000})
{:ok, array} = ExZarr.Nx.from_tensor(tensor, chunks: {100, 100})

# Save to filesystem
{:ok, array} = ExZarr.Nx.from_tensor(tensor,
  storage: :filesystem,
  path: "/data/output",
  chunks: {100, 100},
  compressor: %{id: "zstd", level: 3}
)

# Create v3 array
{:ok, array} = ExZarr.Nx.from_tensor(tensor,
  chunks: {100, 100},
  zarr_version: 3
)

@spec nx_to_zarr_type(nx_type()) :: {:ok, zarr_dtype()} | {:error, String.t()}

Converts Nx type to ExZarr dtype.

Examples

iex> ExZarr.Nx.nx_to_zarr_type({:f, 64})
{:ok, :float64}

iex> ExZarr.Nx.nx_to_zarr_type({:s, 32})
{:ok, :int32}

iex> ExZarr.Nx.nx_to_zarr_type({:bf, 16})
{:error, "Unsupported Nx type: {:bf, 16}. BF16 is not part of Zarr specification."}

@spec supported_dtypes() :: [zarr_dtype()]

Returns list of supported dtype conversions.

Examples

iex> dtypes = ExZarr.Nx.supported_dtypes()
iex> :float64 in dtypes
true
iex> length(dtypes)
10

@spec supported_nx_types() :: [nx_type()]

Returns list of supported Nx type conversions.

Examples

iex> types = ExZarr.Nx.supported_nx_types()
iex> {:f, 64} in types
true
iex> length(types)
10

@spec to_tensor(
  ExZarr.Array.t(),
  keyword()
) :: {:ok, Nx.Tensor.t()} | {:error, term()}

Converts ExZarr array to Nx tensor using direct binary transfer.

This is the recommended way to convert ExZarr arrays to Nx tensors. Uses efficient binary conversion without intermediate nested tuple representation.

Options

• :backend - Nx backend to use (default: current default backend)
• :names - Axis names for the tensor (list of atoms)

Returns

• {:ok, tensor} - Successfully converted Nx.Tensor
• {:error, reason} - Conversion failed

Performance

Conversion time scales linearly with array size:

• 1 MB: ~2ms
• 10 MB: ~15ms
• 100 MB: ~150ms

For arrays larger than available RAM, use to_tensor_chunked/3 instead.

Examples

# Basic conversion
{:ok, array} = ExZarr.open(path: "/data/array")
{:ok, tensor} = ExZarr.Nx.to_tensor(array)

# Transfer to specific backend
{:ok, tensor} = ExZarr.Nx.to_tensor(array, backend: EXLA.Backend)

# With axis names
{:ok, tensor} = ExZarr.Nx.to_tensor(array, names: [:batch, :features])

@spec to_tensor_chunked(ExZarr.Array.t(), tuple(), keyword()) ::
  Enumerable.t({:ok, Nx.Tensor.t()} | {:error, term()})

Converts ExZarr array to stream of Nx tensors by processing in chunks.

For large arrays that don't fit in memory, this function loads the array in chunks and yields a tensor for each chunk. Useful for processing large datasets incrementally.

Parameters

• array - ExZarr array to convert
• chunk_size - Size of chunks to load (tuple matching array dimensionality)
• opts - Options (same as to_tensor/2)

Returns

Stream that yields {:ok, tensor} or {:error, reason} for each chunk.

Examples

# Process 100×100 chunks from large array
{:ok, array} = ExZarr.open(path: "/data/large_array")

array
|> ExZarr.Nx.to_tensor_chunked({100, 100})
|> Stream.each(fn {:ok, tensor} ->
  # Process each tensor chunk
  result = Nx.mean(tensor) |> Nx.to_number()
  IO.puts("Chunk mean: #{result}")
end)
|> Stream.run()

# Map over chunks in parallel
results =
  array
  |> ExZarr.Nx.to_tensor_chunked({100, 100})
  |> Task.async_stream(fn {:ok, tensor} ->
    Nx.sum(tensor) |> Nx.to_number()
  end, max_concurrency: 4)
  |> Enum.to_list()

@spec zarr_to_nx_type(zarr_dtype()) :: {:ok, nx_type()} | {:error, String.t()}

Converts ExZarr dtype to Nx type.

Examples

iex> ExZarr.Nx.zarr_to_nx_type(:float64)
{:ok, {:f, 64}}

iex> ExZarr.Nx.zarr_to_nx_type(:int32)
{:ok, {:s, 32}}

iex> ExZarr.Nx.zarr_to_nx_type(:invalid)
{:error, "Unsupported dtype: :invalid"}