unitaria 🌈

unitaria is a library for working with so called "block encodings" of matrices and vectors. These are format for performing linear algebra calculations on quantum computers. It allows constructing quantum algorithms using a simple, numpy-like syntax.

>>> import unitaria as ut
>>> import numpy as np
>>> result = ut.Identity(ut.Subspace.from_dim(2)) @ ut.ConstantVector(np.array([3, 4]))
>>> print(result.draw())
Mul
├── Identity{'subspace': Subspace("#")}
└── ConstantVector{'vec': array([3, 4])}
>>> result.toarray().real
array([3., 4.])
>>> result.normalization
np.float64(5.0)
>>> result.circuit()
Circuit(_tq_circuit=circuit: 
GlobalPhase(target=(), control=(), parameter=0.0)
Ry(target=(0,), parameter=1.854590436003224)
, n_qubits=1)

Tutorials

Developer Documentation

Getting started

The best way to install this library is using pip:

pip install unitaria

This might fail if your python installation is to old, see python --version. unitaria requires version 3.12 or higher, see Python versions below. When contributing to unitaria we recommend to use the uv package manager for installing unitaria and managing python versions.

This installs everything needed to work with unitaria, including the simulation backend qulacs. Additional backends compatible with tequila, which is used for communcating with the backends, can also be installed, see tequila.

unitaria aims to be as intuitive as possible. Most operators do exactly what you would expect them to. To construct a tridiagonal matrix, you can, e.g., write

import unitaria as ut
N = 3
inc = ut.Increment(bits=N)
laplace = (2 * ut.Identity(dim=2**N) - inc - inc.adjoint())[:-1, :-1]

If you are not sure how to construct a matrix or vector, you can use the ConstantMatrix or ConstantVector functions.

import unitaria as ut
import numpy as np
v = ut.ConstantVector(np.array([1, 2, 3]))
A = ut.ConstantMatrix(np.array([[1, 2], [3, 4]]))

Note, however, that this will typically not yield efficient quantum circuits.

For a list of all implemented matrices, vectors, and operations check out the documentation. Additional examples are available under /examples.

Contributing

We welcome contributions to unitaria. Check out the Contributing guildlines for details.

Development

To install this library locally, clone this repository and run

pip install --editable .

To run the test suite you can then execute

pytest

To build the documentation, some additional dependencies are required, which can be installed using

pip install --group docs --editable .

Then navigate to the /docs folder and run

rm -r generated
make html

If you get the error locale.Error: unsupported locale setting, try adding the environment variable LC_ALL=C.UTF-8:

LC_ALL=C.UTF-8 make html

Python versions

unitaria requires at least Python version 3.12, and follows Numpy's deprecation policy, i.e. at least Python 3.13 will be required starting April 2027.

Versioning

Unitaria follows SemVer conventions.