Welcome !
Tangelo is an open-source and free Python package maintained by Good Chemistry Company, focusing on the development of end-to-end material simulation workflows on quantum computers.
Tackling chemical systems with quantum computing is not easy. Leveraging pre- and post-processing techniques as well as insights from classical calculations remain necessary, in order to make non-trivial use cases computationally tractable, and develop efficient approaches returning accurate results on simulators or quantum devices. Assembling the different building blocks to form and explore workflows that meet these constraints is where Tangelo strives to be of help.
This package provides a growing collection of algorithms and toolboxes, including problem decomposition, to support the development of new approaches and the design of successful experiments on quantum devices. Tangelo is backend-agnostic, so that users can write code once and experiment with current and future platforms with minimal changes.
Tangelo is capable to perform quantum experiments that led to peer-reviewed work published in scientific journals, co-authored by professionals from the chemical industry and quantum hardware manufacturers.
We hope to grow a healthy community around Tangelo, collaborate, and together leverage the best of what the field has to offer.
- Our release document on arXiv.
- Our Sphinx documentation.
- Our examples repository.
What will you do with Tangelo ?
This package requires a Python 3 environment. We recommend:
- using Python virtual environments in order to set up your environment safely and cleanly
- installing the "dev" version of Python3 if you encounter missing header errors, such as
python.h file not found. - having good C/C++ compilers and BLAS libraries to ensure good overall performance of computation-intensive code.
The easiest way to install Tangelo in your local environment. We recommend upgrading pip first:
python -m pip install --upgrade pip. pip install tangelo-gc
If you'd like to install via pip the code in a specific branch of this Github repository (let's say develop)
pip install git+https://github.com/goodchemistryco/Tangelo.git@develop
This package can be installed locally by copying the contents of this repository to any machine. This can be useful if you need a bit more control on your install (such as installing from a particular branch, or tweaking the setup.py install to circumvent any issue on your system).
Type the following command in the root directory:
python -m pip install .
If the installation of a dependency fails and the reason is not obvious, we suggest installing that dependency
separately with pip, before trying again.
Use our Docker file to deploy Tangelo in a Linux environment, either retrieved from pip or mounted locally. Comment / uncomment the relevant sections of the Dockerfile to control installation and dependencies.
A good alternative for users that simply want to quickly get a working environment ready, especially for quick tests, demos, tutorials. Check out the tutorial section below to see how services such as Google Colab may help you circumvent local installation challenges or go beyond the limitations of your personal computer if you feel short of compute power or memory.
Tangelo enables users to target various backends. In particular, it integrates quantum circuit simulators such as
qulacs, qiskit, cirq or qdk. We leave it to you to install the packages of your choice, and refer to their own documentation.
Most packages can be installed through pip in a straightforward way:
pip install qulacs pip install qiskit pip install cirq ...
Depending on your OS and environment, some of these packages may be more challenging to install. For installing Microsoft's QDK or any issue regarding the above packages, please check their respective documentation.
Our installation instructions will work on Linux and MacOS systems. If you are using Windows, we recommend
you install the Windows Linux Subsystem, which allows you
to run Ubuntu as an application. Once it has been installed, you can type explorer.exe in your Ubuntu terminal to
drag and drop files between your Windows and Linux environment.
Here are a few essentials to install inside a brand new Ubuntu environment, before trying to install Tangelo:
sudo apt update && sudo apt upgrade sudo apt-get install python3-dev sudo apt-get install python3-venv sudo apt-get install cmake unzip
Some environment variables can impact performance (ex: using GPU for quantum circuit simulation, or changing the number of CPU threads used) or are used to connect to web services providing access to some compute backends.
See the list of relevant environment variables and their use in env_var.sh. In order for these variables to be set to
the desired values in your environment, you can run this shell script in Linux with the following command line:
source env_var.sh (you may need to set execution permissions with chmod +x set_env_var.sh first), or you can set
them in whatever way your OS supports it, or even inside your python script using the os package.
We have a dedicated repository for examples and tutorials !
We wrote a number of them, and tried to provide material that doesn't just explain how to use the software, but provides insights into the complex topics of chemistry, quantum computing, and digs into the challenges we encountered in our previous hardware experiments. Nothing prevents users from contributing and showcasing what they have been doing with Tangelo.
You can visualize notebooks directly on Github, most of them have been pre-run. If you'd like to be able to run them locally, we suggest you use Jupyter notebooks inside a virtual environment.
- Install Jupyter and ipykernel in your environment:
pip install jupyter ipykernel
- To make sure the notebooks allow you to set the kernel corresponding to your virtual environment:
python -m ipykernel install --user --name=myenv
Jupyter notebooks can also be displayed and executed in the cloud, with services such as Google Colab. This removes the constraint of building a local development envrionement, and enables users to run interactive notebooks on machines that may provide a better configuration than their own (more RAM, compute power, access to GPUs...). This may come in handy for users who want to get started quickly, especially for quick tests, demos and tutorials.
Check out our tutorials file for more details.
Unit tests can be found in the tests folders, located in the various toolboxes they are related to. To automatically
find and run all tests (assuming you are in the tangelo subfolder that contains the code of the package):
python -m unittest
Thank you very much for considering contributing to this project; we'd love to have you on board ! You do not need to be a seasoned software developer or expert in your field to make contributions to this project: it will take various kinds of people and backgrounds to tackle the challenges that await us.
However we need some guidelines and processes to ensure that we build something of quality for the community. We describe them in the contributions file. There are many ways you can contribute, but in case you're considering contributing to the codebase: don't be scared of the infamous pull request process ! It can feel intimidating, but we've had a few researchers or high-schoolers go through their first one and... they came back for more ! Mostly.
You can use the Issue tab to open a bug report or feature request. If you're not sure, starting a discussion in the Discussion tab is a good start: we'll figure it out from there.
By joining the Tangelo community and sharing your ideas and developments, you are creating an opportunity for us to learn and grow together, and take ideas to the finish line and beyond.
If you use Tangelo in your research, please cite:
Valentin Senicourt, James Brown, Alexandre Fleury, Ryan Day, Erika Lloyd, Marc P. Coons, Krzysztof Bieniasz, Lee Huntington, Alejandro J. Garza, Shunji Matsuura, Rudi Plesch, Takeshi Yamazaki, and Arman Zaribafiyan Tangelo: An Open-source Python Package for End-to-end Chemistry Workflows on Quantum Computers 2022 arXiv:2206.12424
© Good Chemistry Company 2023. This software is released under the Apache Software License version 2.0.