YAEL - Yet another encoding library

Links

Documentation: https://gawehn1.pages.jsc.fz-juelich.de/yael
Code: https://gitlab.jsc.fz-juelich.de/gawehn1/yael

Description

Yael is designed to make it easier to encode quadratic unconstrained optimization problems into QUBOs. It therefore provides different encodings to map integers to binary representations as well as different transformations to be able to represent continuous values.

Install

Install via pip:

pip install yael

To get the latest unpublished version:

pip install git+https://gitlab.jsc.fz-juelich.de/gawehn1/yael.git@main

Provided encodings

• yael.encoding.Exponential: The standard unsigned integer representation
• yael.encoding.OneHot: The index of the one is the value
• yael.encoding.BoundedCoefficient: Bounded Coefficient Encoding
• yael.encoding.DomainWall: Domain Wall Encoding

Additionally it contains the following transformations:

• yael.transformation.Linear: Linear Transformation

The following encodings were constructed by combining the above encodings and transformations:

• yael.encoding.Interval: OneHot rescaled to an interval
• yael.encoding.Binary: Alias for Exponential with base 2
• yael.encoding.Unary: Unary Encoding is equavalent to BoundedCoefficient with max coefficient = 1

All methods shared by the encodings can be found in the base class yael.encoding.Encoding.

Example

This example gives a quick overview over the functionality of YAEL. For a detailed description refer to the documentation.

from yael.encoding import Exponential
from yael.transformation import Linear
import numpy as np

# ---------------------------
# Create Encoding
# ---------------------------
enc = Exponential(precision=2, base=2)

# ---------------------------
# Explore encoding
# ---------------------------
# get all values that can be represented by the encoding
print(enc.get_possible_values())
# [array([0, 1, 2, 3])]

# get the closest value the encoding can represent
print(enc.get_closest_values(1.8))
# 2.0

# get the bit representation of the closest representable value
# (least significant bit first)
print(enc.quantize(2))
# [0 1]
print(enc.quantize(1.8))
# [0 1]

# ---------------------------
# Encode into QUBOs
# ---------------------------

# problem specific coefficients correspond to:
# v_0^2 + v_0 v_2 + 2 v_1^2 + 4 v_1 v_2 + 5 v_2^2 + 6 v_0 + 7 v_1 + 8 v_2
quadratic = np.array(
    [
        [1, 0, 3],
        [0, 2, 4],
        [0, 0, 5],
    ]
)

linear = np.array([6, 7, 8])

# penalty is not used for Exponential encoding but for encodings with constraints
qubo, offset = enc.encode(quadratic, linear, penalty=1.0)

print(qubo)
# [[ 7.  4.  0.  0.  3.  6.]
#  [ 0. 16.  0.  0.  6. 12.]
#  [ 0.  0.  9.  8.  4.  8.]
#  [ 0.  0.  0. 22.  8. 16.]
#  [ 0.  0.  0.  0. 13. 20.]
#  [ 0.  0.  0.  0.  0. 36.]]

# ---------------------------
# Validate and decode
# ---------------------------
# least significant bit first (congruent across encodings)
bitstrings = np.array(["0110", "0010"])
print(enc.are_valid(bitstrings))
# [ True True ]
print(enc.decode(bitstrings))
# [[2 1]
#  [0 1]]

# print separated per value
print(enc.format_bits("000111"))
# "000 111"

# ---------------------------
# Transformations
# ---------------------------
inner_enc = Exponential(precision=3, base=2)
# apply a transformation:
enc = Linear(inner_enc, A=-1, B=1, endpoint=False)
print(enc.get_possible_values())
# [array([-1.  , -0.75, -0.5 , -0.25,  0.  ,  0.25,  0.5 ,  0.75])]

Citing

If you use this library, please cite it:

@misc{gawehn2026yael,
  author       = {Carina Gawehn},
  title        = {{YAEL: Yet Another Encoding Library for QUBOs}},
  year         = {2026},
  howpublished = {\url{https://pypi.org/project/yael/}},
  note         = {Version 1.1.0. Documentation and source code: https://gitlab.jsc.fz-juelich.de/gawehn1/yael}
}

Contributing

Clone this Repo and install the package as editable with the dev extra dependencies:

pip install -e .[dev]

The project contains a CI/CD Pipeline. Please Make sure that the steps work on your machine before creating a Merge Request. The steps are in the Makefile:

• test
• format
• build
• docs

You can run them all with: make dev

You can also create a coverage report with make coverage. The merge request will show that as well.

License

This repository is licensed under the Apache License, Version 2.0. A copy of the license is provided in LICENSE.