Graphs

Boulder Opal uses graphs to represent all computations. All usage of graphs is via the Graph object, which you can construct directly or using the qctrl.Qctrl.create_graph() method.

This page documents the available graph operations, together with the auxiliary features in the graphs module, namely the graph object itself and the classes representing the types of possible graph nodes.

For context on the role of graphs and their usage in Boulder Opal see the Understanding graphs in Boulder Opal topic. To develop hands-on experience with graphs, complete the Get familiar with graphs tutorial. The How to calculate and optimize with graphs and How to represent quantum systems using graphs user guides can show you how to solve relevant problems with Boulder Opal using graphs.

Boulder Opal also provides toolkits to simplify the workflow for common computation tasks. Some toolkits host graph nodes that you can access from their namespaces of the Graph object. See the reference for details.

Graph object

The graph object is the main entrypoint to the Q-CTRL graph ecosystem.

Graph

Utility class for representing and building a Q-CTRL data flow graph.

Data types

Each graph operation creates a node, and each node has a type corresponding to the type of the data it produces.

ConvolutionKernel

A kernel to be used in a convolution.

Pwc

A piecewise-constant tensor-valued function of time (or batch of such functions).

SparsePwc

A piecewise-constant sparse-matrix-valued function of time.

Stf

A sampleable tensor-valued function of time (or batch of such functions).

Target

A target gate for an infidelity calculation.

Tensor

A multi-dimensional array of data.

Optimization variables

When performing optimizations, you can use these operations to create the optimizable variables that can be tuned by the optimizer in order to minimize your cost function.

Graph.anchored_difference_bounded_variables

Create a sequence of optimizable variables with an anchored difference bound.

Graph.optimization_variable

Create optimization variables, which can be bounded, semi-bounded, or unbounded.

Graph.real_fourier_pwc_signal

Create a piecewise-constant signal constructed from Fourier components.

Graph.real_fourier_stf_signal

Create a real sampleable signal constructed from Fourier components.

Building Hamiltonians

You can use these operations to build graphs representing Hamiltonians. Hamiltonians are represented as tensor-valued functions of time. Tensor-valued functions of time can be either piecewise-constant (PWCs) or smooth (STFs, which stands for sampleable tensor functions). You can manipulate PWCs and STFs either by using the operations in this section or by applying most mathematical functions. You can also convert PWCs into STFs by applying linear filters, and can convert STFs into PWCs by discretizing.

Working with piecewise-constant tensor functions (PWCs)

Graph.complex_pwc_signal

Create a complex piecewise-constant signal from moduli and phases.

Graph.constant_pwc

Create a piecewise-constant function of time that is constant over a specified duration.

Graph.constant_pwc_operator

Create a constant piecewise-constant operator over a specified duration.

Graph.pwc

Create a piecewise-constant function of time.

Graph.pwc_operator

Create a constant operator multiplied by a piecewise-constant signal.

Graph.pwc_signal

Create a piecewise-constant signal (scalar-valued function of time).

Graph.pwc_sum

Create the sum of multiple piecewise-constant terms.

Graph.real_fourier_pwc_signal

Create a piecewise-constant signal constructed from Fourier components.

Graph.sample_pwc

Sample a Pwc at the given times.

Graph.symmetrize_pwc

Create the symmetrization of a piecewise-constant function.

Graph.time_concatenate_pwc

Concatenate multiple piecewise-constant functions in the time dimension.

Graph.time_reverse_pwc

Reverse in time a piecewise-constant function.

Working with sampleable tensor functions (STFs)

You can use these functions to create and manipulate STFs. Note that a powerful way to create analytic STFs is to start with identity_stf and then apply a sequence of mathematical functions.

Graph.constant_stf

Create a constant sampleable tensor-valued function of time.

Graph.constant_stf_operator

Create a constant operator.

Graph.identity_stf

Create an Stf representing the identity function, f(t) = t.

Graph.random_colored_noise_stf_signal

Sample the one-sided power spectral density (PSD) of a random noise process in the time domain and returns the resultant noise trajectories as an Stf.

Graph.real_fourier_stf_signal

Create a real sampleable signal constructed from Fourier components.

Graph.sample_stf

Sample an Stf at the given times.

Graph.stf_operator

Create a constant operator multiplied by a sampleable signal.

Graph.stf_sum

Create the sum of multiple sampleable functions.

Filtering and discretizing

Graph.convolve_pwc

Create the convolution of a piecewise-constant function with a kernel.

Graph.discretize_stf

Create a piecewise-constant function by discretizing a sampleable function.

Graph.gaussian_convolution_kernel

Create a convolution kernel representing a normalized Gaussian.

Graph.sinc_convolution_kernel

Create a convolution kernel representing the sinc function.

Quantum information

Use these operations to calculate common operations and metrics from quantum information theory.

Graph.annihilation_operator

Create an annihilation operator in the truncated Fock space.

Graph.coherent_state

Create a coherent state (or a batch of them).

Graph.creation_operator

Create a creation operator in the truncated Fock space.

Graph.density_matrix_infidelity

Calculate the infidelity between two states represented by density matrices.

Graph.embed_operators

Embed operators into a larger Hilbert space.

Graph.expectation_value

Calculate the expectation value of an operator with respect to a state.

Graph.fock_state

Create a Fock state (or a batch of them).

Graph.inner_product

Calculate the inner product of two vectors.

Graph.kronecker_product_list

Calculate the Kronecker product between a list of operators.

Graph.number_operator

Create a number operator in the truncated Fock space.

Graph.outer_product

Calculate the outer product of two vectors.

Graph.partial_trace

Calculate the partial trace of a density matrix.

Graph.pauli_kronecker_product

Place Pauli matrices into their two-dimensional subsystems of a system and returns the Kronecker product.

Graph.pauli_matrix

Create a Pauli matrix from a label.

Graph.state_infidelity

Calculate the infidelity of two pure states.

Graph.unitary_infidelity

Calculate the infidelity between a target operation and the actual implemented unitary.

Time evolution

You can use these operations to calculate the time evolution of your open or closed quantum system, either for simulations or optimizations.

Graph.density_matrix_evolution_pwc

Calculate the state evolution of an open system described by the GKS–Lindblad master equation.

Graph.estimated_krylov_subspace_dimension_lanczos

Calculate an appropriate Krylov subspace dimension (\(k\)) to use in the Lanczos integrator while keeping the total error in the evolution below a given error tolerance.

Graph.spectral_range

Obtain the range of the eigenvalues of a Hermitian operator.

Graph.state_evolution_pwc

Calculate the time evolution of a state generated by a piecewise-constant Hamiltonian by using the Lanczos method.

Graph.time_evolution_operators_pwc

Calculate the unitary time-evolution operators for a system defined by a piecewise-constant Hamiltonian.

Graph.time_evolution_operators_stf

Calculate the time-evolution operators for a system defined by an STF Hamiltonian by using a 4th order Runge–Kutta method.

Optimal and robust control

You can use these operations, together with the operations for creating optimization variables and Hamiltonians, to define convenient cost functions for optimal and robust control.

Graph.infidelity_pwc

Create the total infidelity of the given piecewise-constant system.

Graph.infidelity_stf

Create the total infidelity of a given system with a sampleable Hamiltonian.

Graph.target

Create information about the target for system time evolution.

Large systems

You can use these operations, together with those for building Hamiltonians, to build graphs that efficiently handle large quantum systems.

Graph.constant_sparse_pwc_operator

Create a constant sparse piecewise-constant operator over a specified duration.

Graph.density_matrix_evolution_pwc

Calculate the state evolution of an open system described by the GKS–Lindblad master equation.

Graph.estimated_krylov_subspace_dimension_lanczos

Calculate an appropriate Krylov subspace dimension (\(k\)) to use in the Lanczos integrator while keeping the total error in the evolution below a given error tolerance.

Graph.sparse_pwc_hermitian_part

Create the Hermitian part of a piecewise-constant operator.

Graph.sparse_pwc_operator

Create a sparse piecewise-constant operator (sparse-matrix-valued function of time).

Graph.sparse_pwc_sum

Create the sum of multiple sparse-matrix-valued piecewise-constant functions.

Graph.spectral_range

Obtain the range of the eigenvalues of a Hermitian operator.

Graph.state_evolution_pwc

Calculate the time evolution of a state generated by a piecewise-constant Hamiltonian by using the Lanczos method.

Mølmer–Sørensen gates

You can use these operations to efficiently model systems described by Mølmer–Sørensen interactions.

Graph.ms_dephasing_robust_cost

Calculate the cost for robust optimization of a Mølmer–Sørensen gate.

Graph.ms_displacements

Calculate the displacements for each mode and ion combination where ions are described by a Mølmer–Sørensen-type interaction.

Graph.ms_infidelity

Calculate the final operational infidelity of the Mølmer–Sørensen gate.

Graph.ms_phases

Calculate the relative phases for all pairs of ions described by a Mølmer–Sørensen-type interaction when single-tone individually-addressed laser beams are used.

Graph.ms_phases_multitone

Calculate the relative phases for all pairs of ions described by a Mølmer–Sørensen-type interaction where the ions are being addressed by a multitone global beam.

Random operations

You can use these operations to create random quantities, which take different values each time they are evaluated. These operations are most useful in simulations and stochastic optimizations.

Graph.random_choices

Create random samples from the data that you provide.

Graph.random_colored_noise_stf_signal

Sample the one-sided power spectral density (PSD) of a random noise process in the time domain and returns the resultant noise trajectories as an Stf.

Graph.random_normal

Create a sample of normally distributed random numbers.

Graph.random_uniform

Create a sample of uniformly distributed random numbers.

Manipulating tensors

You can use these operations to manipulate the structures of tensors.

Graph.concatenate

Concatenate a list of tensors along a specified dimension.

Graph.cumulative_sum

Calculate the cumulative sum of a tensor along a specified dimension.

Graph.einsum

Perform tensor contraction via Einstein summation convention.

Graph.max

Find the maximum value in a tensor along one or multiple of its axes.

Graph.min

Find the minimum value in a tensor along one or multiple of its axes.

Graph.repeat

Repeat elements of a tensor.

Graph.reshape

Reshape a tensor into a new shape, keeping the order of its elements.

Graph.reverse

Reverse a tensor along some specified dimensions.

Graph.sum

Sum the elements in a tensor (or a list of tensors with the same shape) along one or multiple of its axes.

Graph.tensor

Create a real or complex Tensor with the data provided.

Graph.transpose

Reorder the dimensions of a tensor.

Mathematical functions

You can use these operations to perform standard mathematical computations.

Arithmetic

Graph.add

Calculate the element-wise sum between numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.cumulative_sum

Calculate the cumulative sum of a tensor along a specified dimension.

Graph.floordiv

Calculate the element-wise rounded-down division between real numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.multiply

Calculate the element-wise product between numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.negative

Calculate the element-wise numerical negative value of an object.

Graph.pow

Calculate the element-wise power between numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.subtract

Calculate the element-wise difference between numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.sum

Sum the elements in a tensor (or a list of tensors with the same shape) along one or multiple of its axes.

Graph.truediv

Calculate the element-wise division between numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

Linear algebra

Graph.adjoint

Calculate the element-wise adjoint of the last two dimensions of an object.

Graph.einsum

Perform tensor contraction via Einstein summation convention.

Graph.embed_operators

Embed operators into a larger Hilbert space.

Graph.expectation_value

Calculate the expectation value of an operator with respect to a state.

Graph.hermitian_part

Calculate the Hermitian part of an object.

Graph.inner_product

Calculate the inner product of two vectors.

Graph.kron

Calculate the Kronecker product between np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.kronecker_product_list

Calculate the Kronecker product between a list of operators.

Graph.matmul

Calculate the matrix multiplication between np.ndarrays, Tensors, Pwcs, or Stfs.

Graph.outer_product

Calculate the outer product of two vectors.

Graph.partial_trace

Calculate the partial trace of a density matrix.

Graph.trace

Calculate the trace of an object.

Graph.transpose

Reorder the dimensions of a tensor.

Basic functions

Graph.abs

Calculate the element-wise absolute value of an object.

Graph.exp

Calculate the element-wise exponential of an object.

Graph.log

Calculate the element-wise natural logarithm of an object.

Graph.sqrt

Calculate the element-wise square root of an object.

Trigonometric functions

Graph.arccos

Calculate the element-wise arccosine of an object.

Graph.arcsin

Calculate the element-wise arcsine of an object.

Graph.arctan

Calculate the element-wise arctangent of an object.

Graph.cos

Calculate the element-wise cosine of an object.

Graph.sin

Calculate the element-wise sine of an object.

Graph.tan

Calculate the element-wise tangent of an object.

Hyperbolic functions

Graph.cosh

Calculate the element-wise hyperbolic cosine of an object.

Graph.sinh

Calculate the element-wise hyperbolic sine of an object.

Graph.tanh

Calculate the element-wise hyperbolic tangent of an object.

Handling complex numbers

Graph.abs

Calculate the element-wise absolute value of an object.

Graph.angle

Calculate the element-wise argument of an object.

Graph.complex_value

Create element-wise complex values from real numbers, np.ndarrays, Tensors, Pwcs, or Stfs, that is, the real and imaginary parts.

Graph.conjugate

Calculate the element-wise complex conjugate of an object.

Graph.imag

Calculate the element-wise imaginary part of an object.

Graph.real

Calculate the element-wise real part of an object.

Derivatives

Graph.gradient

Calculate the gradients for all the variables.

Graph.hessian

Calculate a single Hessian matrix for all the variables.

Other operations

You typically do not need to use these operations directly.

Graph.getattr

Get an attribute from a node value.

Graph.getitem

Get an item (or items) from a node value.

Deprecated operations

These operations are deprecated and will be removed in the future.