Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
91 changes: 29 additions & 62 deletions .github/README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
# Q-CTRL Open Controls

Q-CTRL Open Controls is an open-source Python package that makes it easy to
create and deploy established error-robust quantum control protocols from the
open literature. The aim of the package is to be the most comprehensive library
of published and tested quantum control techniques developed by the community,
with easy to use export functions allowing users to deploy these controls on:
Q-CTRL Open Controls is an open-source Python package that makes it easy to create and deploy established error-robust quantum control protocols from the open literature. The aim of the package is to be the most comprehensive library of published and tested quantum control techniques developed by the community, with easy to use export functions allowing users to deploy these controls on:

- Custom quantum hardware
- Publicly available cloud quantum computers
Expand All @@ -14,23 +10,13 @@ Anyone interested in quantum control is welcome to contribute to this project.

## Installation

Q-CTRL Open Controls can be installed through `pip` or from source. We recommend
the `pip` distribution to get the most recent stable release. If you want the
latest features, then install from source.
Q-CTRL Open Controls can be installed through `pip` or from source. We recommend the `pip` distribution to get the most recent stable release. If you want the latest features, then install from source.

### Requirements

To use Q-CTRL Open Controls you will need an installation of Python (>=3.8, <3.12).
We recommend using the [Anaconda](https://www.anaconda.com/) distribution of
Python. Anaconda includes standard numerical and scientific Python packages
which are optimally compiled for your machine. Follow the [Anaconda
Installation](https://docs.anaconda.com/anaconda/install/) instructions and
consult the [Anaconda User
guide](https://docs.anaconda.com/anaconda/user-guide/) to get started.
To use Q-CTRL Open Controls you will need an installation of Python (>=3.8, <3.12). We recommend using the [Anaconda](https://www.anaconda.com/) distribution of Python. Anaconda includes standard numerical and scientific Python packages which are optimally compiled for your machine. Follow the [Anaconda Installation](https://docs.anaconda.com/anaconda/install/) instructions and consult the [Anaconda User guide](https://docs.anaconda.com/anaconda/user-guide/) to get started.

We use interactive jupyter notebooks for our usage examples. The Anaconda
python distribution comes with editors for these files, or you can [install the
jupyter notebook editor](https://jupyter.org/install) on its own.
We use interactive jupyter notebooks for our usage examples. The Anaconda python distribution comes with editors for these files, or you can [install the jupyter notebook editor](https://jupyter.org/install) on its own.

### Using PyPi

Expand All @@ -40,11 +26,9 @@ Use `pip` to install the latest version of Q-CTRL Open Controls.
pip install qctrl-open-controls
```

### From Source
### From source

The source code is hosted on
[GitHub](https://github.com/qctrl/open-controls). The repository can be
cloned using
The source code is hosted on [GitHub](https://github.com/qctrl/open-controls). The repository can be cloned using

```shell
git clone [email protected]:qctrl/open-controls.git
Expand All @@ -54,9 +38,7 @@ Once the clone is complete, you have two options:

1. Using Poetry

Follow the instructions from the
[Poetry documentation](https://python-poetry.org/docs/#installation) to
install Poetry.
Follow the instructions from the [Poetry documentation](https://python-poetry.org/docs/#installation) to install Poetry.

After you have installed Poetry, use:

Expand All @@ -75,61 +57,56 @@ Once the clone is complete, you have two options:
rm requirements.txt
```

Once installed via one of the above methods, test your installation by running
`pytest` in the `open-controls` directory.
Once installed via one of the above methods, test your installation by running `pytest` in the `open-controls` directory.

```shell
pytest
```

## Usage

See the [Jupyter notebooks examples](../examples) and the
[Q-CTRL Open Controls reference documentation](https://docs.q-ctrl.com/open-controls/references/qctrl-open-controls/).
See the [Jupyter notebooks examples](../examples) and the [Q-CTRL Open Controls reference documentation](https://docs.q-ctrl.com/open-controls/references/qctrl-open-controls/).

## Contributing

For general guidelines, see [Contributing](https://code.q-ctrl.com/contributing).

### Building documentation

Documentation generation relies on [Sphinx](http://www.sphinx-doc.org).
The reference documentation for the latest released version of
Q-CTRL Open Controls is hosted online in the
[Q-CTRL documentation website](https://docs.q-ctrl.com/open-controls/references/qctrl-open-controls/).
Documentation generation relies on [Sphinx](http://www.sphinx-doc.org). The reference documentation for the latest released version of Q-CTRL Open Controls is hosted online in the [Q-CTRL documentation website](https://docs.q-ctrl.com/open-controls/references/qctrl-open-controls/).

To build it locally:

1. Ensure you have used one of the install options above.
1. Execute the make file from the docs directory:

If using Poetry:
If using Poetry:

```bash
cd docs
poetry run make html
```
```bash
cd docs
poetry run make html
```

If using pip:
If using pip:

```bash
cd docs
# Activate your virtual environment if required
make html
```
```bash
cd docs
# Activate your virtual environment if required
make html
```

The generated HTML will appear in the `docs/_build/html` directory.

### Formatting, linting, and static analysis

Code is formatted, linted and checked using the following tools:

- [Black](https://github.com/psf/black)
- [Pylint](https://pypi.org/project/pylint/)
- [isort](https://github.com/timothycrosley/isort)
- [mypy](http://mypy-lang.org/)

These checks are run on all code merged to master, and may also be run locally from the open-controls
directory:
These checks are run on all code merged to master, and may also be run locally from the open-controls directory:

```shell
pip install black isort mypy pylint
Expand All @@ -139,39 +116,29 @@ black --check .
pylint .
```

Note that you can speed up the execution of Pylint by running it in the parallel mode with the `-j`
option: `pylint -j 0 .`.
See the [official documentation](https://pylint.readthedocs.io/en/latest/user_guide/usage/run.html#parallel-execution)
for details.
Note that you can speed up the execution of Pylint by running it in the parallel mode with the `-j` option: `pylint -j 0 .`. See the [official documentation](https://pylint.readthedocs.io/en/latest/user_guide/usage/run.html#parallel-execution) for details.

Black and isort, in addition to checking code, can also automatically apply fixes. To fix all code
in the open-controls tree, run:
Black and isort, in addition to checking code, can also automatically apply fixes. To fix all code in the open-controls tree, run:

```shell
isort
black .
```

You can also run these checks only in the files that you changed by using the
`pre-commit` tool. To use it, run:
You can also run these checks only in the files that you changed by using the `pre-commit` tool. To use it, run:

```shell
pip install pre-commit
pre-commit install
```

With this, the checks will run every time that you commit code with
`git commit`. If you prefer to run the checks every time that you push changes
instead of when you commit changes, use `pre-commit install -t pre-push`.
With this, the checks will run every time that you commit code with `git commit`. If you prefer to run the checks every time that you push changes instead of when you commit changes, use `pre-commit install -t pre-push`.

If you no longer wish to use `pre-commit`, you can uninstall it by running
`pre-commit uninstall` in the `open-controls` directory (or by running
`pre-commit uninstall -t pre-push`, if you used the pre-push hooks).
If you no longer wish to use `pre-commit`, you can uninstall it by running `pre-commit uninstall` in the `open-controls` directory (or by running `pre-commit uninstall -t pre-push`, if you used the pre-push hooks).

## Credits

See
[Contributors](https://github.com/qctrl/open-controls/graphs/contributors).
See [Contributors](https://github.com/qctrl/open-controls/graphs/contributors).

## License

Expand Down
7 changes: 6 additions & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
# See https://pre-commit.com/hooks.html for more hooks
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v3.4.0
rev: v4.4.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
Expand Down Expand Up @@ -39,3 +39,8 @@ repos:
# when passing in a single file as argument the ignore entry in the .pylintrc does
# not seem to be considered.
exclude: .*(venv|\.conf\.py)
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v3.0.0
hooks:
- id: prettier
files: .*(\.js|\.graphql|\.json|\.md)$
1 change: 1 addition & 0 deletions .prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
proseWrap: "never"
6 changes: 1 addition & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
# Q-CTRL Open Controls

Q-CTRL Open Controls is an open-source Python package that makes it easy to
create and deploy established error-robust quantum control protocols from the
open literature. The aim of the package is to be the most comprehensive library
of published and tested quantum control techniques developed by the community,
with easy to use export functions allowing users to deploy these controls on:
Q-CTRL Open Controls is an open-source Python package that makes it easy to create and deploy established error-robust quantum control protocols from the open literature. The aim of the package is to be the most comprehensive library of published and tested quantum control techniques developed by the community, with easy to use export functions allowing users to deploy these controls on:

- Custom quantum hardware
- Publicly available cloud quantum computers
Expand Down