-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
8f6b401
commit 71f08e5
Showing
1 changed file
with
36 additions
and
89 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,116 +1,63 @@ | ||
| # Template Python project | ||
| # Qadence-Libs | ||
|
|
||
| This is a template Python project which can be used to bootstrap a new library in the Pasqal quantum software codebase. | ||
| **Qadence-Libs** is a Python package that provides extra functionality for Qadence. | ||
|
|
||
| ## Development tools | ||
| [](https://github.com/pasqal-io/qadence-libs/actions/workflows/lint.yml) | ||
| [](https://github.com/pasqal-io/qadence-libs/actions/workflows/test.yml) | ||
| [](https://pasqal-io.github.io/qadence-libs/latest) | ||
| [](https://pypi.org/project/qadence-libs/) | ||
| [](https://opensource.org/licenses/Apache-2.0) | ||
|
|
||
| The library uses the following tools: | ||
|
|
||
| * [hatch](https://hatch.pypa.io/latest/) for managing virtual environment and dependencies | ||
| * [pytest](https://docs.pytest.org/en/7.2.x/contents.html) for building the unit tests suite | ||
| * [black](https://black.readthedocs.io/en/stable/), [isort](https://pycqa.github.io/isort/) and [flake8](https://flake8.pycqa.org/en/latest/) for code formatting and linting | ||
| * [mypy](https://mypy.readthedocs.io/en/stable/) for static type checking | ||
| * [pre-commit](https://pre-commit.com/) for applying linting and formatting automatically before committing new code | ||
| ## Installation guide | ||
|
|
||
| We recommend to use [`pyenv`](https://github.com/pyenv/pyenv) for managing | ||
| python versions for managing python versions both globally and locally: | ||
| ```bash | ||
| # System-wide install of a python version. | ||
| pyenv install 3.10 | ||
|
|
||
| # Use 3.10 everywhere. | ||
| pyenv global 3.10 | ||
|
|
||
| # Or locally in the current directory. | ||
| pyenv local 3.10 | ||
| ``` | ||
|
|
||
|
|
||
| ## Install from registry | ||
|
|
||
| Before you can install the library from the private Pasqal PyPi, make sure to ask for `PYPI_USERNAME` and `PYPI_PASSWORD` on the relevant Slack channel. | ||
| You can then set the credentials as environment variables via: | ||
| [PyPI](https://pypi.org/project/qadence-libs/) and can be installed using `pip` as follows: | ||
|
|
||
| ```bash | ||
| export PYPI_USERNAME=MYUSERNAME | ||
| export PYPI_PASSWORD=THEPASSWORD | ||
| ``` | ||
|
|
||
| You are then able to install the latest version of `template-python-project` from the Pasqal private PyPi. | ||
|
|
||
|
|
||
| ## Install from source | ||
|
|
||
| All Pasqal quantum libraries require Python >=3.8. For development, the preferred method to install this package is | ||
| to use `hatch`. You can install from source by cloning this repository and run: | ||
|
|
||
| ```bash | ||
| python -m pip install hatch | ||
| python -m hatch -v shell | ||
|
|
||
| # execute any script using the library | ||
| python my_script.py | ||
| pip install qadence_libs | ||
| ``` | ||
|
|
||
| Alternatively, you can also: | ||
| ## Contributing | ||
|
|
||
| * install with `pip` in development mode by simply running `pip install -e .`. Notice that in this way | ||
| you will install all the dependencies, including extras. | ||
| * install it with `conda` by simply using `pip` inside the Conda environment. | ||
| Before making a contribution, please review our [code of conduct](docs/CODE_OF_CONDUCT.md). | ||
|
|
||
| - **Submitting Issues:** To submit bug reports or feature requests, please use our [issue tracker](https://github.com/pasqal-io/qadence-libs/issues). | ||
| - **Developing in qadence:** To learn more about how to develop within `qadence`, please refer to [contributing guidelines](docs/CONTRIBUTING.md). | ||
|
|
||
| ## Develop | ||
| ### Setting up qadence in development mode | ||
|
|
||
| When developing the package, the recommended way is to create a virtual environment with `hatch` as shown above: | ||
| We recommend to use the [`hatch`](https://hatch.pypa.io/latest/) environment manager to install `qadence_libs` from source: | ||
|
|
||
| ```bash | ||
| python -m pip install hatch | ||
| python -m hatch -v shell | ||
| ``` | ||
|
|
||
| When inside the shell with development dependencies, install first the pre-commit hook: | ||
| ``` | ||
| pre-commit install | ||
| ``` | ||
| # get into a shell with all the dependencies | ||
| python -m hatch shell | ||
|
|
||
| In this way, you will get automatic linting and formatting every time you commit new code. Do not | ||
| forget to run the unit test suite by simply running the `pytest` command. | ||
| # run a command within the virtual environment with all the dependencies | ||
| python -m hatch run python my_script.py | ||
| ``` | ||
|
|
||
| If you do not want to get into the Hatch shell, you can alternatively do the following: | ||
| **WARNING** | ||
| `hatch` will not combine nicely with other environment managers such as Conda. If you still want to use Conda, | ||
| install it from source using `pip`: | ||
|
|
||
| ```bash | ||
| python -m pip install hatch | ||
| python -m hatch -v shell | ||
|
|
||
| # install the pre-commit | ||
| python -m hatch run pre-commit install | ||
|
|
||
| # commit some code | ||
| python -m hatch run git commit -m "My awesome commit" | ||
|
|
||
| # run the unit tests suite | ||
| python -m hatch run pytest | ||
|
|
||
| # within the Conda environment | ||
| python -m pip install -e . | ||
| ``` | ||
|
|
||
| ## Document | ||
| ## Citation | ||
|
|
||
| You can improve the documentation of the package by editing this file for the landing page or adding new | ||
| markdown or Jupyter notebooks to the `docs/` folder in the root of the project. In order to modify the | ||
| table of contents, edit the `mkdocs.yml` file in the root of the project. | ||
| If you use Qadence-Libs for a publication, we kindly ask you to cite our work using the following BibTex entry: | ||
|
|
||
| In order to build and serve the documentation locally, you can use `hatch` with the right environment: | ||
|
|
||
| ```bash | ||
| python -m hatch -v run docs:build | ||
| python -m hatch -v run docs:serve | ||
| ```latex | ||
| @misc{qadence-libs2024pasqal, | ||
| url = {https://github.com/pasqal-io/qadence-libs}, | ||
| title = {Qadence Libs: {A}n {E}xperiment runner for Qadence.}, | ||
| year = {2023} | ||
| } | ||
| ``` | ||
|
|
||
| If you don't want to use `hatch`, just check into your favorite virtual environment and | ||
| execute the following commands: | ||
|
|
||
| ```bash | ||
| python -m pip install -r docs/requirements.txt | ||
| mkdocs build | ||
| mkdocs serve | ||
| ``` | ||
| ## License | ||
| Qadence-Libs is a free and open source software package, released under the Apache License, Version 2.0. |