yael 1.0.0

Yet another encoding library for QUBOs

YAEL - Yet another encoding library

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

To install this package download the Package from the releases and install via

pip install ./yael-<version>-py-none-any.whl

Alternatively you can install it directly from this repository with:

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

The version in the back can match any release. Using branch names instead of versions can result in unstable versions.

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.

Usage

See the Documentation on gitlab pages.

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]]

# ---------------------------
# 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])]

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.