Contribute a tutorial
Qiskit tutorials on IBM Quantum® Platform are open to community contributions. This page explains which tutorials you can contribute, what each kind of tutorial must show, and how to propose one.
Every tutorial belongs to a domain (optimization, Hamiltonian simulation, quantum machine learning, or quantum information science) and is either Foundational or Applied:
- Foundational tutorials teach the core ideas and canonical methods of a domain. They use well-known teaching problems, so that the method is the focus rather than the problem.
- Applied tutorials are built around a specific goal: solving a particular problem from the working-group problem classes, or applying a specialized technique or tool in the setting where it can be used successfully. They assume strong familiarity with the fundamentals.
What you can contribute
Domain | Foundational tutorials | Applied tutorials |
|---|---|---|
| Optimization | Written by the IBM Quantum team | 10 problem classes |
| Hamiltonian simulation | Written by the IBM Quantum team | 10 problem classes |
| Quantum machine learning | 1 open topic | 7 problem classes |
| Quantum information science | 4 open topics | Written by the IBM Quantum team |
The following are out of scope:
- Foundational optimization and Hamiltonian simulation tutorials, so that contributions in those domains go to the problem classes.
- Applied quantum information science tutorials, which usually build on IBM tools in active development.
- Content that duplicates an IBM Quantum Learning course or an existing tutorial. To improve an existing tutorial, open a pull request against it instead.
Requirements
Every tutorial must:
- Follow the tutorial template, and use current Qiskit with no deprecated interfaces.
- Use only the approved quantum packages, pin every package version, and keep custom code in the notebook.
- Verify a small instance against a known answer (exact, analytic, or published) within a stated tolerance before scaling up.
- Run on IBM Quantum hardware through the Qiskit Runtime primitives, and report the error mitigation settings and QPU time.
Foundational and Applied tutorials also have their own requirements:
Requirement | Foundational | Applied |
|---|---|---|
| Scope | An open topic, taught on the topic's teaching problem | A real instance from a problem class, reporting the class's target quantity |
| Value | The method is a step in the Applied tutorial or problem class listed for the topic, which the "Next steps" section links to | State of the art, meeting at least two of: a peer-reviewed paper from the past three years, the largest hardware demonstration of its problem, or advanced features such as dynamic circuits |
| Hardware run | About 50 qubits or more | At least 50 qubits and a two-qubit depth of 50 (smaller only if clearly state of the art), reproducible within its error bars on any current-generation backend |
| Compared against | A default or naive approach, showing how cost, noise sensitivity, or accuracy changes with size | A classical method on the same instance, such as an exact or heuristic solver, a tensor network method, or a matched classical model |
Each problem class accepts one community tutorial per method family. A new tutorial in a family that already has one replaces it only if it does better on scale, accuracy, or QPU cost.
Qiskit Functions are welcome in any tutorial. A tutorial built around a vendor's Qiskit Function counts as Applied, but a Foundational tutorial can use a Function as one step of its workflow.
Approved quantum packages
The IBM Quantum team maintains this list. Install approved packages from PyPI, or from GitHub pinned to a release tag where the list says so. Classical packages, such as NumPy and SciPy, must be published on PyPI. To request a package that is not on the list, name it in your proposal and explain why you need it.
Area | Packages |
|---|---|
| Qiskit and IBM Quantum services | qiskit, qiskit-ibm-runtime, qiskit-aer, qiskit-serverless, qrmi |
| Compilation | qiskit-ibm-transpiler, qiskit-basis-constructor |
| Qiskit addons | qiskit-addon-aqc-tensor, qiskit-addon-cutting, qiskit-addon-mpf, qiskit-addon-obp, qiskit-addon-opt-mapper, qiskit-addon-pna, qiskit-addon-slc, qiskit-addon-sqd, qiskit-addon-utils |
| Error mitigation and noise | samplomatic, qiskit-mitigation, qiskit-noise-learning, qiskit-paulice, mthree |
| Benchmarking and characterization | qiskit-experiments, gem-suite, qiskit-device-benchmarking (from GitHub) |
| Simulation, chemistry, and optimization | ffsim, qiskit-fermions, pauli-prop, qaoa_training_pipeline (from GitHub) |
| Qiskit Functions | qiskit-ibm-catalog, plus any client package that a Function's provider requires, such as qctrl-visualizer or luna-model |
Open topics and problem classes
For each domain, this section lists the teaching problem and open topics for Foundational tutorials, and the problem classes for Applied tutorials. The working groups use these problem classes to track progress toward quantum advantage. To propose a problem class, or a quantum machine learning or quantum information science topic that is not listed, open a proposal and explain the gap it fills.
Optimization
Foundational tutorials use max-cut as the teaching problem. They are written by the IBM Quantum team, so community contributions target the problem classes below.
Applied tutorials target one of the ten problem classes in the Quantum Optimization Benchmarking Library (QOBLIB):
Problem class | Description | Existing tutorials |
|---|---|---|
| Market split | Multi-dimensional subset sum | Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer Solve the market split problem with the ParityQC Parity Twine Optimizer |
| Low autocorrelation binary sequences | Radar and communications sequence design | None yet |
| Minimum Birkhoff decomposition | Doubly stochastic matrix decomposition | None yet |
| Steiner tree packing | VLSI design and wire routing | None yet |
| Sports tournament scheduling | Constraint satisfaction | None yet |
| Portfolio optimization | Multi-period portfolios with transaction costs and short selling | Dynamic portfolio optimization with Global Data Quantum's Portfolio Optimizer |
| Maximum independent set | Unweighted maximum independent set on graphs | Find the maximum independent set with Aqarios Constrained Quantum Optimizer |
| Network design | Telecommunications network planning | None yet |
| Vehicle routing | Vehicle routing with time windows and knapsack constraints | None yet |
| Topology design | Graph golf (the degree-diameter problem) | None yet |
Hamiltonian simulation
Foundational tutorials use one of two teaching problems: the N2 molecule in a minimal basis for chemistry, or the one-dimensional Heisenberg or Ising chain for spin and lattice models. They are written by the IBM Quantum team, so community contributions target the problem classes below.
Applied tutorials target one of the following problem classes:
Problem class | Target quantity | Existing tutorials |
|---|---|---|
| Strongly correlated molecular ground states | Ground-state energy across geometries | Sample-based quantum diagonalization of a chemistry Hamiltonian (one geometry) Dissociation PES curves with Qunova HiVQE |
| Nuclear shell-model ground states | Ground-state energy | Pooled sample-based quantum diagonalization of a nuclear Hamiltonian |
| Electron-phonon dynamics | Polaron quench dynamics | None yet |
| Lattice gauge real-time dynamics | String-breaking and hadron dynamics | Observation of robust and coherent non-Abelian hadron dynamics on noisy quantum processors |
| SYK scrambling (long-term target) | Out-of-time-order correlators and spectral form factor | None yet |
| Frustrated magnets | Ground-state and finite-temperature observables | None yet |
| Kicked and Floquet spin dynamics | Quench observables | Simulation of kicked Ising Hamiltonian with dynamic circuits Transverse-Field Ising Model with Q-CTRL's Performance Management Simulate 2D tilted-field Ising with the QESEM function Simulate a kicked Ising model with the TEM function |
| Symmetric spin dynamics | Dynamical structure factor | Simulate neutron scattering in quantum materials with quantum circuits Simulate neutron scattering with an AQC + Trotter dynamics Serverless workflow |
| Doped 2D Fermi-Hubbard dynamics | Charge and spin quench dynamics | None yet |
| Quantum impurity models | Impurity Green's function | Sample-based Krylov quantum diagonalization of a fermionic lattice model (ground state only) |
Quantum machine learning
Foundational tutorials use a small classification dataset with a classical baseline as the teaching problem. One Foundational topic is open:
Open topic | Leads to |
|---|---|
| Training and evaluating a quantum kernel classifier on a small dataset, with a classical baseline | Classification problem classes |
Applied tutorials target one of the following problem classes:
Problem class | Target quantity | Existing tutorials |
|---|---|---|
| Quantum phase classification | Test accuracy versus sample count | None yet |
| Quantum property prediction | Samples needed to reach a target error | None yet |
| Hamiltonian learning | Parameter error versus samples | None yet |
| Generative learning of hard distributions | Sampling fidelity or cross-entropy | None yet |
| Group-structured classification | Test accuracy | None yet |
| Quantum reservoir and extreme learning | Prediction error or test accuracy | None yet |
| Real-world tabular classification | Accuracy versus a matched classical model | Enhance feature classification using projected quantum kernels Hybrid quantum-enhanced ensemble classification (grid stability workflow) |
Quantum information science
Quantum information science has no problem classes, and its Applied tutorials are written by the IBM Quantum team. Foundational tutorials are open for the following topics only, and each topic names its own teaching problem.
Open topic | Teaching problem | Leads to |
|---|---|---|
| Phase estimation at scale without vendor tools, for example iterative phase estimation with dynamic circuits | The one-dimensional transverse-field Ising chain, whose energies are known exactly | Energy estimation in Hamiltonian simulation |
| Device benchmarking with cross-entropy benchmarking and random circuit sampling | Random circuits, simulated exactly at small sizes | Quantum advantage experiments |
| Error correction beyond the repetition code, such as syndrome extraction with dynamic circuits | A small stabilizer code, such as the Steane code or the distance-3 surface code | Low-overhead error detection with spacetime codes |
| Fidelity estimation and certification of large entangled states | GHZ and graph states | Learning and certifying quantum states |
How to propose a tutorial
Contributions go through two stages, so that you get feedback before you write the full tutorial.
- Propose. Open a tutorial proposal issue in the Qiskit documentation repository. Proposals are public, so you can check what others are already working on. The IBM Quantum tutorials team reviews each proposal against these requirements, and a member of the relevant working group reviews the technical content.
- Submit. After your proposal is approved, open a pull request from your fork that adds the notebook. Follow the contributing guide, including signing the Contributor License Agreement.
Authorship and maintenance
- Credit. Contributed tutorials show a byline at the top with the authors' names and affiliations and a link to the source paper. Tutorial cards show a community tag.
- Maintainer of record. Each contributed tutorial also has a maintainer of record from the IBM Quantum team, who keeps it running as Qiskit changes.
- Breaking changes. If a change breaks the tutorial, the authors have 30 days to respond to the issue. If it is still unresolved after the next major Qiskit release, the tutorial is archived.
- Existing community tutorials. These requirements apply to new contributions. Community tutorials that are already published get the community tag, and are held to these requirements when they are next updated.