# helia_edge.layers.residual_vector_quantizer

## helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer

`class` · `python`

```python
ResidualVectorQuantizer(
    num_levels: int,
    num_embeddings: int | Sequence[int],
    embedding_dim: int,
    beta: float = 0.25,
    **kwargs={},
)
```

Residual Vector Quantizer (RVQ) with straight-through estimator.

Input:  [..., D]  (last dim = embedding_dim)
Output: [..., D]  (sum of per-level dequantized vectors; gradients pass through x)

Metrics (logged via `metrics` property):
  - rvq_l{l}_perplexity, rvq_l{l}_usage, rvq_l{l}_bits_per_index
  - rvq_perplexity_mean, rvq_usage_mean, rvq_bits_per_index_sum (entropy lower bound)

:::note[Losses added per level]
- beta * ||stop(q_l) - r_l||^2  +  ||q_l - stop(r_l)||^2,
  where r_l is the current residual and q_l the level-l code vector.

:::

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| num_levels | int | Required | int, number of residual VQ stages (M >= 1) |
| num_embeddings | int \| Sequence[int] | Required | int OR sequence[int], codebook size K for each level |
| embedding_dim | int | Required | int, latent dimensionality D |
| beta | float | 0.25 | float, commitment coefficient per level |

Source: `helia_edge/layers/residual_vector_quantizer.py:8`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.M

`constant` · `python`

```python
M = int(num_levels)
```

Source: `helia_edge/layers/residual_vector_quantizer.py:42`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.D

`constant` · `python`

```python
D = int(embedding_dim)
```

Source: `helia_edge/layers/residual_vector_quantizer.py:43`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.Ks

`attribute` · `python`

```python
Ks
```

Source: `helia_edge/layers/residual_vector_quantizer.py:48`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.beta

`attribute` · `python`

```python
beta = float(beta)
```

Source: `helia_edge/layers/residual_vector_quantizer.py:51`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.metrics

`attribute` · `python`

```python
metrics
```

Source: `helia_edge/layers/residual_vector_quantizer.py:159`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.build

`method` · `python`

```python
build(input_shape)
```

Source: `helia_edge/layers/residual_vector_quantizer.py:64`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.call

`method` · `python`

```python
call(
    x: keras.KerasTensor,
    return_indices: bool = False,
) -> keras.KerasTensor | tuple[keras.KerasTensor, list[keras.KerasTensor]]
```

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| x | keras.KerasTensor | Required | [..., D] latent to be quantized. |
| return_indices | bool | False | if True, also returns list of flat indices (one tensor per level). |

**Returns**

| Name | Type | Description |
| --- | --- | --- |
|  | keras.KerasTensor \| tuple[keras.KerasTensor, list[keras.KerasTensor]] | y or (y, indices_list): dequantized vector and optional per-level indices. |

Source: `helia_edge/layers/residual_vector_quantizer.py:93`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.encode

`method` · `python`

```python
encode(x)
```

Return list of per-level flat index tensors [N] (no gradients).

Source: `helia_edge/layers/residual_vector_quantizer.py:164`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.decode

`method` · `python`

```python
decode(indices_list, original_shape)
```

Sum per-level code vectors from indices_list and reshape to original_shape.

Source: `helia_edge/layers/residual_vector_quantizer.py:176`

### helia_edge.layers.residual_vector_quantizer.ResidualVectorQuantizer.get_config

`method` · `python`

```python
get_config()
```

Source: `helia_edge/layers/residual_vector_quantizer.py:185`