quast_decisiontree.algorithms.mixers

quast_decisiontree.algorithms.mixers

Qrisp-compatible QAOA mixer definitions and registry.

Overview

A mixer is a callable with signature::

def mixer(qv: QuantumVariable, beta: float) -> None

It applies a parameterized unitary exp(-i · beta · H_mixer) to the quantum variable qv in-place. Qrisp's QAOAProblem calls it once per QAOA layer.

Registering Custom Mixers

To add your own mixer, create a Python module and call :func:register_mixer at module level:

.. code-block:: python

# File: my_project/custom_mixers.py

from quast_decisiontree.algorithms.mixers import register_mixer


def _build_my_mixer(**kwargs):
    # Factory that returns a mixer callable.
    # Receives **kwargs from the framework (currently: num_qubits).
    # Must return a function with signature mixer(qv, beta).
    from qrisp import rz

    def my_mixer(qv, beta):
        for i in range(len(qv)):
            rz(2 * beta, qv[i])

    return my_mixer


register_mixer(
    name="MyCustom",
    description="My custom mixer applying RZ rotations to all qubits",
    factory=_build_my_mixer,
)

Then reference the module in the YAML config:

.. code-block:: yaml

QrispMixerNode:
  children: ["SelectOptimizerNode"]
  mixer_modules:
    - "my_project.custom_mixers"

The module is imported at node construction time. Multiple modules can be listed; they are loaded in order, and later registrations overwrite earlier ones with the same name (a warning is logged).

Factory Contract

A factory callable must:

1. Accept arbitrary **kwargs (forward-compatible with future arguments).
2. Return a callable with signature mixer(qv, beta) -> None.
3. Perform Qrisp imports inside the factory body (not at module level), so that registration and discovery work without triggering heavy imports.

The num_qubits kwarg may be None when the framework queries the registry for descriptions (before a problem is loaded). Factories that need num_qubits at build time should raise a clear error if it is None.

logger module-attribute

logger = logging.getLogger('dt_logger')

MixerFactory module-attribute

MixerFactory = Callable[..., Callable]

MIXER_REGISTRY module-attribute

MIXER_REGISTRY = {}

register_mixer

register_mixer(name, description, factory)

Register a mixer factory in the global registry.

Parameters

name : str User-facing name (used in YAML configs and interactive queries). description : str One-line description shown during mixer selection. factory : callable A callable(**kwargs) that returns a mixer function mixer(qv, beta). See module docstring for the full contract.

Source code in src/quast_decisiontree/algorithms/mixers.py

def register_mixer(name: str, description: str, factory: MixerFactory) -> None:
    """Register a mixer factory in the global registry.

    Parameters
    ----------
    name : str
        User-facing name (used in YAML configs and interactive queries).
    description : str
        One-line description shown during mixer selection.
    factory : callable
        A callable(**kwargs) that returns a mixer function ``mixer(qv, beta)``.
        See module docstring for the full contract.
    """
    if name in MIXER_REGISTRY:
        logger.warning("Overwriting existing mixer '%s' in registry.", name)
    MIXER_REGISTRY[name] = {
        "description": description,
        "factory": factory,
    }

get_mixer

get_mixer(name, **kwargs)

Retrieve and build a mixer by name.

Parameters

name : str Registered mixer name. **kwargs Passed to the factory (e.g., num_qubits).

Returns

callable A mixer function with signature mixer(qv, beta).

Raises

ValueError If the name is not found in the registry.

Source code in src/quast_decisiontree/algorithms/mixers.py

def get_mixer(name: str, **kwargs) -> Callable:
    """Retrieve and build a mixer by name.

    Parameters
    ----------
    name : str
        Registered mixer name.
    **kwargs
        Passed to the factory (e.g., num_qubits).

    Returns
    -------
    callable
        A mixer function with signature ``mixer(qv, beta)``.

    Raises
    ------
    ValueError
        If the name is not found in the registry.
    """
    if name not in MIXER_REGISTRY:
        available = ", ".join(sorted(MIXER_REGISTRY.keys()))
        raise ValueError(f"Unknown mixer {name!r}. Available: {available}")
    return MIXER_REGISTRY[name]["factory"](**kwargs)

get_registry_descriptions

get_registry_descriptions()

Return {name: description} for all registered mixers.

Source code in src/quast_decisiontree/algorithms/mixers.py

def get_registry_descriptions() -> dict[str, str]:
    """Return {name: description} for all registered mixers."""
    return {name: entry["description"] for name, entry in MIXER_REGISTRY.items()}

load_mixer_modules

load_mixer_modules(module_paths)

Import one or more modules so they can register additional mixers.

Each module is expected to call :func:register_mixer at import time.

Parameters

module_paths : sequence of str Fully qualified Python module paths (e.g., ["my_project.custom_mixers", "another_pkg.special_mixers"]).

Raises

ImportError If any module cannot be imported.

Source code in src/quast_decisiontree/algorithms/mixers.py

def load_mixer_modules(module_paths: Sequence[str]) -> None:
    """Import one or more modules so they can register additional mixers.

    Each module is expected to call :func:`register_mixer` at import time.

    Parameters
    ----------
    module_paths : sequence of str
        Fully qualified Python module paths
        (e.g., ``["my_project.custom_mixers", "another_pkg.special_mixers"]``).

    Raises
    ------
    ImportError
        If any module cannot be imported.
    """
    import importlib

    for module_path in module_paths:
        logger.info("Loading external mixer module: %s", module_path)
        importlib.import_module(module_path)