2019-08-10 01:23:51 +08:00
# Contributing
2019-06-08 02:53:10 +08:00
2023-11-21 02:58:06 +08:00
Qiskit is an open-source project committed to bringing quantum computing to
people of all backgrounds. This page describes how you can join the Qiskit
community in this goal.
2019-11-08 14:30:00 +08:00
2023-11-21 02:58:06 +08:00
## Contents
* [Before you start ](#before-you-start )
2021-11-26 23:29:51 +08:00
* [Choose an issue to work on ](#Choose-an-issue-to-work-on )
2023-11-21 02:58:06 +08:00
* [Set up Python virtual development environment ](#set-up-python-virtual-development-environment )
* [Installing Qiskit from source ](#installing-qiskit-from-source )
2023-12-08 16:11:18 +08:00
* [Issues and pull requests ](#issues-and-pull-requests )
2023-11-21 02:58:06 +08:00
* [Contributor Licensing Agreement ](#contributor-licensing-agreement )
2021-11-26 23:29:51 +08:00
* [Changelog generation ](#changelog-generation )
2023-11-21 02:58:06 +08:00
* [Release notes ](#release-notes )
* [Testing ](#testing )
2021-11-26 23:29:51 +08:00
* [Style and Lint ](#style-and-lint )
2023-12-19 22:09:47 +08:00
* [Building API docs locally ](#building-api-docs-locally )
2021-11-26 23:29:51 +08:00
* [Development Cycle ](#development-cycle )
* [Branches ](#branches )
* [Release Cycle ](#release-cycle )
* [Adding deprecation warnings ](#adding-deprecation-warnings )
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
* [Using dependencies ](#using-dependencies )
* [Adding a requirement ](#adding-a-requirement )
* [Adding an optional dependency ](#adding-an-optional-dependency )
* [Checking for optionals ](#checking-for-optionals )
2021-11-26 23:29:51 +08:00
* [Dealing with git blame ignore list ](#dealing-with-the-git-blame-ignore-list )
2023-11-21 02:58:06 +08:00
## Before you start
If you are new to Qiskit contributing we recommend you do the following before diving into the code:
* Read the [Code of Conduct ](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md )
* Familiarize yourself with the Qiskit community (via [Slack ](https://qisk.it/join-slack ),
[Stack Exchange ](https://quantumcomputing.stackexchange.com ), [GitHub ](https://github.com/qiskit-community/feedback/discussions ) etc.)
## Choose an issue to work on
Qiskit uses the following labels to help non-maintainers find issues best suited to their interests and experience level:
* [good first issue ](https://github.com/Qiskit/qiskit/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 ) - these issues are typically the simplest available to work on, ideal for newcomers. They should already be fully scoped, with a clear approach outlined in the descriptions.
* [help wanted ](https://github.com/Qiskit/qiskit/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22 ) - these issues are generally more complex than good first issues. They typically cover work that core maintainers don't currently have capacity to implement and may require more investigation/discussion. These are a great option for experienced contributors looking for something a bit more challenging.
* [short project ](https://github.com/Qiskit/qiskit/issues?q=is%3Aopen+is%3Aissue+label%3A%22short+project%22 ) - these issues are bigger pieces of work that require greater time commitment. Good options for hackathons, internship projects etc.
## Set up Python virtual development environment
Virtual environments are used for Qiskit development to isolate the development environment
from system-wide packages. This way, we avoid inadvertently becoming dependent on a
particular system configuration. For developers, this also makes it easy to maintain multiple
environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).
### Set up a Python venv
All Python versions supported by Qiskit include built-in virtual environment module
[venv ](https://docs.python.org/3/tutorial/venv.html ).
Start by creating a new virtual environment with `venv` . The resulting
environment will use the same version of Python that created it and will not inherit installed
system-wide packages by default. The specified folder will be created and is used to hold the environment's
installation. It can be placed anywhere. For more detail, see the official Python documentation,
[Creation of virtual environments ](https://docs.python.org/3/library/venv.html ).
```
python3 -m venv ~/.venvs/qiskit-dev
```
Activate the environment by invoking the appropriate activation script for your system, which can
be found within the environment folder. For example, for bash/zsh:
```
source ~/.venvs/qiskit-dev/bin/activate
```
Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections
can be located for your system.
```
pip install -U pip
```
```
pip install -e .
```
### Set up a Conda environment
For Conda users, a new environment can be created as follows.
```
conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv
```
```
pip install -e .
```
## Installing Qiskit from source
Qiskit is primarily written in Python but there are some core routines
that are written in the [Rust ](https://www.rust-lang.org/ ) programming
language to improve the runtime performance. For the released versions of
qiskit we publish precompiled binaries on the
[Python Package Index ](https://pypi.org/ ) for all the supported platforms
which only requires a functional Python environment to install. However, when
building and installing from source you will need a rust compiler installed. You can do this very easily
using rustup: https://rustup.rs/ which provides a single tool to install and
configure the latest version of the rust compiler.
[Other installation methods ](https://forge.rust-lang.org/infra/other-installation-methods.html )
exist too. For Windows users, besides rustup, you will also need install
the Visual C++ build tools so that Rust can link against the system c/c++
libraries. You can see more details on this in the
[rustup documentation ](https://rust-lang.github.io/rustup/installation/windows.html ).
If you use Rustup, it will automatically install the correct Rust version
currently used by the project.
Once you have a Rust compiler installed, you can rely on the normal Python
build/install steps to install Qiskit. This means you just run
`pip install .` in your local git clone to build and install Qiskit.
Do note that if you do use develop mode/editable install (via `python setup.py develop` or `pip install -e .` ) the Rust extension will be built in debug mode
without any optimizations enabled. This will result in poor runtime performance.
If you'd like to use an editable install with an optimized binary you can
run `python setup.py build_rust --release --inplace` after you install in
editable mode to recompile the rust extensions in release mode.
Note that in order to run `python setup.py ...` commands you need have build
dependency packages installed in your environment, which are listed in the
`pyproject.toml` file under the `[build-system]` section.
Add infrastructure for gates, instruction, and operations in Rust (#12459)
* Add infrastructure for gates, instruction, and operations in Rust
This commit adds a native representation of Gates, Instruction, and
Operations to rust's circuit module. At a high level this works by
either wrapping the Python object in a rust wrapper struct that tracks
metadata about the operations (name, num_qubits, etc) and then for other
details it calls back to Python to get dynamic details like the
definition, matrix, etc. For standard library gates like Swap, CX, H,
etc this replaces the on-circuit representation with a new rust enum
StandardGate. The enum representation is much more efficient and has a
minimal memory footprint (just the enum variant and then any parameters
or other mutable state stored in the circuit instruction). All the gate
properties such as the matrix, definiton, name, etc are statically
defined in rust code based on the enum variant (which represents the
gate).
The use of an enum to represent standard gates does mean a change in
what we store on a CircuitInstruction. To represent a standard gate
fully we need to store the mutable properties of the existing Gate class
on the circuit instruction as the gate by itself doesn't contain this
detail. That means, the parameters, label, unit, duration, and condition
are added to the rust side of circuit instrucion. However no Python side
access methods are added for these as they're internal only to the Rust
code. In Qiskit 2.0 to simplify this storage we'll be able to drop, unit,
duration, and condition from the api leaving only label and parameters.
But for right now we're tracking all of the fields.
To facilitate working with circuits and gates full from rust the
setting the `operation` attribute of a `CircuitInstruction` object now
transltates the python object to an internal rust representation.
For standard gates this translates it to the enum form described earlier,
and for other circuit operations 3 new Rust structs: PyGate,
PyInstruction, and PyOperation are used to wrap the underlying Python
object in a Rust api. These structs cache some commonly accessed static
properties of the operation, such as the name, number of qubits, etc.
However for dynamic pieces, such as the definition or matrix, callback
to python to get a rust representation for those.
Similarly whenever the `operation` attribute is accessed from Python
it converts it back to the normal Python object representation. For
standard gates this involves creating a new instance of a Python object
based on it's internal rust representation. For the wrapper structs a
reference to the wrapped PyObject is returned.
To manage the 4 variants of operation (`StandardGate`, `PyGate`,
`PyInstruction`, and `PyOperation`) a new Rust trait `Operation` is
created that defines a standard interface for getting the properties
of a given circuit operation. This common interface is implemented for
the 4 variants as well as the `OperationType` enum which wraps all 4
(and is used as the type for `CircuitInstruction.operation` in the
rust code.
As everything in the `QuantumCircuit` data model is quite coupled moving
the source of truth for the operations to exist in Rust means that more
of the underlying `QuantumCircuit`'s responsibility has to move to Rust
as well. Primarily this involves the `ParameterTable` which was an
internal class for tracking which instructions in the circuit have a
`ParameterExpression` parameter so that when we go to bind parameters we
can lookup which operations need to be updated with the bind value.
Since the representation of those instructions now lives in Rust and
Python only recieves a ephemeral copy of the instructions the
ParameterTable had to be reimplemented in Rust to track the
instructions. This new parameter table maps the Parameter's uuid (as a
u128) as a unique identifier for each parameter and maps this to a
positional index in the circuit data to the underlying instruction using
that parameter. This is a bit different from the Python parameter table
which was mapping a parameter object to the id of the operation object
using that parmaeter. This also leads to a difference in the binding
mechanics as the parameter assignment was done by reference in the old
model, but now we need to update the entire instruction more explicitly
in rust. Additionally, because the global phase of a circuit can be
parameterized the ownership of global phase is moved from Python into
Rust in this commit as well.
After this commit the only properties of a circuit that are not defined
in Rust for the source of truth are the bits (and vars) of the circuit,
and when creating circuits from rust this is what causes a Python
interaction to still be required.
This commit does not translate the full standard library of gates as
that would make the pull request huge, instead this adds the basic
infrastructure for having a more efficient standard gate representation
on circuits. There will be follow up pull requests to add the missing
gates and round out support in rust.
The goal of this pull request is primarily to add the infrastructure for
representing the full circuit model (and dag model in the future) in
rust. By itself this is not expected to improve runtime performance (if
anything it will probably hurt performance because of extra type
conversions) but it is intended to enable writing native circuit
manipulations in Rust, including transpiler passes without needing
involvement from Python. Longer term this should greatly improve the
runtime performance and reduce the memory overhead of Qiskit. But,
this is just an early step towards that goal, and is more about
unlocking the future capability. The next steps after this commit are
to finish migrating the standard gate library and also update the
`QuantumCircuit` methods to better leverage the more complete rust
representation (which should help offset the performance penalty
introduced by this).
Fixes: #12205
* Fix Python->Rust Param conversion
This commit adds a custom implementation of the FromPyObject trait for
the Param enum. Previously, the Param trait derived it's impl of the
trait, but this logic wasn't perfect. In cases whern a
ParameterExpression was effectively a constant (such as `0 * x`) the
trait's attempt to coerce to a float first would result in those
ParameterExpressions being dropped from the circuit at insertion time.
This was a change in behavior from before having gates in Rust as the
parameters would disappear from the circuit at insertion time instead of
at bind time. This commit fixes this by having a custom impl for
FromPyObject that first tries to figure out if the parameter is a
ParameterExpression (or a QuantumCircuit) by using a Python isinstance()
check, then tries to extract it as a float, and finally stores a
non-parameter object; which is a new variant in the Param enum. This
new variant also lets us simplify the logic around adding gates to the
parameter table as we're able to know ahead of time which gate
parameters are `ParameterExpression`s and which are other objects (and
don't need to be tracked in the parameter table.
Additionally this commit tweaks two tests, the first is
test.python.circuit.library.test_nlocal.TestNLocal.test_parameters_setter
which was adjusted in the previous commit to workaround the bug fixed
by this commit. The second is test.python.circuit.test_parameters which
was testing that a bound ParameterExpression with a value of 0 defaults
to an int which was a side effect of passing an int input to symengine
for the bind value and not part of the api and didn't need to be
checked. This assertion was removed from the test because the rust
representation is only storing f64 values for the numeric parameters
and it is never an int after binding from the Python perspective it
isn't any different to have float(0) and int(0) unless you explicit
isinstance check like the test previously was.
* Fix qasm3 exporter for std gates without stdgates.inc
This commit fixes the handling of standard gates in Qiskit when the user
specifies excluding the use of the stdgates.inc file from the exported
qasm. Previously the object id of the standard gates were used to
maintain a lookup table of the global definitions for all the standard
gates explicitly in the file. However, the rust refactor means that
every time the exporter accesses `circuit.data[x].operation` a new
instance is returned. This means that on subsequent lookups for the
definition the gate definitions are never found. To correct this issue
this commit adds to the lookup table a fallback of the gate name +
parameters to do the lookup for. This should be unique for any standard
gate and not interfere with the previous logic that's still in place and
functional for other custom gate definitions.
While this fixes the logic in the exporter the test is still failing
because the test is asserting the object ids are the same in the qasm3
file, which isn't the case anymore. The test will be updated in a
subsequent commit to validate the qasm3 file is correct without using
a hardcoded object id.
* Fix base scheduler analysis pass duration setting
When ALAPScheduleAnalysis and ASAPScheduleAnalysis were setting the
duration of a gate they were doing `node.op.duration = duration` this
wasn't always working because if `node.op` was a standard gate it
returned a new Python object created from the underlying rust
representation. This commit fixes the passes so that they modify the
duration and then explicit set the operation to update it's rust
representation.
* Fix python lint
* Fix last failing qasm3 test for std gates without stdgates.inc
While the logic for the qasm3 exporter was fixed
in commit a6e69ba4c99cdd2fa50ed10399cada322bc88903 to handle the edge
case of a user specifying that the qasm exporter does not use the
stdgates.inc include file in the output, but also has qiskit's standard
gates in their circuit being exported. The one unit test to provide
coverage for that scenario was not passing because when an id was used
for the gate definitions in the qasm3 file it was being referenced
against a temporary created by accessing a standard gate from the
circuit and the ids weren't the same so the reference string didn't
match what the exporter generated. This commit fixes this by changing
the test to not do an exact string comparison, but instead a line by
line comparison that either does exact equality check or a regex search
for the expected line and the ids are checked as being any 15 character
integer.
* Remove superfluous comment
* Cache imported classes with GILOnceCell
* Remove unused python variables
* Add missing file
* Update QuantumCircuit gate methods to bypass Python object
This commit updates the QuantumCircuit gate methods which add a given
gate to the circuit to bypass the python gate object creation and
directly insert a rust representation of the gate. This avoids a
conversion in the rust side of the code. While in practice this is just
the Python side object creation and a getattr for the rust code to
determine it's a standard gate that we're skipping. This may add up over
time if there are a lot of gates being created by the method.
To accomplish this the rust code handling the mapping of rust
StandardGate variants to the Python classes that represent those gates
needed to be updated as well. By bypassing the python object creation
we need a fallback to populate the gate class for when a user access the
operation object from Python. Previously this mapping was only being
populated at insertion time and if we never insert the python object
(for a circuit created only via the methods) then we need a way to find
what the gate class is. A static lookup table of import paths and class names
are added to `qiskit_circuit::imports` module to faciliate this and
helper functions are added to facilitate interacting with the class
objects that represent each gate.
* Deduplicate gate matrix definitions
* Fix lint
* Attempt to fix qasm3 test failure
* Add compile time option to cache py gate returns for rust std gates
This commit adds a new rust crate feature flag for the qiskit-circuits
and qiskit-pyext that enables caching the output from
CircuitInstruction.operation to python space. Previously, for memory
efficiency we were reconstructing the python object on demand for every
access. This was to avoid carrying around an extra pointer and keeping
the ephemeral python object around longer term if it's only needed once.
But right now nothing is directly using the rust representation yet and
everything is accessing via the python interface, so recreating gate
objects on the fly has a huge performance penalty. To avoid that this
adds caching by default as a temporary solution to avoid this until we
have more usage of the rust representation of gates.
There is an inherent tension between an optimal rust representation
and something that is performant for Python access and there isn't a
clear cut answer on which one is better to optimize for. A build time
feature lets the user pick, if what we settle on for the default doesn't
agree with their priorities or use case. Personally I'd like to see us
disable the caching longer term (hopefully before releasing this
functionality), but that's dependent on a sufficent level of usage from
rust superseding the current Python space usage in the core of Qiskit.
* Add num_nonlocal_gates implementation in rust
This commit adds a native rust implementation to rust for the
num_nonlocal_gates method on QuantumCircuit. Now that we have a rust
representation of gates it is potentially faster to do the count because
the iteration and filtering is done rust side.
* Performance tuning circuit construction
This commit fixes some performance issues with the addition of standard
gates to a circuit. To workaround potential reference cycles in Python
when calling rust we need to check the parameters of the operation. This
was causing our fast path for standard gates to access the `operation`
attribute to get the parameters. This causes the gate to be eagerly
constructed on the getter. However, the reference cycle case can only
happen in situations without a standard gate, and the fast path for
adding standard gates directly won't need to run this so a skip is added
if we're adding a standard gate.
* Add back validation of parameters on gate methods
In the previous commit a side effect of the accidental eager operation
creation was that the parameter input for gates were being validated by
that. By fixing that in the previous commit the validation of input
parameters on the circuit methods was broken. This commit fixes that
oversight and adds back the validation.
* Skip validation on gate creation from rust
* Offload operation copying to rust
This commit fixes a performance regression in the
`QuantumCircuit.copy()` method which was previously using Python to copy
the operations which had extra overhead to go from rust to python and
vice versa. This moves that logic to exist in rust and improve the copy
performance.
* Fix lint
* Perform deepcopy in rust
This commit moves the deepcopy handling to occur solely in Rust.
Previously each instruction would be directly deepcopied by iterating
over the circuit data. However, we can do this rust side now and doing
this is more efficient because while we need to rely on Python to run a
deepcopy we can skip it for the Rust standard gates and rely on Rust to
copy those gates.
* Fix QuantumCircuit.compose() performance regression
This commit fixes a performance regression in the compose() method. This
was caused by the checking for classical conditions in the method
requiring eagerly converting all standard gates to a Python object. This
changes the logic to do this only if we know we have a condition (which
we can determine Python side now).
* Fix map_ops test case with no caching case
* Fix typos in docs
This commit fixes several docs typos that were caught during code review.
Co-authored-by: Eli Arbel <46826214+eliarbel@users.noreply.github.com>
* Shrink memory usage for extra mutable instruction state
This commit changes how we store the extra mutable instruction state
(condition, duration, unit, and label) for each `CircuitInstruction`
and `PackedInstruction` in the circuit. Previously it was all stored
as separate `Option<T>` fields on the struct, which required at least
a pointer's width for each field which was wasted space the majority of
the time as using these fields are not common. To optimize the memory
layout of the struct this moves these attributes to a new struct which
is put in an `Option<Box<_>>` which reduces it from 4 pointer widths
down to 1 per object. This comes from extra runtime cost from the extra
layer of pointer indirection but as this is the uncommon path this
tradeoff is fine.
* Remove Option<> from params field in CircuitInstruction
This commit removes the Option<> from the params field in
CircuitInstruction. There is no real distinction between an empty vec
and None in this case, so the option just added another layer in the API
that we didn't need to deal with. Also depending on the memory alignment
using an Option<T> might have ended up in a little extra memory usage
too, so removing it removes that potential source of overhead.
* Eagerly construct rust python wrappers in .append()
This commit updates the Python code in QuantumCircuit.append() method
to eagerly construct the rust wrapper objects for python defined circuit
operations.
* Simplify code around handling python errors in rust
* Revert "Skip validation on gate creation from rust"
This reverts commit 2f81bde8bf32b06b4165048896eabdb36470814d. The
validation skipping was unsound in some cases and could lead to invalid
circuit being generated. If we end up needing this as an optimization we
can remove this in the future in a follow-up PR that explores this in
isolation.
* Temporarily use git for qasm3 import
In Qiskit/qiskit-qasm3-import#34 the issue we're hitting caused by
qiskit-qasm3-import using the private circuit attributes removed in this
PR was fixed. This commit temporarily moves to installing it from git so
we can fully run CI. When qiskit-qasm3-import is released we should
revert this commit.
* Fix lint
* Fix lint for real (we really need to use a py312 compatible version of pylint)
* Fix test failure caused by incorrect lint fix
* Relax trait-method typing requirements
* Encapsulate `GILOnceCell` initialisers to local logic
* Simplify Interface for building circuit of standard gates in rust
* Simplify complex64 creation in gate_matrix.rs
This just switches Complex64::new(re, im) to be c64(re, im) to reduce
the amount of typing. c64 needs to be defined inplace so it can be a
const fn.
* Simplify initialization of array of elements that are not Copy (#28)
* Simplify initialization of array of elements that are not Copy
* Only generate array when necessary
* Fix doc typos
Co-authored-by: Kevin Hartman <kevin@hart.mn>
* Add conversion trait for OperationType -> OperationInput and simplify CircuitInstruction::replace()
* Use destructuring for operation_type_to_py extra attr handling
* Simplify trait bounds for map_indices()
The map_indices() method previously specified both Iterator and
ExactSizeIterator for it's trait bounds, but Iterator is a supertrait of
ExactSizeIterator and we don't need to explicitly list both. This commit
removes the duplicate trait bound.
* Make Qubit and Clbit newtype member public
As we start to use Qubit and Clbit for creating circuits from accelerate
and other crates in the Qiskit workspace we need to be able to create
instances of them. However, the newtype member BitType was not public
which prevented creating new Qubits. This commit fixes this by making it
public.
* Use snakecase for gate matrix names
* Remove pointless underscore prefix
* Use downcast instead of bound
* Rwork _append reference cycle handling
This commit reworks the multiple borrow handling in the _append() method
to leveraging `Bound.try_borrow()` to return a consistent error message
if we're unable to borrow a CircuitInstruction in the rust code meaning
there is a cyclical reference in the code. Previously we tried to detect
this cycle up-front which added significant overhead for a corner case.
* Make CircuitData.global_phase_param_index a class attr
* Use &[Param] instead of &SmallVec<..> for operation_type_and_data_to_py
* Have get_params_unsorted return a set
* Use lookup table for static property methods of StandardGate
* Use PyTuple::empty_bound()
* Fix lint
* Add missing test method docstring
* Reuse allocations in parameter table update
* Remove unnecessary global phase zeroing
* Move manually set params to a separate function
* Fix release note typo
* Use constant for global-phase index
* Switch requirement to release version
---------
Co-authored-by: Eli Arbel <46826214+eliarbel@users.noreply.github.com>
Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
Co-authored-by: John Lapeyre <jlapeyre@users.noreply.github.com>
Co-authored-by: Kevin Hartman <kevin@hart.mn>
2024-06-13 18:48:40 +08:00
### Compile time options
When building qiskit from source there are options available to control how
Qiskit is built. Right now the only option is if you set the environment
variable `QISKIT_NO_CACHE_GATES=1` this will disable runtime caching of
Python gate objects when accessing them from a `QuantumCircuit` or `DAGCircuit` .
This makes a tradeoff between runtime performance for Python access and memory
overhead. Caching gates will result in better runtime for users of Python at
the cost of increased memory consumption. If you're working with any custom
transpiler passes written in python or are otherwise using a workflow that
repeatedly accesses the `operation` attribute of a `CircuitInstruction` or `op`
attribute of `DAGOpNode` enabling caching is recommended.
2023-11-21 02:58:06 +08:00
2023-12-08 16:11:18 +08:00
## Issues and pull requests
2023-11-21 02:58:06 +08:00
We use [GitHub pull requests ](https://help.github.com/articles/about-pull-requests ) to accept
contributions.
While not required, opening a new issue about the bug you're fixing or the
feature you're working on before you open a pull request is an important step
in starting a discussion with the community about your work. The issue gives us
a place to talk about the idea and how we can work together to implement it in
the code. It also lets the community know what you're working on, and if you
need help, you can reference the issue when discussing it with other community
and team members.
2023-12-08 16:11:18 +08:00
* For documentation issues relating to pages in the Start, Build, Transpile, Verify, Run, and Migration guides sections of [docs.quantum.ibm.com ](https://docs.quantum.ibm.com/ ), please open an issue in the [Qiskit/documentation repo ](https://github.com/Qiskit/documentation/issues/new/choose ) rather than the Qiskit/qiskit repo. In other words, any page that DOES NOT have `/api/` in the url should be addressed in the Qiskit/documentation repo. (Exception: the [Migration guide ](https://docs.quantum.ibm.com/api/migration-guides ) urls contain `/api/` but are managed in the Qiskit/documentation repo.)
* For issues relating to API reference pages (any page that contains `/api/` in the url), please open an issue in the repo specific to that API reference, for example [Qiskit/qiskit ](https://github.com/Qiskit/qiskit/issues/new/choose ), [Qiskit/qiskit-aer ](https://github.com/Qiskit/qiskit-aer/issues/new/choose ), or [Qiskit/qiskit-ibm-runtime ](https://github.com/Qiskit/qiskit-ibm-runtime/issues/new/choose ).
2023-11-21 02:58:06 +08:00
If you've written some code but need help finishing it, want to get initial
feedback on it prior to finishing it, or want to share it and discuss prior
to finishing the implementation, you can open a *Draft* pull request and prepend
the title with the ** \[WIP\]** tag (for Work In Progress). This will indicate
to reviewers that the code in the PR isn't in its final state and will change.
It also means that we will not merge the commit until it is finished. You or a
reviewer can remove the [WIP] tag when the code is ready to be fully reviewed for merging.
Before marking your Pull Request as "ready for review" make sure you have followed the
PR Checklist below. PRs that adhere to this list are more likely to get reviewed and
merged in a timely manner.
2021-11-26 23:29:51 +08:00
2019-08-20 02:12:55 +08:00
### Pull request checklist
2019-06-08 02:53:10 +08:00
2019-08-10 01:23:51 +08:00
When submitting a pull request and you feel it is ready for review,
please ensure that:
1. The code follows the code style of the project and successfully
2023-11-21 02:58:06 +08:00
passes the CI tests. For convenience, you can execute `tox` locally,
2019-08-10 01:23:51 +08:00
which will run these checks and report any issues.
2021-05-05 21:53:39 +08:00
2021-04-22 19:22:51 +08:00
If your code fails the local style checks (specifically the black
code formatting check) you can use `tox -eblack` to automatically
fix update the code formatting.
2019-08-10 01:23:51 +08:00
2. The documentation has been updated accordingly. In particular, if a
function or class has been modified during the PR, please update the
*docstring* accordingly.
2021-04-16 00:21:46 +08:00
If your pull request is adding a new class, function, or module that is
intended to be user facing ensure that you've also added those to a
documentation `autosummary` index to include it in the api documentation.
2024-05-06 14:53:21 +08:00
3. If you are of the opinion that the modifications you made warrant additional tests,
feel free to include them
2019-08-10 01:23:51 +08:00
4. Ensure that if your change has an end user facing impact (new feature,
2019-09-23 22:07:52 +08:00
deprecation, removal etc) that you have added a reno release note for that
change and that the PR is tagged for the changelog.
2023-11-21 02:58:06 +08:00
5. All contributors have signed the CLA.
6. The PR has a concise and explanatory title (e.g. `Fixes Issue1234` is a bad title!).
7. If the PR addresses an open issue the PR description includes the `fixes #issue-number`
syntax to link the PR to that issue (**you must use the exact phrasing in order for GitHub
to automatically close the issue when the PR merges**)
### Code Review
Code review is done in the open and is open to anyone. While only maintainers have
access to merge commits, community feedback on pull requests is extremely valuable.
It is also a good mechanism to learn about the code base.
Response times may vary for your PR, it is not unusual to wait a few weeks for a maintainer
to review your work, due to other internal commitments. If you have been waiting over a week
for a review on your PR feel free to tag the relevant maintainer in a comment to politely remind
them to review your work.
2019-09-23 22:07:52 +08:00
2023-11-21 02:58:06 +08:00
Please be patient! Maintainers have a number of other priorities to focus on and so it may take
some time for your work to get reviewed and merged. PRs that are in a good shape (i.e. following the [Pull request checklist ](#pull-request-checklist ))
are easier for maintainers to review and more likely to get merged in a timely manner. Please also make
sure to always be kind and respectful in your interactions with maintainers and other contributors, you can read
[the Qiskit Code of Conduct ](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md ).
## Contributor Licensing Agreement
Before you can submit any code, all contributors must sign a
contributor license agreement (CLA). By signing a CLA, you're attesting
that you are the author of the contribution, and that you're freely
contributing it under the terms of the Apache-2.0 license.
When you contribute to the Qiskit project with a new pull request,
a bot will evaluate whether you have signed the CLA. If required, the
bot will comment on the pull request, including a link to accept the
agreement. The [individual CLA ](https://qiskit.org/license/qiskit-cla.pdf )
document is available for review as a PDF.
Note: If your contribution is part of your employment or your contribution
is the property of your employer, then you will more than likely need to sign a
[corporate CLA ](https://qiskit.org/license/qiskit-corporate-cla.pdf ) too and
email it to us at < qiskit @ us . ibm . com > .
## Changelog generation
2019-09-23 22:07:52 +08:00
The changelog is automatically generated as part of the release process
automation. This works through a combination of the git log and the pull
request. When a release is tagged and pushed to github the release automation
bot looks at all commit messages from the git log for the release. It takes the
PR numbers from the git log (assuming a squash merge) and checks if that PR had
a `Changelog:` label on it. If there is a label it will add the git commit
message summary line from the git log for the release to the changelog.
If there are multiple `Changelog:` tags on a PR the git commit message summary
line from the git log will be used for each changelog category tagged.
The current categories for each label are as follows:
| PR Label | Changelog Category |
| -----------------------|--------------------|
| Changelog: Deprecation | Deprecated |
| Changelog: New Feature | Added |
| Changelog: API Change | Changed |
| Changelog: Removal | Removed |
| Changelog: Bugfix | Fixed |
2019-06-08 02:53:10 +08:00
2023-11-21 02:58:06 +08:00
## Release notes
2019-08-20 02:12:55 +08:00
When making any end user facing changes in a contribution we have to make sure
2023-11-21 02:58:06 +08:00
we document that when we release a new version of qiskit. The expectation
2019-08-20 02:12:55 +08:00
is that if your code contribution has user facing changes that you will write
the release documentation for these changes. This documentation must explain
what was changed, why it was changed, and how users can either use or adapt
to the change. The idea behind release documentation is that when a naive
2020-08-02 00:40:17 +08:00
user with limited internal knowledge of the project is upgrading from the
2019-08-20 02:12:55 +08:00
previous release to the new one, they should be able to read the release notes,
understand if they need to update their program which uses qiskit, and how they
would go about doing that. It ideally should explain why they need to make
this change too, to provide the necessary context.
To make sure we don't forget a release note or if the details of user facing
changes over a release cycle we require that all user facing changes include
documentation at the same time as the code. To accomplish this we use the
[reno ](https://docs.openstack.org/reno/latest/ ) tool which enables a git based
workflow for writing and compiling release notes.
2023-11-21 02:58:06 +08:00
### Adding a new release note
2019-08-20 02:12:55 +08:00
Making a new release note is quite straightforward. Ensure that you have reno
2022-03-17 00:25:04 +08:00
installed with:
2019-08-20 02:12:55 +08:00
pip install -U reno
Once you have reno installed you can make a new release note by running in
2022-03-17 00:25:04 +08:00
your local repository checkout's root:
2019-08-20 02:12:55 +08:00
reno new short-description-string
where short-description-string is a brief string (with no spaces) that describes
what's in the release note. This will become the prefix for the release note
file. Once that is run it will create a new yaml file in releasenotes/notes.
Then open that yaml file in a text editor and write the release note. The basic
structure of a release note is restructured text in yaml lists under category
keys. You add individual items under each category and they will be grouped
automatically by release when the release notes are compiled. A single file
can have as many entries in it as needed, but to avoid potential conflicts
you'll want to create a new file for each pull request that has user facing
changes. When you open the newly created file it will be a full template of
the different categories with a description of a category as a single entry
in each category. You'll want to delete all the sections you aren't using and
update the contents for those you are. For example, the end result should
2022-03-17 00:25:04 +08:00
look something like:
2019-08-20 02:12:55 +08:00
```yaml
features:
- |
Introduced a new feature foo, that adds support for doing something to
2022-03-17 00:25:04 +08:00
:class:`.QuantumCircuit` objects. It can be used by using the foo function,
2019-08-20 02:12:55 +08:00
for example::
from qiskit import foo
from qiskit import QuantumCircuit
foo(QuantumCircuit())
- |
2022-03-17 00:25:04 +08:00
The :class:`.QuantumCircuit` class has a new method :meth:`~.QuantumCircuit.foo`.
This is the equivalent of calling the :func:`~qiskit.foo` to do something to your
:class:`.QuantumCircuit`. This is the equivalent of running :func:`~qiskit.foo`
on your circuit, but provides the convenience of running it natively on
2019-08-20 02:12:55 +08:00
an object. For example::
from qiskit import QuantumCircuit
circ = QuantumCircuit()
circ.foo()
deprecations:
- |
The ``qiskit.bar`` module has been deprecated and will be removed in a
future release. Its sole function, ``foobar()`` has been superseded by the
2022-03-17 00:25:04 +08:00
:func:`~qiskit.foo` function which provides similar functionality but with
more accurate results and better performance. You should update your
:func:`~qiskit.bar.foobar` calls to :func:`~qiskit.foo`.
2019-08-20 02:12:55 +08:00
```
2024-03-20 22:47:58 +08:00
You can also look at other release notes for other examples.
For the ``features``, ``deprecations``, and ``upgrade`` sections there are a
list of subsections available which are used to provide more structure to the
release notes organization. If you're adding a feature, making an API change,
or deprecating an API you should pick the subsection that matches that note.
For example if you're adding a new feature to the transpiler, you should put
it under the ``upgrade_transpiler`` section.
2019-08-20 02:12:55 +08:00
2022-03-17 00:25:04 +08:00
Note that you can use sphinx [restructured text syntax ](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html ).
In fact, you can use any restructured text feature in them (code sections, tables,
2019-08-20 02:12:55 +08:00
enumerated lists, bulleted list, etc) to express what is being changed as
needed. In general you want the release notes to include as much detail as
needed so that users will understand what has changed, why it changed, and how
they'll have to update their code.
After you've finished writing your release notes you'll want to add the note
file to your commit with `git add` and commit them to your PR branch to make
sure they're included with the code in your PR.
2023-11-21 02:58:06 +08:00
#### Linking to issues
2019-12-05 22:01:59 +08:00
If you need to link to an issue or other github artifact as part of the release
note this should be done using an inline link with the text being the issue
number. For example you would write a release note with a link to issue 12345
as:
```yaml
fixes:
- |
Fixes a race condition in the function ``foo()``. Refer to
2023-11-21 02:58:06 +08:00
`#12345 <https://github.com/Qiskit/qiskit/issues/12345>` for more
2019-12-05 22:01:59 +08:00
details.
```
2019-08-20 02:12:55 +08:00
#### Generating the release notes
2022-03-17 00:25:04 +08:00
After release notes have been added, you can use reno to see what the full output
of the release notes is. In general the output from reno that we'll get is a rst
2019-08-20 02:12:55 +08:00
(ReStructuredText) file that can be compiled by
[sphinx ](https://www.sphinx-doc.org/en/master/ ). To generate the rst file you
2023-11-21 02:58:06 +08:00
use the ``reno report`` command. If you want to generate the full release
2022-03-17 00:25:04 +08:00
notes for all releases (since we started using reno during 0.9) you just run:
2019-08-20 02:12:55 +08:00
reno report
but you can also use the ``--version`` argument to view a single release (after
2022-03-17 00:25:04 +08:00
it has been tagged:
2019-08-20 02:12:55 +08:00
reno report --version 0.9.0
At release time ``reno report`` is used to generate the release notes for the
release and the output will be submitted as a pull request to the documentation
repository's [release notes file](
https://github.com/Qiskit/qiskit/blob/master/docs/release_notes.rst)
2019-10-01 00:50:44 +08:00
#### Building release notes locally
2023-11-21 02:58:06 +08:00
Building The release notes are part of the standard qiskit documentation
2019-10-01 00:50:44 +08:00
builds. To check what the rendered html output of the release notes will look
like for the current state of the repo you can run: `tox -edocs` which will
build all the documentation into `docs/_build/html` and the release notes in
2020-01-10 06:23:54 +08:00
particular will be located at `docs/_build/html/release_notes.html`
2019-08-20 02:12:55 +08:00
2023-11-21 02:58:06 +08:00
## Testing
2019-06-08 02:53:10 +08:00
2019-08-10 01:23:51 +08:00
Once you've made a code change, it is important to verify that your change
does not break any existing tests and that any new tests that you've added
also run successfully. Before you open a new pull request for your change,
you'll want to run the test suite locally.
The easiest way to run the test suite is to use
[**tox** ](https://tox.readthedocs.io/en/latest/# ). You can install tox
with pip: `pip install -U tox` . Tox provides several advantages, but the
biggest one is that it builds an isolated virtualenv for running tests. This
means it does not pollute your system python when running. Additionally, the
environment that tox sets up matches the CI environment more closely and it
runs the tests in parallel (resulting in much faster execution). To run tests
on all installed supported python versions and lint/style checks you can simply
run `tox` . Or if you just want to run the tests once run for a specific python
2023-05-05 23:28:34 +08:00
version: `tox -epy310` (or replace py310 with the python version you want to use,
py39 or py311).
2019-08-10 01:23:51 +08:00
If you just want to run a subset of tests you can pass a selection regex to
the test runner. For example, if you want to run all tests that have "dag" in
2023-05-05 23:28:34 +08:00
the test id you can run: `tox -epy310 -- dag` . You can pass arguments directly to
2019-08-10 01:23:51 +08:00
the test runner after the bare `--` . To see all the options on test selection
you can refer to the stestr manual:
https://stestr.readthedocs.io/en/stable/MANUAL.html#test-selection
If you want to run a single test module, test class, or individual test method
you can do this faster with the `-n` /`--no-discover` option. For example:
to run a module:
```
2023-05-05 23:28:34 +08:00
tox -epy310 -- -n test.python.test_examples
2019-08-10 01:23:51 +08:00
```
or to run the same module by path:
```
2023-05-05 23:28:34 +08:00
tox -epy310 -- -n test/python/test_examples.py
2019-08-10 01:23:51 +08:00
```
to run a class:
```
2023-05-05 23:28:34 +08:00
tox -epy310 -- -n test.python.test_examples.TestPythonExamples
2019-08-10 01:23:51 +08:00
```
to run a method:
```
2023-05-05 23:28:34 +08:00
tox -epy310 -- -n test.python.test_examples.TestPythonExamples.test_all_examples
2019-08-10 01:23:51 +08:00
```
2019-06-08 02:53:10 +08:00
2019-08-10 01:23:51 +08:00
Alternatively there is a makefile provided to run tests, however this
does not perform any environment setup. It also doesn't run tests in
parallel and doesn't provide an option to easily modify the tests run.
For executing the tests with the makefile, a `make test` target is available.
The execution of the tests (both via the make target and during manual
2019-06-08 02:53:10 +08:00
invocation) takes into account the `LOG_LEVEL` environment variable. If
present, a `.log` file will be created on the test directory with the
output of the log calls, which will also be printed to stdout. You can
adjust the verbosity via the content of that variable, for example:
Linux and Mac:
``` {.bash}
$ cd out
out$ LOG_LEVEL="DEBUG" ARGS="-V" make test
```
Windows:
``` {.bash}
$ cd out
C:\..\out> set LOG_LEVEL="DEBUG"
C:\..\out> set ARGS="-V"
C:\..\out> make test
```
For executing a simple python test manually, we don\'t need to change
the directory to `out` , just run this command:
Linux and Mac:
``` {.bash}
$ LOG_LEVEL=INFO python -m unittest test/python/circuit/test_circuit_operations.py
```
Windows:
``` {.bash}
C:\..\> set LOG_LEVEL="INFO"
C:\..\> python -m unittest test/python/circuit/test_circuit_operations.py
```
2020-09-10 07:01:54 +08:00
##### STDOUT/STDERR and logging capture
2021-02-02 01:43:36 +08:00
When running tests in parallel using `stestr` either via tox, the Makefile
(`make test_ci`), or in CI we set the env variable
`QISKIT_TEST_CAPTURE_STREAMS` which will capture any text written to stdout,
stderr, and log messages and add them as attachments to the tests run so
output can be associated with the test case it originated from. However, if
you run tests with `stestr` outside of these mechanisms by default the streams
are not captured. To enable stream capture just set the
`QISKIT_TEST_CAPTURE_STREAMS` env variable to `1` . If this environment
variable is set outside of running with `stestr` the streams (STDOUT, STDERR,
and logging) will still be captured but **not** displayed in the test runners
output. If you are using the stdlib unittest runner a similar result can be
accomplished by using the
[`--buffer` ](https://docs.python.org/3/library/unittest.html#command-line-options )
option (e.g. `python -m unittest discover --buffer ./test/python` ).
2020-09-10 07:01:54 +08:00
2019-06-08 02:53:10 +08:00
##### Test Skip Options
How and which tests are executed is controlled by an environment
variable, `QISKIT_TESTS` :
2019-06-19 02:43:51 +08:00
Option | Description | Default
------ | ----------- | -------
`run_slow` | It runs tests tagged as *slow* . | `False`
2019-06-08 02:53:10 +08:00
2019-06-19 02:43:51 +08:00
It is possible to provide more than one option separated with commas.
2019-06-08 02:53:10 +08:00
Alternatively, the `make test_ci` target can be used instead of
`make test` in order to run in a setup that replicates the configuration
we used in our CI systems more closely.
2021-04-22 19:22:51 +08:00
### Snapshot Testing for Visualizations
2021-07-23 08:06:55 +08:00
If you are working on code that makes changes to any matplotlib visualisations
you will need to check that your changes don't break any snapshot tests, and add
2021-04-22 19:22:51 +08:00
new tests where necessary. You can do this as follows:
1. Make sure you have pushed your latest changes to your remote branch.
2023-11-21 02:58:06 +08:00
2. Go to link: `https://mybinder.org/v2/gh/<github_user>/<repo>/<branch>?urlpath=apps/test/ipynb/mpl_tester.ipynb` . For example, if your GitHub username is `username` , your forked repo has the same name the original, and your branch is `my_awesome_new_feature` , you should visit https://mybinder.org/v2/gh/username/qiskit/my_awesome_new_feature?urlpath=apps/test/ipynb/mpl_tester.ipynb.
2021-07-23 08:06:55 +08:00
This opens a Jupyter Notebook application running in the cloud that automatically runs
2021-04-22 19:22:51 +08:00
the snapshot tests (note this may take some time to finish loading).
3. Each test result provides a set of 3 images (left: reference image, middle: your test result, right: differences). In the list of tests the passed tests are collapsed and failed tests are expanded. If a test fails, you will see a situation like this:
< img width = "995" alt = "Screenshot_2021-03-26_at_14 13 54" src = "https://user-images.githubusercontent.com/23662430/112663508-d363e800-8e50-11eb-9478-6d665d0ff086.png" >
2021-07-23 08:06:55 +08:00
4. Fix any broken tests. Working on code for one aspect of the visualisations
can sometimes result in minor changes elsewhere to spacing etc. In these cases
2021-04-22 19:22:51 +08:00
you just need to update the reference images as follows:
- download the mismatched images (link at top of Jupyter Notebook output)
- unzip the folder
2023-11-21 02:58:06 +08:00
- copy and paste the new images into `qiskit/test/ipynb/mpl/references` ,
2021-04-22 19:22:51 +08:00
replacing the existing reference images
2021-07-23 08:06:55 +08:00
- add, commit and push your changes, then restart the Jupyter Notebook app in your browser. The
2021-04-22 19:22:51 +08:00
tests should now pass.
5. Add new snapshot tests covering your new features, extensions, or bugfixes.
- add your new snapshot tests to `test/ipynb/mpl/test_circuit_matplotlib_drawer.py`
, where you can also find existing tests to use as a guide.
2021-07-23 08:06:55 +08:00
- commit and push your changes, restart the Jupyter Notebook app in your browser.
As this is the first time you run your new tests there won't be any reference
images to compare to. Instead you should see an option in the list of tests
2021-04-22 19:22:51 +08:00
to download the new images, like so:
< img width = "1002" alt = "Screenshot_2021-03-26_at_15 38 31" src = "https://user-images.githubusercontent.com/23662430/112665215-b9c3a000-8e52-11eb-89e7-b18550718522.png" >
2023-11-21 02:58:06 +08:00
- download the new images, then copy and paste into `qiskit/test/ipynb/mpl/references`
2021-07-23 08:06:55 +08:00
- add, commit and push your changes, restart the Jupyter Notebook app in your browser. The
2021-04-22 19:22:51 +08:00
new tests should now pass.
Note: If you have run `test/ipynb/mpl_tester.ipynb` locally it is possible some file metadata has changed, **please do not commit and push changes to this file unless they were intentional** .
2021-05-05 21:53:39 +08:00
Add Rust-based `SparsePauliOp.to_matrix` and Miri tests (#11388)
* Add Rust-based `SparsePauliOp.to_matrix`
This rewrites the numerical version of `SparsePauliOp.to_matrix` to be
written in parallelised Rust, building up the matrices row-by-row rather
than converting each contained operator to a matrix individually and
summing them.
The new algorithms are complete row-based, which is embarrassingly
parallel for dense matrices, and parallelisable with additional copies
and cumulative sums in the CSR case.
The two new algorithms are an asymptotic complexity improvement for both
dense and sparse matrices over the "sum the individual matrices"
version. In the dense case, the cost goes from
O(4 ** num_qubits * num_ops)
to
O(4 ** num_qubits + (2 ** num_qubits) * reduced_num_ops)
where the first term is from the zeroing of the matrix, and the second
is from updating the elements in-place. `reduced_num_ops` is the number
of explicitly stored operations after Pauli-operator uniqueness
compaction, so is upper-bounded as `4 ** num_qubits`. (The Pauli
compaction goes as `O(num_ops)`, so is irrelevant to the complexity
discussion.) The CSR form of the algorithm goes as
O(2 ** num_qubits * reduced_num_ops * lg(reduced_num_ops))
which (I think! - I didn't fully calculate it) is asymptotically the
same as before, but in practice the constant factors and intermediate
memory use are *dramatically* reduced, and the new algorithm is
threadable with an additional `O(2 ** num_qubits * reduced_num_ops)`
intermediate memory overhead (the serial form has only
`O(reduced_num_ops)` memory overhead).
The `object`-coefficients form is left as-is to avoid exploding the
complexity in Rust space; these objects are already slow and unsuited
for high-performance code, so the effects should be minimal.
* Add non-blocking Miri to CI
As we begin to include more `unsafe` code in the Rust-accelerated
components, it is becoming more important for us to test these in an
undefined-behaviour sanitiser. This is done in a separate CI job
because:
- we do not yet know how stable Miri will be, so we don't want to block
on it.
- some dependencies need their version-resolution patching to
Miri-compatible versions, but we want to run our regular test suites
with the same versions of packages we will be building against.
* Parallelise cumulative nnz sum
This parallelises the previously serial-only cumulative sum of the
`indptr` array of number of non-zero entries at the end. In practice, I
didn't actually see any change in performance from this, but
philosophically it feels like the right thing to do.
* Update Miri pin to later version of crossbeam-epohc
* Improve error handling and messages
* Simplify unnecessary match
* Add link to environment variable configuration
* Add link to Rayon plumbing README
* Add explicit test of serial and parallel modes
2024-04-26 23:30:07 +08:00
### Testing Rust components
Rust-accelerated functions are generally tested from Python space, but in cases
where there is Rust-specific internal details to be tested, `#[test]` functions
can be included inline. Typically it's most convenient to place these in a
separate inline module that is only conditionally compiled in, such as
```rust
#[cfg(test)]
mod tests {
#[test]
fn my_first_test() {
assert_eq!(2, 1 + 1);
}
}
```
To run the Rust-space tests, do
```bash
cargo test --no-default-features
```
Our Rust-space components are configured such that setting the
``-no-default-features`` flag will compile the test runner, but not attempt to
build a linked CPython extension module, which would cause linker failures.
### Unsafe code and Miri
Any `unsafe` code added to the Rust logic should be exercised by Rust-space
tests, in addition to the more complete Python test suite. In CI, we run the
Rust test suite under [Miri ](https://github.com/rust-lang/miri ) as an
undefined-behavior sanitizer.
Miri is currently only available on `nightly` Rust channels, so to run it
locally you will need to ensure you have that channel available, such as by
```bash
rustup install nightly --components miri
```
After this, you can run the Miri test suite with
```bash
MIRIFLAGS="< flags go here > " cargo +nightly miri test
```
For the current set of `MIRIFLAGS` used by Qiskit's CI, see the
[`miri.yml` ](https://github.com/Qiskit/qiskit/blob/main/.github/workflows/miri.yml )
GitHub Action file. This same file may also include patches to dependencies to
make them compatible with Miri, which you would need to temporarily apply as
well.
2019-08-10 01:23:51 +08:00
## Style and lint
2021-05-05 21:53:39 +08:00
2023-11-21 02:58:06 +08:00
Qiskit uses three tools for verify code formatting and lint checking. The
2021-04-22 19:22:51 +08:00
first tool is [black ](https://github.com/psf/black ) which is a code formatting
tool that will automatically update the code formatting to a consistent style.
2021-05-08 00:19:38 +08:00
The second tool is [pylint ](https://www.pylint.org/ ) which is a code linter
2021-04-22 19:22:51 +08:00
which does a deeper analysis of the Python code to find both style issues and
2023-05-31 06:43:36 +08:00
potential bugs and other common issues in Python. The third tool is the linter
[ruff ](https://github.com/charliermarsh/ruff ), which has been recently
2023-11-21 02:58:06 +08:00
introduced into Qiskit on an experimental basis. Only a very small number
2023-05-31 06:43:36 +08:00
of rules are enabled.
You can check that your local modifications conform to the style rules by
running `tox -elint` which will run `black` , `ruff` , and `pylint` to check the
local code formatting and lint. If black returns a code formatting error you can
run `tox -eblack` to automatically update the code formatting to conform to the
style. However, if `ruff` or `pylint` return any error you will have to fix
these issues by manually updating your code.
Because `pylint` analysis can be slow, there is also a `tox -elint-incr` target,
which runs `black` and `ruff` just as `tox -elint` does, but only applies
`pylint` to files which have changed from the source github. On rare occasions
this will miss some issues that would have been caught by checking the complete
source tree, but makes up for this by being much faster (and those rare
oversights will still be caught by the CI after you open a pull request).
Because they are so fast, it is sometimes convenient to run the tools `black` and `ruff` separately
rather than via `tox` . If you have installed the development packages in your python environment via
`pip install -r requirements-dev.txt` , then `ruff` and `black` will be available and can be run from
the command line. See [`tox.ini` ](tox.ini ) for how `tox` invokes them.
2021-07-23 08:06:55 +08:00
2023-12-19 22:09:47 +08:00
## Building API docs locally
If you have made changes to the API documentation, you can run the command below
to build documentation locally to review the html output.
The easiest and recommended way to build the documentation is to use [**tox** ](https://tox.readthedocs.io/en/latest/# ):
```
tox -edocs
```
Once you run this command, the output will be located at `docs/_build/html` .
Then, open up the file `index.html` in your browser.
Sometimes Sphinx can get in a bad cache state. Run `tox -e docs-clean`
to reset Sphinx's cache.
2023-11-21 02:58:06 +08:00
## Development cycle
2019-06-08 02:53:10 +08:00
2023-11-21 02:58:06 +08:00
The development cycle for qiskit is all handled in the open using
2019-08-10 01:23:51 +08:00
the project boards in Github for project management. We use milestones
in Github to track work for specific releases. The features or other changes
that we want to include in a release will be tagged and discussed in Github.
As we're preparing a new release we'll document what has changed since the
2019-09-23 22:07:52 +08:00
previous version in the release notes.
2019-06-08 02:53:10 +08:00
2019-08-10 01:23:51 +08:00
### Branches
2019-06-08 02:53:10 +08:00
2021-04-21 00:30:16 +08:00
* `main` :
2019-06-08 02:53:10 +08:00
2023-11-21 02:58:06 +08:00
The main branch is used for development of the next version of qiskit.
2019-08-10 01:23:51 +08:00
It will be updated frequently and should not be considered stable. The API
2021-04-21 00:30:16 +08:00
can and will change on main as we introduce and refine new features.
2019-06-08 02:53:10 +08:00
2019-08-10 01:23:51 +08:00
* `stable/*` branches:
2023-11-21 02:58:06 +08:00
Branches under `stable/*` are used to maintain released versions of qiskit.
2019-08-10 01:23:51 +08:00
It contains the version of the code corresponding to the latest release for
that minor version on pypi. For example, stable/0.8 contains the code for the
0.8.2 release on pypi. The API on these branches are stable and the only changes
merged to it are bugfixes.
2019-06-08 02:53:10 +08:00
2019-08-10 01:23:51 +08:00
### Release cycle
2022-05-11 19:21:55 +08:00
In the lead up to a release there are a few things to keep in mind. Prior to
the release date there is a feature, removal, and deprecation proposal freeze
date. This date in each release cycle is the last day where a new PR adding a
new feature, removing something, or adding a new deprecation can be proposed (in
a ready for review state) for potential inclusion in the release. If a new
PR is opened after this date it will not be considered for inclusion in that
release. Note, that meeting these deadlines does not guarantee inclusion in a
release: they are preconditions. You can refer to the milestone page for each
release to see these dates for each release (for example for 0.21.0 the page is:
2023-11-21 02:58:06 +08:00
https://github.com/Qiskit/qiskit/milestone/23).
2022-05-11 19:21:55 +08:00
After the proposal freeze a release review period will begin, during this time
release candidate PRs will be reviewed as we finalize the feature set and merge
the last PRs for the release. Following the review period a release candidate will be
tagged and published. This release candidate is pre-release that enables users and
developers to test the release ahead of time. When the pre-release is tagged the release
automation will publish the pre-release to PyPI (but only get installed on user request),
create the `stable/*` branch, and generate a pre-release changelog/release page. At
this point the `main` opens up for development of the next release. The `stable/*`
branches should only receive changes in the form of bug fixes at this point. If there
is a need additional release candidates can be published from `stable/*` and when the
release is ready a full release will be tagged and published from `stable/*` .
2021-05-06 00:43:47 +08:00
2021-05-28 04:16:24 +08:00
## Adding deprecation warnings
2024-02-13 19:59:06 +08:00
The qiskit code is part of Qiskit and, therefore, the [Qiskit Deprecation Policy ](./DEPRECATION.md ) fully applies here. Additionally, qiskit does not allow `DeprecationWarning` s in its testsuite. If you are deprecating code, you should add a test to use the new/non-deprecated method (most of the time based on the existing test of the deprecated method) and alter the existing test to check that the deprecated method still works as expected, [using `assertWarns` ](https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertWarns ). The `assertWarns` context will silence the deprecation warning while checking that it raises.
2021-05-28 04:16:24 +08:00
For example, if `Obj.method1` is being deprecated in favour of `Obj.method2` , the existing test (or tests) for `method1` might look like this:
```python
def test_method1(self):
result = Obj.method1()
self.assertEqual(result, < expected > )
```
Deprecating `method1` means that `Obj.method1()` now raises a deprecation warning and the test will not pass. The existing test should be updated and a new test added for `method2` :
```python
def test_method1_deprecated(self):
with self.assertWarns(DeprecationWarning):
result = Obj.method1()
self.assertEqual(result, < expected > )
def test_method2(self):
result = Obj.method2()
self.assertEqual(result, < expected > )
```
2023-11-25 04:36:25 +08:00
`test_method1_deprecated` can be removed after `Obj.method1` is removed (following the [Qiskit Deprecation Policy ](./DEPRECATION.md )).
2021-05-28 04:16:24 +08:00
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
## Using dependencies
2023-11-21 02:58:06 +08:00
We distinguish between "requirements" and "optional dependencies" in qiskit.
A requirement is a package that is absolutely necessary for core functionality in qiskit, such as Numpy or Scipy.
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
An optional dependency is a package that is used for specialized functionality, which might not be needed by all users.
If a new feature has a new dependency, it is almost certainly optional.
### Adding a requirement
2023-11-21 02:58:06 +08:00
Any new requirement must have broad system support; it needs to be supported on all the Python versions and operating systems that qiskit supports.
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
It also cannot impose many version restrictions on other packages.
2023-11-21 02:58:06 +08:00
Users often install qiskit into virtual environments with many different packages in, and we need to ensure that neither we, nor any of our requirements, conflict with their other packages.
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
When adding a new requirement, you must add it to [`requirements.txt` ](requirements.txt ) with as loose a constraint on the allowed versions as possible.
### Adding an optional dependency
2023-11-21 02:58:06 +08:00
New features can also use optional dependencies, which might be used only in very limited parts of qiskit.
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
These are not required to use the rest of the package, and so should not be added to `requirements.txt` .
Instead, if several optional dependencies are grouped together to provide one feature, you can consider adding an "extra" to the package metadata, such as the `visualization` extra that installs Matplotlib and Seaborn (amongst others).
To do this, modify the [`setup.py` ](setup.py ) file, adding another entry in the `extras_require` keyword argument to `setup()` at the bottom of the file.
You do not need to be quite as accepting of all versions here, but it is still a good idea to be as permissive as you possibly can be.
You should also add a new "tester" to [`qiskit.utils.optionals` ](qiskit/utils/optionals.py ), for use in the next section.
### Checking for optionals
2023-11-21 02:58:06 +08:00
You cannot `import` an optional dependency at the top of a file, because if it is not installed, it will raise an error and qiskit will be unusable.
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
We also largely want to avoid importing packages until they are actually used; if we import a lot of packages during `import qiskit` , it becomes sluggish for the user if they have a large environment.
2024-02-13 19:59:06 +08:00
Instead, you should use [one of the "lazy testers" for optional dependencies ](https://docs.quantum.ibm.com/api/qiskit/utils#optional-dependency-checkers ), and import your optional dependency inside the function or class that uses it, as in the examples within that link.
Optimise `import qiskit` with lazy imports (#7525)
* Unify lazy handling of optional dependencies
This introduces new `HAS_X` variables for each of Qiskit's optional
dependencies, and provides a simple unified interface to them from
`qiskit.utils.optionals`. These objects lazily test for their
dependency when evaluated in a Boolean context, and have two `require_`
methods to unify the exception handling. `require_now` tests
immediately for the dependency and raises `MissingOptionalLibraryError`
if it is not present, and `require_in_call` is a decorator that lazily
tests for the dependencies when the function is called.
These remove the burden of raising nice exceptions from the usage
points; a function marked `HAS_MATPLOTLIB.require_in_call` can now
safely `import matplotlib` without special handling, for example. This
also provides a unified way for consumers of `qiskit` (such as the test
suite) to query the presence of libraries.
All tests are now lazy, and imports are moved to the point of usage, not
the point of import of the module. This means that `import qiskit` is
significantly faster for people who have many of the optional
dependencies installed; rather than them all being loaded at initial
import just to test their presence, they will now be loaded on demand.
* Optimise time taken for `import qiskit`
This makes several imports lazy, only being imported when they are
actually called and used. In particular, no component of `scipy` is
imported during `import qiskit` now, nor is `pkg_resources` (which is
surprisingly heavy).
No changes were made to algorithms or opflow, since these are not
immediately imported during `import qiskit`, and likely require more
significant work than the rest of the library.
* Import missing to-be-deprecated names
* Convert straggler tests to require_now
* Correct requirements in test cases
* Add `require_in_instance` class decorator
Effectively this is just a wrapper around `__init__`, except that this
class-decorator form will do the right thing even if `__init__` isn't
explicitly defined on the given class.
The implementation of `wrap_method` is a replacement for the older
`test.decorators._wrap_method`, which didn't handle all the possible
special cases as well, and messed up the documentation of its wrapped
functions. That wasn't so important when it was just a private
function, but now it has become public (so that
`test.decorators.enforce_subclasses_call` can still use it from
`qiskit.utils`), it needed reworking to be more polished.
* Privatise non-public names rather than del
* Add tests of `require_in_instance`
* Fix typos in documentation
* Add section on requirements to CONTRIBUTING
* Update documentation on HoareOptimizer error
* Remove UK localisation
* Mention more uses of PIL in documentation
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
2022-02-02 20:31:34 +08:00
Very lightweight _requirements_ can be imported at the tops of files, but even this should be limited; it's always ok to `import numpy` , but Scipy modules are relatively heavy, so only import them within functions that use them.
2021-05-06 00:43:47 +08:00
## Dealing with the git blame ignore list
2023-11-21 02:58:06 +08:00
In the qiskit repository we maintain a list of commits for git blame
2021-05-06 00:43:47 +08:00
to ignore. This is mostly commits that are code style changes that don't
change the functionality but just change the code formatting (for example,
when we migrated to use black for code formatting). This file,
`.git-blame-ignore-revs` just contains a list of commit SHA1s you can tell git
to ignore when using the `git blame` command. This can be done one time
with something like
```
git blame --ignore-revs-file .git-blame-ignore-revs qiskit/version.py
```
from the root of the repository. If you'd like to enable this by default you
can update your local repository's configuration with:
```
git config blame.ignoreRevsFile .git-blame-ignore-revs
```
which will update your local repositories configuration to use the ignore list
by default.
