Ring Module

Symbolic computation with ring elements.

The rings module provides tools for symbolic computations with elements of various mathematical rings. Rings are used in many algorithms for the approximation of z-rotation gates into Clifford+T unitaries.

The module includes the following classes:

• D: Ring of dyadic fractions \(\mathbb{D}\).

• Zsqrt2: Ring of quadratic integers with radicand 2 \(\mathbb{Z}[\sqrt{2}]\).

• Dsqrt2: Ring of quadratic dyadic fractions with radicand 2 \(\mathbb{D}[\sqrt{2}]\).

• Zomega: Ring of cyclotomic integers of degree 8 \(\mathbb{Z}[\omega]\).

• Domega: Ring of cyclotomic dyadic fractions of degree 8 \(\mathbb{D}[\omega]\).

For more information, see [Ross and Selinger, 2014].

class qdecomp.rings.rings.D(num: int, denom: int)

Class to do symbolic computation with elements of the ring of dyadic fractions \(\mathbb{D}\).

The ring element has the form \(a/(2^k)\), where a is an integer and k is a positive integer.

Parameters:

• num (int) – Numerator of the ring element.

• denom (int) – Power of 2 in the denominator of the ring element.

• is_integer (bool) – True if the ring element is an integer.

__init__(num: int, denom: int) → None

Initialize the ring element.

Parameters:

• num (int) – Numerator of the ring element

• denom (int) – Power of 2 in the denominator of the ring element. Must be positive.

Raises:

• TypeError – If the numerator or the denominator exponent are not integers.

• ValueError – If the denominator exponent is negative.

property num: int

Numerator of the dyadic fraction.

property denom: int

Denominator exponent of the dyadic fraction.

property is_integer: bool

Return True if the number is an integer.

mpfloat() → float

Define the mpfloat value of the D class.

class qdecomp.rings.rings.Zsqrt2(a: int, b: int)

Class to do symbolic computation with elements of the ring of quadratic integers with radicand 2 \(\mathbb{Z}[\sqrt{2}]\).

The ring element has the form \(a + b\sqrt{2}\), where a and b are integers.

Parameters:

• a (int) – Integer coefficient of the ring element.

• b (int) – \(\sqrt{2}\) coefficient of the ring element.

__init__(a: int, b: int) → None

Initialize the ring element.

Parameters:

• a (int) – Integer coefficient of the ring element.

• b (int) – \(\sqrt{2}\) coefficient of the ring element.

Raises:

TypeError – If a or b are not integers.

property a: int

Integer coefficient of the ring element.

property b: int

\(\sqrt{2}\) coefficient of the ring element.

property is_integer: bool

Return True if the ring element is an integer.

classmethod from_ring(nb: int | D | Zsqrt2 | Dsqrt2 | Zomega | Domega) → Zsqrt2

Convert a ring element to a Zsqrt2 object. The conversion must be possible.

Parameters:

nb (int | Ring) – Ring element or integer to convert to Zsqrt2.

Returns:

Zsqrt2 object converted from the ring element.

Return type:

Zsqrt2

Raises:

ValueError – If the conversion is not possible.

sqrt2_conjugate() → Zsqrt2

Define the \(\sqrt{2}\)-conjugation operation.

Returns:

\(\sqrt{2}\)-conjugate of the ring element.

Return type:

Zsqrt2

mpfloat() → float

Define the mpfloat value of the Zsqrt2 class.

class qdecomp.rings.rings.Dsqrt2(a: tuple[int, int] | D, b: tuple[int, int] | D)

Class to do symbolic computation with elements of the ring of quadratic dyadic fractions \(\mathbb{D}[\sqrt{2}]\).

The ring element has the form \(a + b\sqrt{2}\), where a and b are dyadic fractions of the form \(m/2^n\), where m is an integer and n is a positive integer. The coefficients are automatically reduced when the class is initialized.

Parameters:

• a (D) – Rational coefficient of the ring element.

• b (D) – \(\sqrt{2}\) coefficient of the ring element.

__init__(a: tuple[int, int] | D, b: tuple[int, int] | D) → None

Initialize the Dsqrt2 class.

Parameters:

• a (tuple[int, int] | D) – Rational coefficient of the ring element.

• b (tuple[int, int] | D) – \(\sqrt{2}\) coefficient of the ring element.

Raises:

• TypeError – If the class arguments are not 2-tuples of integers or D objects.

• ValueError – If the denominator exponent is negative.

property a: D

Rational coefficient of the ring element.

property b: D

\(\sqrt{2}\) coefficient of the ring element.

property is_zomega: bool

Return True if the ring element is in the ring \(\mathbb{Z}[\omega]\).

property is_zsqrt2: bool

Return True if the ring element is in the ring \(\mathbb{Z}[\sqrt{2}]\).

property is_d: bool

Return True if the ring element is in the ring \(\mathbb{D}\).

property is_integer: bool

Return True if the ring element is an integer.

classmethod from_ring(nb: int | D | Zsqrt2 | Dsqrt2 | Zomega | Domega) → Dsqrt2

Convert a ring element to a Dsqrt2 object. The conversion must be possible.

Parameters:

nb (int | Ring) – Ring element or integer to convert to Dsqrt2.

Returns:

Dsqrt2 object converted from the ring element.

Return type:

Dsqrt2

Raises:

ValueError – If the conversion is not possible.

sqrt2_conjugate() → Dsqrt2

Define the \(\sqrt{2}\)-conjugation operation.

Returns:

\(\sqrt{2}\)-conjugate of the ring element.

Return type:

Dsqrt2

mpfloat() → float

Define the mpfloat value of the Dsqrt2 class.

class qdecomp.rings.rings.Zomega(a: int, b: int, c: int, d: int)

Class to do symbolic computation with elements of the ring of cyclotomic integers of degree 8 \(\mathbb{Z}[\omega]\).

The ring element has the form \(a\omega^3 + b\omega^2 + c\omega + d\), where \(\omega = (1 + i)/\sqrt{2}\). The coefficients a, b, c, d are integers.

The ring element can also be expressed as \(\alpha + i\beta\), where \(i = \sqrt{-1}\), and \(\alpha\) and \(\beta\) are numbers in the ring \(\mathbb{D}[\sqrt{2}]\). These numbers are related to the coefficient a, b, c and d through the expressions: \(\alpha = d + (c-a)/2 \sqrt{2}\) and \(\beta = b + (c+a)/2 \sqrt{2}\).

Parameters:

• a (int) – \(\omega^3\) coefficient of the ring element.

• b (int) – \(\omega^2\) coefficient of the ring element.

• c (int) – \(\omega^1\) coefficient of the ring element.

• d (int) – \(\omega^0\) coefficient of the ring element.

__init__(a: int, b: int, c: int, d: int) → None

Initialize the Zomega class.

Parameters:

• a (int) – \(\omega^3\) coefficient of the ring element.

• b (int) – \(\omega^2\) coefficient of the ring element.

• c (int) – \(\omega^1\) coefficient of the ring element.

• d (int) – \(\omega^0\) coefficient of the ring element.

Raises:

TypeError – If the class arguments are not integers.

property a: int

\(\omega^3\) coefficient of the ring element.

property b: int

\(\omega^2\) coefficient of the ring element.

property c: int

\(\omega^1\) coefficient of the ring element.

property d: int

\(\omega^0\) coefficient of the ring element.

property is_dsqrt2: bool

True if the ring element is element of \(\mathbb{D}[\sqrt{2}]\).

property is_zsqrt2: bool

True if the ring element is element of \(\mathbb{Z}[\sqrt{2}]\).

property is_d: bool

True if the ring element is element of \(\mathbb{D}\).

property is_integer: bool

True if the ring element is an integer.

classmethod from_ring(nb: int | complex | D | Zsqrt2 | Dsqrt2 | Zomega | Domega) → Zomega

Convert a ring element to a Zomega object. The conversion must be possible.

Parameters:

nb (int | complex | Ring) – Ring element to convert to Zomega.

Returns:

Zomega object converted from the ring element.

Return type:

Zomega

Raises:

ValueError – If the conversion is not possible.

real() → float

Return the real part of the ring element.

Returns:

Real part of the ring element in float representation.

Return type:

float

mp_real() → float

Return the real part of the ring element in mpfloat representation.

imag() → float

Return the imaginary part of the ring element.

Returns:

Imaginary part of the ring element in float representation.

Return type:

float

mp_imag() → float

Return the imaginary part of the ring element in mpfloat representation.

mpcomplex() → complex

Define the mpcomplex value of the Zomega class.

complex_conjugate() → Zomega

Compute the complex conjugate of the ring element.

Returns:

Complex conjugate of the ring element.

Return type:

Zomega

sqrt2_conjugate() → Zomega

Compute the \(\sqrt{2}\)-conjugate of the ring element.

Returns:

\(\sqrt{2}\)-conjugate of the ring element.

Return type:

Zomega

class qdecomp.rings.rings.Domega(a: tuple[int, int] | D, b: tuple[int, int] | D, c: tuple[int, int] | D, d: tuple[int, int] | D)

Class to do symbolic computation with elements of the ring \(\mathbb{D}[\omega]\).

The ring element has the form \(a\omega^3 + b\omega^2 + c\omega + d\), where \(\omega = (1 + i)/\sqrt{2}\). The coefficients a, b, c, d are dyadic fractions of the form \(m / 2^n\), where m is an integer and n is a positive integer. The coefficients are automatically reduced when the class is initialized.

The ring element can also be expressed as \(\alpha + i\beta\), where \(i = \sqrt{-1}\), and \(\alpha\) and \(\beta\) are numbers in the ring \(\mathbb{D}[\sqrt{2}]\). These numbers are related to the coefficient a, b, c and d through the expressions: \(\alpha = d + (c-a)/2 \sqrt{2}\) and \(\beta = b + (c+a)/2 \sqrt{2}\).

Parameters:

• a (D) – \(\omega^3\) coefficient of the ring element.

• b (D) – \(\omega^2\) coefficient of the ring element.

• c (D) – \(\omega^1\) coefficient of the ring element.

• d (D) – \(\omega^0\) coefficient of the ring element.

__init__(a: tuple[int, int] | D, b: tuple[int, int] | D, c: tuple[int, int] | D, d: tuple[int, int] | D) → None

Initialize the Domega class.

Parameters:

• a (tuple[int, int] | D) – \(\omega^3\) coefficient of the ring element.

• b (tuple[int, int] | D) – \(\omega^2\) coefficient of the ring element.

• c (tuple[int, int] | D) – \(\omega^1\) coefficient of the ring element.

• d (tuple[int, int] | D) – \(\omega^0\) coefficient of the ring element.

Raises:

• TypeError – If the class arguments are not 2-tuples of integers or D objects.

• ValueError – If the denominator exponent is negative.

property a: D

\(\omega^3\) coefficient of the ring element.

property b: D

\(\omega^2\) coefficient of the ring element.

property c: D

\(\omega^1\) coefficient of the ring element.

property d: D

\(\omega^0\) coefficient of the ring element.

property is_zomega: bool

True if the ring element is element of \(\mathbb{Z}[\omega]\).

property is_dsqrt2: bool

True if the ring element is element of \(\mathbb{D}[\sqrt{2}]\).

property is_zsqrt2: bool

True if the ring element is element of \(\mathbb{Z}[\sqrt{2}]\).

property is_d: bool

True if the ring element is element of \(\mathbb{D}\).

property is_integer: bool

True if the ring element is an integer.

classmethod from_ring(nb: int | complex | D | Zsqrt2 | Dsqrt2 | Zomega | Domega) → Domega

Convert a ring element to a Domega object. The conversion must be possible.

Parameters:

nb (int | complex | Ring) – Ring element to convert to Domega.

Returns:

Domega object converted from the ring element.

Return type:

Domega

Raises:

ValueError – If the conversion is not possible.

real() → float

Return the real part of the ring element.

Returns:

Real part of the ring element in float representation.

Return type:

float

mp_real() → float

Return the real part of the ring element in mpfloat representation.

imag() → float

Return the imaginary part of the ring element.

Returns:

Imaginary part of the ring element in float representation.

Return type:

float

mp_imag() → float

Return the imaginary part of the ring element in mpfloat representation.

mpcomplex() → complex

Define the mpcomplex value of the Domega class.

sde() → int | float

Return the smallest denominator exponent (sde) of base \(\sqrt{2}\) of the ring element.

The sde of the ring element \(d \in \mathbb{D}[\omega]\) is the smallest integer value k such that \(d * (\sqrt{2})^k \in \mathbb{Z}[\omega]\).

complex_conjugate() → Domega

Compute the complex conjugate of the ring element.

Returns:

Complex conjugate of the ring element.

Return type:

Domega

sqrt2_conjugate() → Domega

Compute the \(\sqrt{2}\)-conjugate of the ring element.

Returns:

\(\sqrt{2}\)-conjugate of the ring element.

Return type:

Domega

References

[RS14]

N. J. Ross and P. Selinger. Optimal ancilla-free clifford+t approximation of z-rotations. Quantum Information & Computation, 2014. URL: https://arxiv.org/abs/1403.2975.