comdas.codecs.svd

Truncated Singular Value Decomposition (SVD) codec for 2D arrays.

Classes

SVDCodec([rank, energy])

Truncated-Singular Value Decomposition (SVD) codec for 2D arrays.

SVDPayload(original_shape, dtype, U, s, Vt)

Truncated-SVD representation of a 2D array: A ~= (U * s) @ Vt.
class comdas.codecs.svd.SVDPayload(original_shape, dtype, U, s, Vt)

Bases: CompressedPayload

Truncated-SVD representation of a 2D array: A ~= (U * s) @ Vt.

Variables:

  • U (numpy.ndarray) – Left singular vectors, shape (m, k).

  • s (numpy.ndarray) – Singular values, shape (k,).

  • Vt (numpy.ndarray) – Right singular vectors (transposed), shape (k, n).

property rank: int

The truncation rank k used on this payload.

Return type:

int

property compression_params: dict

The compression parameters used for this payload.

Return type:

dict

class comdas.codecs.svd.SVDCodec(rank=None, energy=None)

Bases: Codec

Truncated-Singular Value Decomposition (SVD) codec for 2D arrays.

This codec compresses a 2D array by computing its truncated singular value decomposition (SVD) and storing the left singular vectors, singular values, and right singular vectors (transposed) as a SVDPayload.

Truncation rank can be chosen either as a fixed integer rank or as a retained energy fraction energy in (0,1]. Exactly one option must be specified, either as a codec-level default or per-call parameter.

SVD does not implement partial writes efficiently, so the full array is re-encoded every 10,000 pending writes (or on demand).

Parameters:

  • rank (int | None) – Default truncation rank k to use if not specified per-call.

  • energy (float | None) – Default retained energy fraction to use if not specified per-call.

Raises:

ValueError – If both of rank and energy are specified.

encode(array, *, rank=None, energy=None, **kwargs)

Compress a 2D array via truncated SVD.

Parameters:

  • array (ndarray) – The dense 2D array to compress.

  • rank (int | None) – Fixed truncation rank. Overrides self.default_rank for this call.

  • energy (float | None) – Retained energy fraction in (0, 1]. Overrides self.default_energy for this call.

  • kwargs – Accepted and ignored for compatibility.

Returns:

The truncated-SVD payload.

Return type:

SVDPayload

Raises:

ValueError – If array is not 2D, or if both rank and energy are specified.

decode(payload)

Fully reconstruct the dense array as (U * s) @ Vt.

Parameters:

payload (SVDPayload) – A payload previously produced by encode().

Returns:

The reconstructed dense array.

Return type:

ndarray

decode_partial(payload, key)

Reconstruct only the requested rows/cols of payload.

Parameters:

  • payload (SVDPayload) – A payload previously produced by encode().

  • key – An int/slice index in the NumPy-style.

Returns:

The requested subset of the reconstructed array.

Return type:

ndarray

compressed_size_bytes(payload)

Get the total number of bytes used by U, s, and Vt.

Parameters:

payload (SVDPayload) – A payload previously produced by encode().

Returns:

Combined byte size of the three stored arrays.

Return type:

int

payload_to_group(payload, group)

Write U, s, Vt, and rank into an open h5py.Group.

Parameters:

  • payload (SVDPayload) – The payload to serialize.

  • group (h5py.Group) – An open, writable h5py.Group dedicated to this one patch.

Return type:

None

payload_from_group(group, *, original_shape, dtype)

Construct an SVDPayload from an HDF5 group.

Parameters:

  • group (h5py.Group) – An open, readable h5py.Group previously written by payload_to_group().

  • original_shape (tuple[int, ...]) – The array shape, as read from the container’s own attributes.

  • dtype (dtype) – The array dtype, as read from the container’s own attributes.

Returns:

The reconstructed payload.

Return type:

SVDPayload