Adding Encodings¶

This guide explains how to add a new quantum encoding to the Quantum Encoding Atlas. Every encoding follows the same structure and integrates with the unified API, analysis tools, and benchmarking framework.

Overview¶

Adding a new encoding involves four steps:

Implement the encoding class
Write documentation for the encoding
Add tests for the encoding
Register the encoding in the package

Step 1: Implement the Encoding¶

Create a new file in src/encoding_atlas/encodings/:

# src/encoding_atlas/encodings/my_encoding.py

from encoding_atlas.core.base import BaseEncoding
from encoding_atlas.core.properties import EncodingProperties


class MyEncoding(BaseEncoding):
    """One-line description of the encoding.

    Longer description explaining the encoding strategy,
    circuit structure, and relevant references.

    Args:
        n_features: Number of classical features to encode.
        reps: Number of circuit repetitions.

    References:
        Author et al., "Paper Title", Journal, Year.
    """

    __slots__ = ('_reps',)  # Required: declare instance attributes

    def __init__(self, n_features: int, reps: int = 1):
        self._reps = reps
        super().__init__(n_features=n_features)

    def _build_circuit(self, x, backend='pennylane'):
        """Build the encoding circuit for input x."""
        ...

    def _compute_properties(self) -> EncodingProperties:
        """Compute encoding properties."""
        ...

Key Requirements¶

Inherit from BaseEncoding
Use __slots__ for all instance attributes
Implement _build_circuit and _compute_properties
Support all three backends: pennylane, qiskit, cirq
Include Google-style docstrings with references

Step 2: Write Documentation¶

Create a documentation page in docs/encodings/<name>/:

docs/encodings/my_encoding/my_encoding.md

Follow the structure of existing encoding pages (see IQP Encoding for the gold standard):

Title and one-line description
Core idea with ASCII diagram
Circuit structure
Mathematics
Key properties table
Example walkthrough
Resource scaling table
Strengths and limitations
Use cases
References

Step 3: Add Tests¶

Create a test file in tests/unit/encodings/:

# tests/unit/encodings/test_my_encoding.py

import pytest
from encoding_atlas.encodings.my_encoding import MyEncoding


class TestMyEncoding:
    def test_basic_creation(self):
        enc = MyEncoding(n_features=4)
        assert enc.n_qubits == 4

    def test_properties(self):
        enc = MyEncoding(n_features=4)
        props = enc.properties
        assert props.gate_count > 0

    def test_circuit_generation(self):
        ...

Ensure tests cover:

Construction with default and custom parameters
Property computation
Circuit generation for each backend
Edge cases (n_features=1, large n_features)

Step 4: Register the Encoding¶

Export from the encodings module:

# src/encoding_atlas/encodings/__init__.py
from .my_encoding import MyEncoding

Export from the top-level package:

# src/encoding_atlas/__init__.py
from .encodings.my_encoding import MyEncoding

Add to the nav in mkdocs.yml:

- My Encoding: encodings/my_encoding/my_encoding.md

Checklist¶

Before submitting a PR for a new encoding: