Arrays¶

tinax.arrays owns NumPy, JAX, DLPack, host materialization, and logical array inspection. Its conversion functions make copying and ownership explicit.

See the Array Ownership guide for task-oriented usage.

from_numpy ¶

from_numpy(
    array: ndarray,
    *,
    copy: bool,
    device: Device | Sharding | None = None,
) -> Array

Create a JAX array from a NumPy array with explicit copy and placement policy.

Parameters:

Name	Type	Description	Default
`array`	`ndarray`	Source NumPy array to convert.	required
`copy`	`bool`	If `True`, take an independent host snapshot before transfer so that later mutation of `array` cannot affect the result. If `False`, allow JAX to alias the source buffer when the backend permits it.	required
`device`	`Device \| Sharding \| None`	Device or sharding to place the result on. `None` uses JAX's default placement.	`None`

Returns:

Type	Description
`Array`	A JAX array holding the converted data, placed according to `device`.

Raises:

Type	Description
`TypeError`	If `array` is not a `numpy.ndarray`, `copy` is not a `bool`, or `device` is not a `jax.Device`, `jax.sharding.Sharding`, or `None`.

from_dlpack ¶

from_dlpack(
    array: object,
    *,
    copy: bool | None = None,
    device: Device | Sharding | None = None,
) -> Array

Import a DLPack provider, completing copy=True before returning independent storage.

Parameters:

Name	Type	Description	Default
`array`	`object`	Object exposing the DLPack protocol to import.	required
`copy`	`bool \| None`	Copy policy. `True` forces an independent copy and blocks until the transfer completes; `False` requests a zero-copy import; `None` lets the backend choose.	`None`
`device`	`Device \| Sharding \| None`	Device or sharding for the imported array. `None` uses JAX's default placement.	`None`

Returns:

Type	Description
`Array`	A JAX array backed by the imported buffer. When `copy` is `True` the
`Array`	storage is guaranteed independent, including for same-device JAX providers.

Raises:

Type	Description
`TypeError`	If `copy` is not a `bool` or `None`, or `device` is not a `jax.Device`, `jax.sharding.Sharding`, or `None`.

to_numpy ¶

to_numpy(array: Array, *, writable: bool) -> ndarray

Synchronize a fully addressable JAX array and return a writable copy or read-only host value.

Blocks until the array is ready, then materializes its data on the host.

Parameters:

Name	Type	Description	Default
`array`	`Array`	Fully addressable JAX array to materialize on the host.	required
`writable`	`bool`	If `True`, return an independent, writable copy. If `False`, return a read-only NumPy value whose `writeable` flag is cleared.	required

Returns:

Type	Description
`ndarray`	The array's data as a `numpy.ndarray`. Writable results are independent
`ndarray`	copies; read-only results are a synchronized host view.

Raises:

Type	Description
`TypeError`	If `array` is not a `jax.Array` or `writable` is not a `bool`.
`ValueError`	If `array` is not fully addressable on the current process.

inspect_array ¶

inspect_array(array: Array) -> ArrayInfo

Inspect logical metadata without synchronizing or materializing array data.

Parameters:

Name	Type	Description	Default
`array`	`Array`	JAX array to inspect. Its data is never copied to the host.	required

Returns:

Type	Description
`ArrayInfo`	An `ArrayInfo` describing the array's shape, dtype, logical byte count,
`ArrayInfo`	commitment, and addressability.

Raises:

Type	Description
`TypeError`	If `array` is not a `jax.Array`.

ArrayInfo `dataclass` ¶

ArrayInfo(
    shape: tuple[int, ...],
    dtype: object,
    logical_nbytes: int | None,
    committed: bool,
    fully_addressable: bool,
)

Immutable logical metadata whose byte count is nominal rather than allocator memory.

Attributes:

Name	Type	Description
`shape`	`tuple[int, ...]`	Logical shape of the array.
`dtype`	`object`	Array dtype. Extended dtypes report `logical_nbytes` as `None`.
`logical_nbytes`	`int \| None`	Logical size in bytes, or `None` for extended dtypes whose element size is not a fixed byte count.
`committed`	`bool`	Whether the array is committed to a specific device.
`fully_addressable`	`bool`	Whether every shard is addressable by the current process.

Arrays¶

from_numpy ¶

from_dlpack ¶

to_numpy ¶

inspect_array ¶

ArrayInfo dataclass ¶

ArrayInfo `dataclass` ¶