# 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. To learn more about the role of graphs and their usage in Boulder Opal see the How to calculate with graphs User guide.

Warning

Note that the methods on the graph object can also be accessed via the Qctrl.operations namespace, but that usage is deprecated and will be removed soon. To migrate, change code of the form:

with qctrl.create_graph() as graph:
# Lines involving qctrl.operations, for example:
x = qctrl.operations.multiply(2, 3)


into:

graph = qctrl.create_graph()
# Lines involving graph, for example:
x = graph.multiply(2, 3)


## 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 Creates a sequence of variables with an anchored difference bound. Graph.optimization_variable Creates optimization variables, which can be bounded, semi-bounded, or unbounded. Graph.real_fourier_pwc_signal Creates a piecewise-constant signal constructed from Fourier components. Graph.real_fourier_stf_signal Creates 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 Creates a complex piecewise-constant signal from moduli and phases. Graph.constant_pwc Creates a piecewise-constant function of time that is constant over a specified duration. Graph.constant_pwc_operator Creates a constant piecewise-constant operator over a specified duration. Graph.pwc Creates a piecewise-constant function of time. Graph.pwc_operator Creates a constant operator multiplied by a piecewise-constant signal. Graph.pwc_operator_hermitian_part Creates the Hermitian part of a piecewise-constant operator. Graph.pwc_signal Creates a piecewise-constant signal (scalar-valued function of time). Graph.pwc_sum Creates the sum of multiple piecewise-constant terms. Graph.real_fourier_pwc_signal Creates a piecewise-constant signal constructed from Fourier components. Graph.sample_pwc Samples a Pwc at the given times. Graph.symmetrize_pwc Creates the symmetrization of 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 Creates a constant operator. Graph.identity_stf Returns an Stf representing the identity function, f(t) = t. Graph.random_colored_noise_stf_signal Samples 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 Creates a real sampleable signal constructed from Fourier components. Graph.sample_stf Samples an Stf at the given times. Graph.stf_operator Creates a constant operator multiplied by a sampleable signal. Graph.stf_operator_hermitian_part Creates the Hermitian part of an operator-valued sampleable function. Graph.stf_sum Creates the sum of multiple sampleable functions.

### Filtering and discretizing¶

 Graph.convolve_pwc Creates the convolution of a piecewise-constant function with a kernel. Graph.discretize_stf Creates a piecewise-constant function by discretizing a sampleable function. Graph.gaussian_convolution_kernel Creates a convolution kernel representing a normalized Gaussian. Graph.sinc_convolution_kernel Creates a convolution kernel representing the sinc function.

## 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 Calculates the state evolution of an open system described by the GKS–Lindblad master equation. Graph.estimated_krylov_subspace_dimension_lanczos Calculates 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 Obtains the range of the eigenvalues of a Hermitian operator. Graph.state_evolution_pwc Calculates the time evolution of a state generated by a piecewise-constant Hamiltonian by using the Lanczos method. Graph.time_evolution_operators_pwc Calculates the unitary time-evolution operators for a system defined by a piecewise-constant Hamiltonian. Graph.time_evolution_operators_stf Calculates 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 Creates the total infidelity of the given piecewise-constant system. Graph.infidelity_stf Creates the total infidelity of a given system with a sampleable Hamiltonian. Graph.target Creates 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 Creates a constant sparse piecewise-constant operator over a specified duration. Graph.density_matrix_evolution_pwc Calculates the state evolution of an open system described by the GKS–Lindblad master equation. Graph.estimated_krylov_subspace_dimension_lanczos Calculates 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 Creates the Hermitian part of a piecewise-constant operator. Graph.sparse_pwc_operator Creates a sparse piecewise-constant operator (sparse-matrix-valued function of time). Graph.sparse_pwc_sum Creates the sum of multiple sparse-matrix-valued piecewise-constant functions. Graph.spectral_range Obtains the range of the eigenvalues of a Hermitian operator. Graph.state_evolution_pwc Calculates 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 Calculates the cost for robust optimization of a Mølmer–Sørensen gate. Graph.ms_displacements Calculates the displacements for each mode and ion combination where ions are described by a Mølmer–Sørensen-type interaction. Graph.ms_infidelity Calculates the final operational infidelity of the Mølmer–Sørensen gate. Graph.ms_phases Calculates the relative phases for all pairs of ions described by a Mølmer–Sørensen-type interaction.

## 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 Creates random samples from the data that you provide. Graph.random_colored_noise_stf_signal Samples 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 Creates a sample of normally distributed random numbers. Graph.random_uniform Creates a sample of uniformly distributed random numbers.

## Manipulating tensors¶

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

 Graph.concatenate Concatenates a list of tensors along a specified dimension. Graph.cumulative_sum Calculates the cumulative sum of a tensor along a specified dimension. Graph.einsum Performs tensor contraction via Einstein summation convention. Graph.repeat Repeats elements of a tensor. Graph.reverse Reverses a tensor along some specified dimensions. Graph.sum Returns the sum of all the elements in a tensor (or a list of tensors with the same shape), or the sum of a tensor along one or multiple axes. Graph.tensor Creates a real or complex Tensor with the data provided. Graph.transpose Returns the input tensor with its dimensions reordered.

## Mathematical functions¶

You can use these operations to perform standard mathematical computations.

### Arithmetic¶

 Graph.add Calculates the element-wise sum between numbers, np.ndarrays, Tensors, Pwcs, or Stfs. Graph.cumulative_sum Calculates the cumulative sum of a tensor along a specified dimension. Graph.floordiv Calculates the element-wise rounded-down division between numbers, np.ndarrays, Tensors, Pwcs, or Stfs. Graph.multiply Calculates the element-wise product between numbers, np.ndarrays, Tensors, Pwcs, or Stfs. Graph.negative Returns the element-wise numerical negative value of an object. Graph.pow Calculates the element-wise power between numbers, np.ndarrays, Tensors, Pwcs, or Stfs. Graph.subtract Calculates the element-wise difference between numbers, np.ndarrays, Tensors, Pwcs, or Stfs. Graph.sum Returns the sum of all the elements in a tensor (or a list of tensors with the same shape), or the sum of a tensor along one or multiple axes. Graph.truediv Calculates the element-wise division between numbers, np.ndarrays, Tensors, Pwcs, or Stfs.

### Linear algebra¶

 Graph.adjoint Returns the element-wise adjoint of the last two dimensions of an object. Graph.einsum Performs tensor contraction via Einstein summation convention. Graph.kron Calculates the Kronecker product between np.ndarrays, Tensors, Pwcs, or Stfs. Graph.matmul Calculates the matrix multiplication between np.ndarrays, Tensors, Pwcs, or Stfs. Graph.trace Returns the element-wise trace of an object. Graph.transpose Returns the input tensor with its dimensions reordered.

### Basic functions¶

 Graph.abs Returns the element-wise absolute value of an object. Graph.exp Returns the element-wise exponential of an object. Graph.log Returns the element-wise natural logarithm of an object. Graph.sqrt Returns the element-wise square root of an object.

### Trigonometric functions¶

 Graph.arccos Returns the element-wise arccosine of an object. Graph.arcsin Returns the element-wise arcsine of an object. Graph.arctan Returns the element-wise arctangent of an object. Graph.cos Returns the element-wise cosine of an object. Graph.sin Returns the element-wise sine of an object. Graph.tan Returns the element-wise tangent of an object.

### Hyperbolic functions¶

 Graph.cosh Returns the element-wise hyperbolic cosine of an object. Graph.sinh Returns the element-wise hyperbolic sine of an object. Graph.tanh Returns the element-wise hyperbolic tangent of an object.

### Handling complex numbers¶

 Graph.abs Returns the element-wise absolute value of an object. Graph.angle Returns the element-wise argument of an object. Graph.complex_value Creates element-wise complex values from real numbers, np.ndarrays, Tensors, Pwcs, or Stfs, that is, the real and imaginary parts. Graph.conjugate Returns the element-wise complex conjugate of an object. Graph.imag Returns the element-wise imaginary part of an object. Graph.real Returns the element-wise real part of an object.

### Derivatives¶

 Graph.gradient Calculates a single gradient vector for all the variables. Graph.hessian Calculates a single Hessian matrix for all the variables.

## Other operations¶

You typically do not need to use these operations directly.

 Graph.getattr Gets an attribute from a node value. Graph.getitem Gets an item (or items) from a node value.

## Deprecated operations¶

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

 Graph.estimated_krylov_subspace_dimension_arnoldi This node will be removed in the future. Graph.hessian_matrix This node will be removed in the future.