Base Classes#

For extendability and modularity purposes, qlbm provides several base classes with interfaces that aim to make the development of novel QLBM methods easier. This page documents the base classes that have to do with the register setup and quantum circuit generation. The architecture of the inheritance hierarchy is two-fold: vertically based on specificity (i.e., more specialized classes for specific QLBMs) and horizontally based on methods (i.e., different implementations for different QLBMs).

Lattice Base#

class qlbm.lattice.lattices.base.Lattice(lattice_data, logger=<Logger qlbm (WARNING)>)[source]#

Base class for all algorithm-specific Lattices.

A Lattice object performs the following functions:

Parse high-level input from JSON files or Python dictionaries into appropriate quantum registers and other information used to infer quantum circuits.
Validate the soundness of the input information and raise warnings if algorithmic assumptions are violated.
Provide parameterized inputs for the inference of quantum circuits that comprise QLBMs.

The inheritance structure of Lattices is such that each QLBM uses a specialized implementation of this base class. This allows the same parsing procedures to be used for all algorithms, while additional validity checks can be built on top. All Lattice objects share the following attributes:

Attribute	Summary
`num_dims`	The number of dimensions of the lattice.
`num_gridpoints`	The number of gridpoints in each dimension.
`num_grid_qubits`	The total number of qubits required to encode the grid.
`num_velocities`	The number of discrete velocities in each dimension.
`num_velocity_qubits`	The total number of qubits required to encode the velocity discretization of the lattice.
`num_ancilla_qubits`	The total number of ancllary qubits required for the quantum circuit to simulate this lattice.
`num_total_qubits`	The total number of qubits required for the quantum circuit to simulate the lattice.
`registers`	The qubit registers of the quantum algorithm.
`circuit`	The blueprint quantum circuit for all components of the algorithm.
`discretization`	The discretization of the lattice, as an enum value of `LatticeDiscretization`.
`shapes`	A list of the solid geometry objects.
`logger`	The performance logger.

A lattice can be constructed from from either an input file or a Python dictionary. A sample configuration might look as follows:

{
    "lattice": {
        "dim": {
            "x": 16,
            "y": 16
        },
        "velocities": {
            "x": 4,
            "y": 4
        }
    },
    "geometry": [
        {
            "x": [9, 12],
            "y": [3, 6],
            "boundary": "specular"
        },
        {
            "x": [9, 12],
            "y": [9, 12],
            "boundary": "bounceback"
        }
    ]
}

Parameters:

lattice_data (str | Dict)
logger (Logger)

num_dims: int#: The number of dimensions of the system.

num_gridpoints: List[int]#: The number of gridpoints of the lattice in each dimension.

Warning

For easier compatibility with binary arithmetic, the number of gridpoints specified in the input dictionary is one larger than the one held in the Lattice s. That is, for a \(16 \times 64\) lattice, the num_gridpoints attribute will have the value [15, 63].

num_velocities: List[int]#: The number of velocities in each dimension. This will be refactored in the future to support \(D_dQ_q\) discretizations.

Warning

For easier compatibility with binary arithmetic, the number of velocities specified in the input dictionary is one larger than the one held in the Lattice s. If the numbers of discrete velocities are \(4\) and \(2\), the num_velocities attribute will have the value [3, 1].

num_grid_qubits: int#: The number of qubits required to encode the grid.

num_velocity_qubits: int#: The number of qubits required to encode the velocity discretization of the lattice.

num_ancilla_qubits: int#: The number of ancilla (non-velocity, non-grid) qubits required for the quantum circuit to simulate this lattice.

num_total_qubits: int#: The total number of qubits required for the quantum circuit to simulate the lattice. This is the sum of the number of grid, velocity, and ancilla qubits.

velocity_register: Tuple[QuantumRegister, ...]#: A tuple that holds registers responsible for specific operations of the QLBM algorithm.

circuit: QuantumCircuit#: An empty qiskit.QuantumCircuit with labeled registers that quantum components use as a base. Each quantum component that is parameterized by a Lattice makes a copy of this quantum circuit to which it appends its designated logic.

shapes: Dict[str, List[Shape]]#: Contains all of the Shape`s encoding the solid geometry of the lattice. The key of the dictionary is the specific kind of boundary condition of the obstacle (i.e., `”bounceback”`` or "specular").

register: Tuple[List[QuantumRegister], ...] = <bound method ABCMeta.register of <class 'qlbm.lattice.lattices.base.Lattice'>>#: A tuple of lists of qiskit.QuantumRegister s that are used to store the quantum information of the lattice.

discretization: LatticeDiscretization#: The discretization of the lattice, as an enum value of LatticeDiscretization.

logger: Logger#: The performance logger, by default getLogger("qlbm").

parse_input_data(lattice_data, compressed_grid=True)[source]#

Parses the lattice input data, provided in either a file path or a dictionary.

Parameters:

lattice_data (str | Dict) – Either a file path to read a JSON-formatted specification from, or a dictionary formatted as in the main class description.
compressed_grid (bool) – Whether the grid data is compressed into logarithmically many qubits.

Returns:

A tuple containing (i) a list of the number of gridpoints per dimension, (ii) a list of the number of velicities per dimension, (iii) a dictionary containing the solid Shapes, and (iv) the discretization enum of the lattice. The key of the dictionary is the specific kind of boundary condition of the obstacle (i.e., "bounceback" or "specular").

Return type:

Tuple[List[int], List[int], Dict[str, List[Shape]], LatticeDiscretization]

Raises:

LatticeException – If the specification violates any algorithmic assumptions.

parse_geometry_dict(geometry_list)[source]#

Parses the ‘geometry’ section of the lattice specification.

Parameters:: geometry_list (List[Dict]) – A list of the geometry components. See demos for concrete examples.
Returns:: A dictionary where keys consist of boundary conditions (specular or bounceback) and entries consists of all shapes of that boundary condition.
Return type:: Dict[str, List[Shape]]

to_json()[source]#

Serialize the lattice specification to JSON format.

Returns:: The JSON representation of the lattice.
Return type:: str

abstract get_registers()[source]#

Generates the registers on which the quantum circuits will be placed.

Returns:: A fixed number of registers according to the lattice specification.
Return type:: Tuple[List[QuantumRegister], …]

abstract logger_name()[source]#

An identifiable name to be used in the logger to help with benchmarking and analysis.

Returns:: A string that can be used to sufficiently identify the lattice specification.
Return type:: str

abstract has_multiple_geometries()[source]#

Whether multiple lattice geometries are simulated simultaneously.

Returns:: Whether multiple lattice geometries are simulated simultaneously.
Return type:: bool

class qlbm.lattice.geometry.shapes.base.Shape(num_grid_qubits, boundary_condition)[source]#

Base class for all geometrical shapes.

Parameters:

num_grid_qubits (List[int])
boundary_condition (str)

abstract stl_mesh()[source]#

Provides the stl representation of the shape.

Returns:: The mesh representing the shape.
Return type:: stl.mesh.Mesh

abstract to_json()[source]#

Serializes the shape to JSON format.

Returns:: The JSON representation of the shape.
Return type:: str

abstract to_dict()[source]#

Produces a dictionary representation of the shape.

Returns:: A dictionary representation of the bounds and boundary conditions of the shape.
Return type:: Dict[str, List[int] | str]

Components Base#

class qlbm.components.base.QuantumComponent(logger=<Logger qlbm (WARNING)>)[source]#

Base class for all quantum circuits implementing QLBM functionality.

This class wraps a qiskit.QuantumCircuit object constructed through the parameters supplied to the constructor. The create_circuit() is automatically called at construct time and its output is stored in the circuit attribute. All quantum components have an implementation of the create_circuit() method which builds their specialized quantum circuits.

Attribute	Summary
`circuit`	The `qiskit.QuantumCircuit` of the component.
`logger`	The performance logger, by default `getLogger("qlbm")`

Parameters:: logger (Logger)

abstract create_circuit()[source]#

Creates the qiskit.QuantumCircuit of this object.

This method is called automatically at construction time for all quantum components.

Returns:: The generated QuantumCircuit.
Return type:: QuantumCircuit

width()[source]#

Return the number of qubits plus clbits in the circuit.

Returns:: Width of circuit.
Return type:: int

size()[source]#

Returns the total number of instructions (gates) in the circuit.

Returns:: The total number of gates in the circuit.
Return type:: int

dump_qasm3(stream)[source]#

Serialize to QASM3.

Parameters:: stream (TextIOBase) – The stream to output to.
Return type:: None

dump_qasm2(stream)[source]#

Serialize to QASM2.

Parameters:: stream (TextIOBase) – The stream to output to.
Return type:: None

draw(output, filename=None)[source]#

Draw the circuit to matplotlib, ASCII, or Latex representations.

Parameters:

output (str) – The format of the output. Use “text”, “mpl”, or “texsource”, respectively.
filename (str | None, optional) – The file to write the output to, by default None.

class qlbm.components.base.LBMPrimitive(logger=<Logger qlbm (WARNING)>)[source]#

Base class for all primitive-level quantum components.

A primitive component is a small, isolated, and structurally parameterizable quantum circuit that can be reused throughout one or multiple algorithms.

Attribute	Summary
`circuit`	The `qiskit.QuantumCircuit` of the primitive.
`logger`	The performance logger, by default `getLogger("qlbm")`

Parameters:: logger (Logger)

class qlbm.components.base.LBMOperator(lattice, logger=<Logger qlbm (WARNING)>)[source]#

Base class for all operator-level quantum components.

An operator component implements a specific physical operation corresponding to the classical LBM (streaming, collision, etc.). Operators are inferred based on the structure of a Lattice object of an appropriate encoding.

Attribute	Summary
`circuit`	The `qiskit.QuantumCircuit` of the operator.
`lattice`	The `Lattice` based on which the properties of the operator are inferred.
`logger`	The performance logger, by default `getLogger("qlbm")`

Parameters:

lattice (Lattice)
logger (Logger)

class qlbm.components.base.CQLBMOperator(lattice, logger=<Logger qlbm (WARNING)>)[source]#

Specialization of the LBMOperator operator class for the Collisionless Quantum Transport Method algorithm by Schalkers and Möller [5].

Specializaitons of this class infer their properties based on a CollisionlessLattice.

Attribute	Summary
`circuit`	The `qiskit.QuantumCircuit` of the operator.
`lattice`	The `CollisionlessLattice` based on which the properties of the operator are inferred.
`logger`	The performance logger, by default `getLogger("qlbm")`

Parameters:

lattice (CollisionlessLattice)
logger (Logger)

class qlbm.components.base.SpaceTimeOperator(lattice, logger=<Logger qlbm (WARNING)>)[source]#

Specialization of the LBMOperator operator class for the Space-Time QBM algorithm by Schalkers and Möller [7].

Specializaitons of this class infer their properties based on a SpaceTimeLattice.

Attribute	Summary
`circuit`	The `qiskit.QuantumCircuit` of the operator.
`lattice`	The `SpaceTimeLattice` based on which the properties of the operator are inferred.
`logger`	The performance logger, by default `getLogger("qlbm")`

Parameters:

lattice (SpaceTimeLattice)
logger (Logger)

class qlbm.components.base.LBMAlgorithm(lattice, logger=<Logger qlbm (WARNING)>)[source]#

Base class for all end-to-end Quantum Boltzmann Methods.

An end-to-end algorithm consists of a series of LBMOperator that perform the physical operations of the appropriate algorithm.

Attribute	Summary
`circuit`	The `qiskit.QuantumCircuit` of the algorithm.
`lattice`	The `Lattice` based on which the properties of the algorithm are inferred.
`logger`	The performance logger, by default `getLogger("qlbm")`

Parameters:

lattice (Lattice)
logger (Logger)

Base Classes#

Lattice Base#

Components Base#

This Page