veloxquant_mlx.artifacts package

Concrete ArtifactStore backends for precomputed quantization artifacts.

Groups the implementations of core.abstractions.ArtifactStore (rotation matrices, codebooks, JL sketch matrices): NpyArtifactStore persists them to .npy files on disk, and InMemoryArtifactStore keeps them in plain dicts for tests and other disk-free use cases.

class veloxquant_mlx.artifacts.InMemoryArtifactStore[source]

Bases: ArtifactStore

In-memory artifact store for testing — performs no disk I/O.

All artifacts are stored in plain Python dicts keyed by descriptor tuples. Rotation and JL matrices are stored as float16 and codebooks as float32 numpy arrays, wrapped in MLX on load.

Parameters:

None.

load_rotation_matrix(d, seed)[source]

Look up a rotation matrix by (d, seed); raises if never saved this run.

Return type:

Any

Parameters:
save_rotation_matrix(Pi, d, seed)[source]

Store Pi (cast to fp16) under (d, seed), silently overwriting any prior entry.

Return type:

None

Parameters:
load_codebook(distribution, b, d)[source]

Look up a codebook by (distribution, b, d); raises if never saved this run.

Return type:

Any

Parameters:
save_codebook(cb, distribution, b, d)[source]

Store cb (as fp32) under (distribution, b, d), silently overwriting any prior entry.

Kept in fp32 so a warm load encodes identically to the cold run (#659).

Return type:

None

Parameters:
load_jl_matrix(d, m, seed)[source]

Look up a JL matrix by (d, m, seed); raises if never saved this run.

Return type:

Any

Parameters:
save_jl_matrix(S, d, m, seed)[source]

Store S (cast to fp16) under (d, m, seed), silently overwriting any prior entry.

Return type:

None

Parameters:
exists(artifact_type, **kwargs)[source]

Check whether a rotation/codebook/JL artifact is already stored.

artifact_type must be one of "rotation", "codebook", or "jl"; kwargs must supply that type’s identifying parameters (e.g. d=/seed= for a rotation). Returns False for an unrecognized artifact_type rather than raising.

Return type:

bool

Parameters:

  • artifact_type (str)

  • kwargs (Any)

class veloxquant_mlx.artifacts.NpyArtifactStore(root_dir)[source]

Bases: ArtifactStore

Artifact store that reads and writes .npy files from a local directory.

File naming conventions:

rotation_d{d}_seed{seed}.npy codebook_{distribution}_b{b}_d{d}.npy jl_d{d}_m{m}_seed{seed}.npy

Parameters:

root_dir (str | Path) – Path to the directory where artifacts are stored. Created automatically on first save if absent.

load_rotation_matrix(d, seed)[source]

Load the rotation matrix at rotation_d{d}_seed{seed}.npy, raising if absent.

Return type:

Any

Parameters:
save_rotation_matrix(Pi, d, seed)[source]

Atomically write Pi (cast to fp16) to rotation_d{d}_seed{seed}.npy, silently overwriting any prior file.

Return type:

None

Parameters:
load_codebook(distribution, b, d)[source]

Load the codebook at codebook_{distribution}_b{b}_d{d}.npy, raising if absent.

Return type:

Any

Parameters:
save_codebook(cb, distribution, b, d)[source]

Atomically write cb (as fp32) to codebook_{distribution}_b{b}_d{d}.npy, silently overwriting any prior file.

Kept in fp32: fp16 rounding of tightly spaced centroids changes the nearest-centroid choice, so a warm store would encode differently from the cold run that computed the codebook (#659).

Return type:

None

Parameters:
load_jl_matrix(d, m, seed)[source]

Load the JL matrix at jl_d{d}_m{m}_seed{seed}.npy, raising if absent.

Return type:

Any

Parameters:
save_jl_matrix(S, d, m, seed)[source]

Atomically write S (cast to fp16) to jl_d{d}_m{m}_seed{seed}.npy, silently overwriting any prior file.

Return type:

None

Parameters:
exists(artifact_type, **kwargs)[source]

Check whether a rotation/codebook/JL artifact file is already on disk.

artifact_type must be one of "rotation", "codebook", or "jl"; kwargs must supply that type’s identifying parameters (e.g. d=/seed= for a rotation). Returns False for an unrecognized artifact_type rather than raising.

Return type:

bool

Parameters:

  • artifact_type (str)

  • kwargs (Any)

Submodules