Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readme update: more straight to the point. #343

Merged
merged 2 commits into from
Sep 20, 2023
Merged

Readme update: more straight to the point. #343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
460bdb9
Clean up readme.rst
ValentinS4t1qbit Sep 20, 2023
593417d
Update TUTORIALS.rst
ValentinS4t1qbit Sep 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 36 additions & 99 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,152 +20,92 @@

Welcome !

Tangelo is an open-source and free Python package maintained by `Good Chemistry Company <https://goodchemistry.com>`_, focusing on the development of end-to-end material simulation workflows on quantum computers.
Tangelo is an open-source Python package maintained by `Good Chemistry Company <https://goodchemistry.com>`_, focusing on the development of quantum chemistry simulation workflows on quantum computers. It was developed as an engine to accelerate research, and leverages other popular frameworks to harness the innovation in our field.

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

.. raw:: html

<h3 align="center">
<a href="https://github.com/goodchemistryco/Tangelo-Examples/blob/main/contents.rst" target="_blank"><b>Tutorials</b></a>
&nbsp;&#183;&nbsp;
<a href="http://tangelo-docs.goodchemistry.com" target="_blank"><b>Docs</b></a>
&nbsp;&#183;&nbsp;
<a href="https://goodchemistry.com/blog/" target="_blank"><b>Blog</b></a>
</h3>

-------------

This package provides a growing collection of algorithms and toolboxes, including problem decomposition, to support quantum algorithms R&D 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 publications in scientific journals, co-authored by professionals from the chemical industry and quantum hardware manufacturers.

|workflow|

.. |workflow| image:: ./docs/source/_static/img/quantum_workflow.png
:width: 700
:alt: tangelo_workflow

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 <https://www.nature.com/articles/s42005-021-00751-9>`_
published in scientific journals, co-authored by professionals from the chemical industry and quantum hardware manufacturers.

|curve|

.. |curve| image:: ./docs/source/_static/img/curve_dmet_qcc.png
:width: 400
:alt: curve

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 <https://arxiv.org/abs/2206.12424>`_.
- Our `Sphinx documentation <http://tangelo-docs.goodchemistry.com>`_.
- Our `examples repository <https://github.com/goodchemistryco/Tangelo-Examples>`_.

What will you do with Tangelo ?

-----------------------------

Install
-------

This package requires a Python 3 environment. We recommend:

* using `Python virtual environments <https://docs.python.org/3/tutorial/venv.html>`_ 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.



Using pip
^^^^^^^^^
1. Using pip
^^^^^^^^^^^^

The easiest way to install Tangelo in your local environment. We recommend upgrading pip first:
The easiest way to install Tangelo in your local environment.

.. code-block::

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``)
If you'd like to install via pip the code in a specific branch of this Github repository (let's say ``develop``, which is usually the most advanced):

.. code-block::

pip install git+https://github.com/goodchemistryco/Tangelo.git@develop

From source, using setuptools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2. From source, using setuptools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
After downloading the contents of this repo, you can install Tangelo using the following command, which uses ``setup.py``:

.. code-block::

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.

With Docker
^^^^^^^^^^^

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.

"No install" notebook method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check out the tutorial section below to see how services such as Google Colab, Binder or JupyterLab may help you circumvent local installation challenges or go beyond the compute capabilities of your laptop.

Optional dependencies: Quantum Simulators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Optional dependencies: Quantum Simulators and Classical Quantum Chemistry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 or conda in a straightforward way.


Optional dependencies: Classical Quantum Chemistry Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Tangelo can be used without having a classical quantum chemistry package installed but many algorithms, by default, depend on one being installed. The two quantum chemistry packages that are natively supported are `PySCF <https://pyscf.org/>`_ and `Psi4 <https://psicode.org/>`_.

You are also welcome to provide your own interface to a quantum chemistry package of your choice by defining a subclass of `IntegralSolver <https://github.com/goodchemistryco/Tangelo/blob/develop/tangelo/toolboxes/molecular_computation/integral_solver.py>`_. An example of this can be found in `this test <https://github.com/goodchemistryco/Tangelo/blob/develop/tangelo/toolboxes/molecular_computation/tests/test_molecule.py#L167>`_.


Quick note for Windows users
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Depending on your OS and environment, some of the optional packages may be more challenging to install. If you are using Windows, we recommend you install the `Windows Linux Subsystem <https://docs.microsoft.com/en-us/windows/wsl/install>`_, 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:

.. code-block::

sudo apt update && sudo apt upgrade
sudo apt-get install python3-dev
sudo apt-get install python3-venv
sudo apt-get install cmake unzip
Tangelo enables users to target various backends. In particular, it integrates quantum circuit simulators such as ``qulacs``\ , ``qiskit``\ , ``cirq``, among others. 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 or conda easily.

Tangelo can be used without having a classical quantum chemistry package installed but many chemistry algorithms need one. The two quantum chemistry packages that are natively supported are `PySCF <https://pyscf.org/>`_ and `Psi4 <https://psicode.org/>`_, which can be installed through pip or conda. It is possible to plug in your own `IntegralSolver <https://github.com/goodchemistryco/Tangelo/blob/develop/tangelo/toolboxes/molecular_computation/integral_solver.py>`_ or pre-computed integrals too.

Optional: environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
The bash file ``env_var.sh`` shows a number of environment variables used in Tangelo, for purposes such as computational performance or credentials for quantum experiments.
You can either source this file in your terminal, or set these variables inside your python script / notebooks using the ``os`` package.

Tutorials and examples
----------------------

We have a `dedicated repository <https://github.com/goodchemistryco/Tangelo-Examples>`_ 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 <https://janakiev.com/blog/jupyter-virtual-envs/>`_.

- Install Jupyter and ipykernel in your environment:
.. code-block::

pip install jupyter ipykernel

- To make sure the notebooks allow you to set the kernel corresponding to your virtual environment:
.. code-block::

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.
We have a `dedicated repository <https://github.com/goodchemistryco/Tangelo-Examples>`_ for examples and tutorials ! You can get started with just a few clicks.
Tutorials are organized following a colorful tag system to help people find what is relevant to them. They contain insightful information and advice about chemistry simulations, quantum computing experiments and using Tangelo. Tangelo users can also contribute to this repository and showcase their own work.

Check out our `tutorials <./TUTORIALS.rst>`_ file for more details.

Tests
-----

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):
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 (some tests will fail or be skipped if a dependency is not installed):

.. code-block::

Expand All @@ -178,12 +118,9 @@ Contributions
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 <./CONTRIBUTIONS.rst>`_ 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 <https://github.com/goodchemistryco/Tangelo/issues>`_ to open a bug report or feature request. If you're not sure, starting a discussion in the `Discussion tab <https://github.com/goodchemistryco/Tangelo/discussions>`_ is a good start: we'll figure it out from there.
You can use the `Issue tab <https://github.com/goodchemistryco/Tangelo/issues>`_ to open a bug report or feature request. Starting a discussion in the `Discussion tab <https://github.com/goodchemistryco/Tangelo/discussions>`_ is also 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.
The contribution process is detailed in the `contributions <./CONTRIBUTIONS.rst>`_ file. Don't feel intimidated: we work at the intersection of many difficult fields and we're here to help. By joining the Tangelo community and sharing your ideas and developments, you are creating an opportunity for us to grow together, and take ideas to the finish line and beyond.

Citations
---------
Expand Down
44 changes: 5 additions & 39 deletions TUTORIALS.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,56 +9,22 @@ a great tool to both disseminate knowledge, but also to showcase all the cool st
Working on notebooks is a great way to contribute to this project, and to show everyone something neat you've worked on:
perhaps something that led to a hardware experiment, or implemented an interesting approach.

If you are new to Jupyter notebooks, check out `this page <https://realpython.com/jupyter-notebook-introduction/>`_.
I hope you enjoy it.
If you are new to Jupyter notebooks, check out `this page <https://realpython.com/jupyter-notebook-introduction/>`_. You will learn how to deploy a Jupyter server in your environment and use notebooks.

Quickly deploy a notebook in the cloud
--------------------------------------

Sometimes, you don't want to spend time setting up a local python environment. Maybe it's too cumbersome, or maybe it's
just that your computer's performance is not quite as good as what you'd like. Maybe you simply want to run an existing
notebook and try a few things, right now. Or maybe you intend to run a workshop and you want to avoid any delays
incurred by installation issues experienced by your attendees (the worst). Some cloud providers offer services that can
help with that.


Google Colab
^^^^^^^^^^^^

.. |gcolab| image:: https://colab.research.google.com/assets/colab-badge.svg

`Google Colab <https://research.google.com/colaboratory/faq.html>`_ is a rather straightforward way to achieve the above, as explained on this `webpage <https://colab.research.google.com/github/googlecolab/colabtools/blob/master/notebooks/colab-github-demo.ipynb#scrollTo=K-NVg7RjyeTk>`_.
If you see a |gcolab| badge like this one in a notebook, you can just deploy the notebook on Google Colab by just clicking on it.

Users can read, execute and collaborate through their internet browser. The notebook is hosted and executed on a machine
in the cloud. There are several subscription tiers: the first one is free and may provide you with what you need. The
others can provide you with access to more performant hardware, including GPUs and TPUs, or extra features.

Most of our notebooks are ready to be deployed through Google Colab as-is. A few notebooks require dependencies
that are not publicly available (at the time of writing, QEMIST Cloud is not), or are a bit trickier to install: you may
have to contact us to get access to non-public material.
If you have a Google account (gmail etc) just click the |gcolab| badge on the landing page of our `tutorial repository <https://github.com/goodchemistryco/Tangelo-Examples>`_, or inside any notebook you come across. Notebooks will be launched through your web browser and run on a machine in the cloud.

If you also have access to Google Drive, you can upload your notebooks there and just open then in Google Colab by
double-clicking or right-clicking "open with". To enable this, connect Google Drive to Google Colab by
going to the settings (wheel on top-right of screen), clicking "manage apps" and then searching and installing Colab.
Click here for more information about `Google Colab <https://research.google.com/colaboratory/faq.html>`_.

It is possible that Google Colab is not available in your region of the world. Maybe other cloud providers offer similar
services in your area.

Setting up your environment through an already-deployed notebook
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you have access to an already-deployed notebook in a remote environment you have little control on, you can actually make python run shell commands to modify
the environment in which it runs. We use that trick to check right at the start if Tangelo or the other dependencies
for our notebooks are already installed, and install them for you if not. This is what the cell looks like:
It is possible to install python packages with pip from within an active notebook, by using a `!` to signify a bash command, such as below. Sometimes, you may have to restart the notebook kernel for this change to be taken into account.

.. code-block::

try:
import tangelo
except ModuleNotFoundError:
!pip install git+https://github.com/goodchemistryco/Tangelo.git@develop --quiet

You can use pip to install python packages, but you can run any other shell command: use other package managers for other
software and libraries, download data from somewhere else...
`These examples <https://colab.research.google.com/notebooks/snippets/importing_libraries.ipynb>`_ are not specific to Google Colab.
!pip install git+https://github.com/goodchemistryco/Tangelo.git@develop --quiet