# Qiskit Bosons

> Qiskit Bosons extends Qiskit with tools for working with bosonic systems: a bosonic operator data structure, a framework and library for encoding bosonic operators as qubit operators, and a framework and library for synthesizing bosonic quantum circuits, integrated into Qiskit's transpiler pipeline. The core is written in Rust and exposed through a first-party Python API.


2026, Qiskit addons team

## Pages

- [Qiskit Bosons](index.html.md): Overview of Qiskit Bosons, an extension of the Qiskit SDK for bosonic systems: a bosonic operator data structure, boson-to-qubit encodings with a choice of truncation, bosonic circuits, and a transpilation pipeline with boson-to-boson and boson-to-qubit stages that turns them into qubit circuits.
- [Installation instructions](install.html.md): Prerequisites for building Qiskit Bosons from source and a pointer to the installation instructions for the Python API. A C API is not available yet.
- [Install the Python API](install-py.html.md): Install the Qiskit Bosons Python package from PyPI with pip, or from source for development, and how to verify and test the installation.
- [Overview](guides/overview.html.md): Overview of the Qiskit Bosons guides, grouped by topic, with links to each one.
- [Simulate Bose-Hubbard dynamics with a choice of encoding](guides/bose_hubbard.html.md): End-to-end tutorial for the time dynamics of the one-dimensional Bose-Hubbard model: build the circuit on bosonic modes, defer the truncation and the boson-to-qubit encoding to transpile time, and check the evolved site densities against an exact reference.
- [More guides](guides/index.html.md): Table of contents of all Qiskit Bosons guides.
- [Design principles of operator representations](guides/operators.html.md): Design principles of the BosonOperator in qiskit_bosons.operators: exact sums of ladder-operator products with no occupation cutoff, how to build, inspect, and combine operators, and how to compare two of them.
- [Group operator terms: use the operator structure](guides/grouping.html.md): How to assign group indices to the terms of a BosonOperator, check that each group is Hermitian or has uniform coefficients, and lay out the operator so that picking a few groups stays cheap.
- [Map operator representations](guides/mappers.html.md): How to map a BosonOperator to a qubit operator with the occupation encoding: truncate the Fock space, choose a level encoding, and understand what each choice costs.
- [Work with bosonic circuits](guides/circuit.html.md): How to build, compose, and repeat a BosonicCircuit, which expresses a computation on bosonic modes with no truncation, encoding, or qubit count, so that one circuit can be lowered under several encodings.
- [Rotate bosonic modes](guides/mode_rotation.html.md): How to mix bosonic modes with a ModeRotation gate, the passive linear-optics transformation of a beamsplitter and phase-shifter network, and how to decompose it with the Clements mesh or map it to qubits directly.
- [Transpile bosonic circuits](guides/transpilation.html.md): How to transpile a BosonicCircuit to a qubit QuantumCircuit, where the truncation and the encoding are chosen, through the stages of the bosonic transpiler pipeline.
- [Synthesize an Evolution gate in bosonic space](guides/bosonic_synthesis.html.md): How to synthesize an Evolution gate into smaller bosonic gates with product formulas (Trotter and qDRIFT) before any truncation or encoding is chosen, on one gate or across a whole circuit, and why this reduces the error between non-commuting groups.
- [`qiskit-bosons` Python API reference](pydoc/index.html.md): Reference for the Python API of qiskit-bosons, covering operators, mappers, circuits, the transpiler, linear algebra, protocols, and utilities.
- [Operator Representations](pydoc/qiskit_bosons.operators.html.md): The BosonOperator, an exact sum of products of bosonic creation and annihilation operators with no occupation cutoff, and the cre and ann helpers that build its terms.
- [OperatorTrait](stubs/qiskit_bosons.operators.OperatorTrait.html.md): A protocol indicating all methods implemented by operator classes.
- [BosonAction](stubs/qiskit_bosons.operators.boson_action.BosonAction.html.md): A bosonic creation or annihilation action.
- [BosonOperator](stubs/qiskit_bosons.operators.BosonOperator.html.md): A bosonic operator.
- [cre](stubs/qiskit_bosons.operators.cre.html.md): Constructs a creation action on the bosonic mode at `mode`.
- [ann](stubs/qiskit_bosons.operators.ann.html.md): Constructs an annihilation action on the bosonic mode at `mode`.
- [Operator Library](pydoc/qiskit_bosons.operators.library.html.md): Library of helpers for building bosonic operators, such as the commutator, anti-commutator, and double commutator, and the position and momentum quadratures.
- [commutator](stubs/qiskit_bosons.operators.library.commutator.html.md): Computes the commutator of two operators.
- [anti_commutator](stubs/qiskit_bosons.operators.library.anti_commutator.html.md): Computes the anti-commutator of two operators.
- [double_commutator](stubs/qiskit_bosons.operators.library.double_commutator.html.md): Computes the double-commutator of three operators.
- [position](stubs/qiskit_bosons.operators.library.position.html.md): Builds the dimensionless position (quadrature) operator of a single mode.
- [momentum](stubs/qiskit_bosons.operators.library.momentum.html.md): Builds the dimensionless momentum (quadrature) operator of a single mode.
- [Operator Terms](pydoc/qiskit_bosons.operators.terms.html.md): Routines that operate on the individual terms of an operator, to analyze a grouping, filter diagonal terms, and order them canonically.
- [group_coeff_means](stubs/qiskit_bosons.operators.terms.group_coeff_means.html.md): Returns the mean absolute coefficient magnitude of each group.
- [groups_are_hermitian](stubs/qiskit_bosons.operators.terms.groups_are_hermitian.html.md): Returns, for each group, whether the operator formed by that group’s terms is Hermitian.
- [groups_have_uniform_coeffs](stubs/qiskit_bosons.operators.terms.groups_have_uniform_coeffs.html.md): Returns, for each group, whether all of its coefficients are numerically equal.
- [filter_diagonal_terms](stubs/qiskit_bosons.operators.terms.filter_diagonal_terms.html.md): Filters out the terms of an operator that are diagonal in the occupation-number basis.
- [canonical_order](stubs/qiskit_bosons.operators.terms.canonical_order.html.md): Returns a copy of an operator with its terms sorted into a canonical order.
- [group_order](stubs/qiskit_bosons.operators.terms.group_order.html.md): Returns a copy of an operator with its terms ordered by group index.
- [order_terms](stubs/qiskit_bosons.operators.terms.order_terms.html.md): Returns a copy of an operator with its terms reordered by a user-provided key.
- [Representation Mappers](pydoc/qiskit_bosons.mappers.html.md): Framework for implementing custom boson-to-qubit mappers, plus the LevelEncoding and LevelSpec classes that describe the truncation of each mode and how its levels are laid out on qubits.
- [LevelEncoding](stubs/qiskit_bosons.mappers.LevelEncoding.html.md): The layout of the levels of a single system on qubits.
- [LevelSpec](stubs/qiskit_bosons.mappers.LevelSpec.html.md): The truncation of a register of bosonic modes and the encoding that lays it out on qubits.
- [map_boson_action_generators](stubs/qiskit_bosons.mappers.map_boson_action_generators.html.md): Map a `BosonOperator` to another operator type.
- [Mapper Library](pydoc/qiskit_bosons.mappers.library.html.md): Library of boson-to-qubit mappers, namely the occupation encoding, which truncates each mode of a BosonOperator and lays its levels out on qubits.
- [occupation_encoding](stubs/qiskit_bosons.mappers.library.occupation_encoding.html.md): Map a `BosonOperator` to a `SparseObservable`.
- [Circuit Representation](pydoc/qiskit_bosons.circuit.html.md): The BosonicCircuit and BosonicGate classes for expressing circuits on bosonic modes instead of qubits, plus type aliases that document this re-interpretation of Qiskit's circuit types.
- [BosonicDAGCircuit](stubs/qiskit_bosons.circuit.BosonicDAGCircuit.html.md): A type alias of `DAGCircuit`.
- [BosonicMode](stubs/qiskit_bosons.circuit.BosonicMode.html.md): A type alias of `Qubit`.
- [BosonicRegister](stubs/qiskit_bosons.circuit.BosonicRegister.html.md): A type alias of `QubitRegister`.
- [BosonicSpecifier](stubs/qiskit_bosons.circuit.BosonicSpecifier.html.md): A type alias equivalent to Qiskit’s `QubitSpecifier` but for bosonic modes.
- [BosonicCircuit](stubs/qiskit_bosons.circuit.BosonicCircuit.html.md): A wrapper around `QuantumCircuit` for expressing bosonic circuits.
- [BosonicGate](stubs/qiskit_bosons.circuit.BosonicGate.html.md): The base class for all bosonic gates.
- [Circuit Library](pydoc/qiskit_bosons.circuit.library.html.md): Library of bosonic gates, such as time evolution, mode initialization, and passive mode rotations.
- [InitializeModes](stubs/qiskit_bosons.circuit.library.InitializeModes.html.md): Prepares a bosonic Fock state.
- [ModeRotation](stubs/qiskit_bosons.circuit.library.ModeRotation.html.md): Implements a passive linear-optical mode transformation.
- [Evolution](stubs/qiskit_bosons.circuit.library.Evolution.html.md): Implements the time evolution of a bosonic operator.
- [Circuit Library Synthesis (`B2B`)](pydoc/qiskit_bosons.circuit.library.synthesis.html.md): Boson-to-boson synthesis methods that break a gate down into smaller bosonic gates, such as Trotter and qDRIFT formulas for an Evolution gate and the Clements decomposition of a ModeRotation gate, plus the B2BSynthesisPlugin interface for custom methods, which the B2BSynthesis transpiler pass applies.
- [B2BSynthesisPlugin](stubs/qiskit_bosons.circuit.library.synthesis.B2BSynthesisPlugin.html.md): The protocol for plugins to the `B2BSynthesis` transpiler pass.
- [B2BSynthesisPluginManager](stubs/qiskit_bosons.circuit.library.synthesis.B2BSynthesisPluginManager.html.md): A simple manager of the installed boson-to-boson synthesis plugins.
- [BosonicLieTrotter](stubs/qiskit_bosons.circuit.library.synthesis.BosonicLieTrotter.html.md): The first-order Lie-Trotter product formula, applied in bosonic space.
- [BosonicSuzukiTrotter](stubs/qiskit_bosons.circuit.library.synthesis.BosonicSuzukiTrotter.html.md): The higher-order Suzuki-Trotter product formula, applied in bosonic space.
- [BosonicQDrift](stubs/qiskit_bosons.circuit.library.synthesis.BosonicQDrift.html.md): A synthesis method that Trotterizes an `Evolution` via the qDRIFT protocol.
- [BosonicClementsDecomposition](stubs/qiskit_bosons.circuit.library.synthesis.BosonicClementsDecomposition.html.md): The decomposition of a mode rotation into a mesh of two-mode rotations and phases.
- [QDriftSampler](stubs/qiskit_bosons.circuit.library.synthesis.QDriftSampler.html.md): The draws of the qDRIFT protocol for one `Evolution` gate.
- [Transpiler](pydoc/qiskit_bosons.transpiler.html.md): How Qiskit Bosons transpiles a BosonicCircuit to a QuantumCircuit: the transpilation stages, the pass manager, and the layout of bosonic modes onto qubits.
- [B2QLayout](stubs/qiskit_bosons.transpiler.B2QLayout.html.md): A mapping of bosonic mode registers to quantum registers.
- [BosonicPassManager](stubs/qiskit_bosons.transpiler.BosonicPassManager.html.md): A transpiler pass manager converting one `BosonicCircuit` to another.
- [BosonicCircuitToDAG](stubs/qiskit_bosons.transpiler.BosonicCircuitToDAG.html.md): Converts a `BosonicCircuit` to a `BosonicDAGCircuit`.
- [BosonicDAGToCircuit](stubs/qiskit_bosons.transpiler.BosonicDAGToCircuit.html.md): Converts a `BosonicDAGCircuit` to a `BosonicCircuit`.
- [QuantumDAGToCircuit](stubs/qiskit_bosons.transpiler.QuantumDAGToCircuit.html.md): Converts a `DAGCircuit` to a `QuantumCircuit`.
- [Transpiler Passes](pydoc/qiskit_bosons.transpiler.passes.html.md): Transpiler passes for each stage of the bosonic pipeline: optimization of bosonic circuits, layout of bosonic modes onto qubits, and boson-to-qubit synthesis.
- [B2BSynthesis](stubs/qiskit_bosons.transpiler.passes.B2BSynthesis.html.md): A transpilation pass breaking gates down into smaller ones in bosonic space.
- [B2BSynthesisConfig](stubs/qiskit_bosons.transpiler.passes.optimization.b2b_synthesis.B2BSynthesisConfig.html.md): The dictionary type used to configure the `B2BSynthesis.methods`.
- [MergeEvolutions](stubs/qiskit_bosons.transpiler.passes.MergeEvolutions.html.md): A transpilation pass merging consecutive `Evolution` gates of the same operator.
- [RelabelModes](stubs/qiskit_bosons.transpiler.passes.RelabelModes.html.md): A transpilation pass to relabel the bosonic modes.
- [CustomB2QLayout](stubs/qiskit_bosons.transpiler.passes.CustomB2QLayout.html.md): Sets the user-provided `B2QLayout` in the transpiler.
- [OccupationB2QLayout](stubs/qiskit_bosons.transpiler.passes.OccupationB2QLayout.html.md): Maps bosonic modes to the qubits a `LevelSpec` assigns them.
- [B2QSynthesis](stubs/qiskit_bosons.transpiler.passes.B2QSynthesis.html.md): A transpilation pass to map boson-based circuit instructions to qubit-based ones.
- [B2QSynthesisConfig](stubs/qiskit_bosons.transpiler.passes.synthesis.b2q_synthesis.B2QSynthesisConfig.html.md): The dictionary type used to configure the `B2QSynthesis.methods`.
- [Transpiler Pass Synthesis (`B2Q`)](pydoc/qiskit_bosons.transpiler.passes.synthesis.html.md): Boson-to-qubit synthesis plugins that the B2QSynthesis transpiler pass applies, such as the mapper-based Evolution synthesis, plus the B2QSynthesisPlugin interface for custom plugins.
- [B2QSynthesisPlugin](stubs/qiskit_bosons.transpiler.passes.synthesis.B2QSynthesisPlugin.html.md): The protocol for plugins to the `B2QSynthesis` transpiler pass.
- [B2QSynthesisPluginManager](stubs/qiskit_bosons.transpiler.passes.synthesis.B2QSynthesisPluginManager.html.md): A simple manager of the installed boson-to-qubit synthesis plugins.
- [MapperFnEvolutionSynthesis](stubs/qiskit_bosons.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.html.md): A `B2QSynthesisPlugin` for transpiling `Evolution` under a custom mapping.
- [OccupationInitializeModesSynthesis](stubs/qiskit_bosons.transpiler.passes.synthesis.OccupationInitializeModesSynthesis.html.md): A `B2QSynthesisPlugin` for transpiling `InitializeModes`.
- [group_wise](stubs/qiskit_bosons.transpiler.passes.synthesis.group_wise.html.md): Wraps a mapper function so that it maps an operator one group at a time.
- [simplify](stubs/qiskit_bosons.transpiler.passes.synthesis.simplify.html.md): Wraps a mapper function so that it simplifies the operator it returns.
- [Transpiler Pass Utilities](pydoc/qiskit_bosons.transpiler.passes.utils.html.md): Convenience functions for implementing custom transpiler passes.
- [map_node_single_register](stubs/qiskit_bosons.transpiler.passes.utils.map_node_single_register.html.md): Map the single bosonic mode register acted upon by the circuit operation.
- [Transpiler Presets](pydoc/qiskit_bosons.transpiler.presets.html.md): Preset pass managers that transpile a BosonicCircuit to a QuantumCircuit with the occupation encoding.
- [generate_preset_occupation_pass_manager](stubs/qiskit_bosons.transpiler.presets.generate_preset_occupation_pass_manager.html.md): Generates a preset transpiler pipeline for the occupation basis, from a `LevelSpec`.
- [Linear Algebra Utilities](pydoc/qiskit_bosons.linalg.html.md): Linear algebra utilities, such as the Givens decomposition of a unitary matrix.
- [givens_decomposition](stubs/qiskit_bosons.linalg.givens_decomposition.html.md): Decomposes a unitary matrix into Givens rotations and diagonal phases.
- [Protocols](pydoc/qiskit_bosons.protocols.html.md): Protocols that a class can satisfy structurally to be usable throughout the package, such as SupportsCommutators.
- [SupportsCommutators](stubs/qiskit_bosons.protocols.SupportsCommutators.html.md): A Protocol indicating support for efficient commutator generation.
- [Release Notes](release-notes.html.md): Release notes of Qiskit Bosons for each release.