Represents a square matrix used for describing N-qubit gates. More...

Inheritance diagram for dqcsim::wrap::Matrix:

Public Member Functions
	Matrix (HandleIndex handle) noexcept
	Wraps the given matrix handle. More...

	Matrix (size_t num_qubits, const complex *matrix)
	Constructs a matrix from a row-major flattened array of `4**num_qubits` `complex`s. More...

	Matrix (size_t num_qubits, const double *matrix)
	Constructs a matrix from a row-major flattened array of `2 * 4**num_qubits` `complex`s. More...

	Matrix (PredefinedGate gate)
	Constructs a non-parameterized predefined matrix. More...

	Matrix (PredefinedGate gate, ArbData &&parameters)
	Constructs a predefined matrix, using `ArbData` to represent the parameters for parameterized gates. More...

	Matrix (PredefinedGate gate, const ArbData &parameters)
	Constructs a predefined matrix, using `ArbData` to represent the parameters for parameterized gates. More...

	Matrix (PauliBasis basis)
	Constructs a Pauli basis matrix. More...

	Matrix (const Matrix &src)
	Copy-constructs a matrix. More...

void	operator= (const Matrix &src)
	Copy assignment operator for matrices. More...

	Matrix (Matrix &&)=default
	Default move constructor.

Matrix &	operator= (Matrix &&)=default
	Default move assignment.

size_t	size () const
	Returns the number of elements in the matrix. More...

size_t	dimension () const
	Returns the number of rows/columns in the matrix. More...

size_t	num_qubits () const
	Returns the number of qubits associated with the matrix. More...

std::vector< complex >	get () const
	Returns the data contained by the matrix in row-major form as complex numbers. More...

std::vector< double >	get_as_doubles () const
	Returns the data contained by the matrix in row-major form as pairs of real/imag doubles. More...

bool	approx_eq (const Matrix &other, double epsilon=0.000001, bool ignore_global_phase=true) const
	Approximate equality operator for two matrices. More...

bool	basis_approx_eq (const Matrix &other, double epsilon=0.000001) const
	Approximate equality operator for two basis matrices. More...

bool	approx_unitary (double epsilon=0.000001) const
	Approximate unitary check. More...

bool	is_predefined (PredefinedGate gate, double epsilon=0.000001, bool ignore_global_phase=true, ArbData *parameters=nullptr) const
	Detects whether this matrix is approximately equal to (some parameterization of) the given predefined gate. More...

Matrix	add_controls (size_t number_of_controls) const
	Constructs a controlled matrix from the given matrix. More...

std::pair< std::vector< size_t >, Matrix >	strip_control (double epsilon, bool ignore_global_phase) const
	Splits a controlled matrix into its non-controlled submatrix and the indices of the control qubits. More...

Public Member Functions inherited from dqcsim::wrap::Handle
	Handle () noexcept
	Constructs an empty wrapper. More...

	Handle (HandleIndex handle) noexcept
	Wraps the given raw handle. More...

virtual	~Handle () noexcept
	Delete the handle and its wrapper.

void	free ()
	Explicitly delete the handle, allowing errors to be caught. More...

bool	is_valid () const noexcept
	Returns whether this wrapper (still) contains a valid handle. More...

HandleIndex	get_handle () const noexcept
	Returns the raw handle without relinquishing ownership. More...

HandleIndex	take_handle () noexcept
	Returns the raw handle and relinquishes ownership. More...

	Handle (const Handle &)=delete

void	operator= (const Handle &)=delete

	Handle (Handle &&src)
	Move constructor; simply moves ownership of the handle from the source object to the constructed object. More...

Handle &	operator= (Handle &&src)
	Move constructor; simply moves ownership of the handle from the source object to the assignment target. More...

std::string	dump () const
	Returns a string containing a debug dump of the handle. More...

HandleType	type () const
	Returns the type of this handle. More...

Additional Inherited Members
Protected Attributes inherited from dqcsim::wrap::Handle
HandleIndex	handle
	The wrapped handle.

Detailed Description

Represents a square matrix used for describing N-qubit gates.

Note: DQCsim is not a math library: this matrix class is solely intended as an interface between DQCsim's internal matrix representation and whatever math library you want to use.

Definition at line 3160 of file dqcsim.

Constructor & Destructor Documentation

◆ Matrix() [1/8]

dqcsim::wrap::Matrix::Matrix ( HandleIndex handle )

inlinenoexcept

Wraps the given matrix handle.

Note: This constructor does not verify that the handle is actually valid.

Parameters

handle The raw handle to wrap.

Definition at line 3171 of file dqcsim.

◆ Matrix() [2/8]

dqcsim::wrap::Matrix::Matrix	(	size_t	num_qubits,
		const complex *	matrix
	)

inline

Constructs a matrix from a row-major flattened array of 4**num_qubits complexs.

Parameters

num_qubits	The number of qubits that the matrix is intended for. Must be 1 or more.
matrix	Pointer to an array of complex numbers representing the desired matrix in row-major form. The matrix has `4**num_qubits` complex entries.

Returns: A new matrix containing the desired data.

Exceptions

std::runtime_error When constructing the matrix failed.

Definition at line 3186 of file dqcsim.

◆ Matrix() [3/8]

dqcsim::wrap::Matrix::Matrix	(	size_t	num_qubits,
		const double *	matrix
	)

inline

Constructs a matrix from a row-major flattened array of 2 * 4**num_qubits complexs.

Parameters

num_qubits	The number of qubits that the matrix is intended for. Must be 1 or more.
matrix	Pointer to an array of complex numbers representing the desired matrix in row-major form using (real, imag) pairs. The matrix contains `24*num_qubits` doubles.

Returns: A new matrix containing the desired data.

Exceptions

std::runtime_error When constructing the matrix failed.

Definition at line 3202 of file dqcsim.

◆ Matrix() [4/8]

dqcsim::wrap::Matrix::Matrix ( PredefinedGate gate )

inline

Constructs a non-parameterized predefined matrix.

Parameters

gate	The gate to construct the matrix for.

Returns: A new matrix containing the desired data.

Exceptions

std::runtime_error When the matrix for a parameterized gate type is requested, or constructing the matrix failed.

Definition at line 3214 of file dqcsim.

◆ Matrix() [5/8]

dqcsim::wrap::Matrix::Matrix	(	PredefinedGate	gate,
		ArbData &&	parameters
	)

inline

Constructs a predefined matrix, using ArbData to represent the parameters for parameterized gates.

The ArbData needed for the rotation gates can be trivially constructed in-line. Here's the relevant code:

double theta, phi, lambda;
uint64_t k;
Matrix(PredefinedGate::RX, ArbData.with_arg(theta));
Matrix(PredefinedGate::RY, ArbData.with_arg(theta));
Matrix(PredefinedGate::RZ, ArbData.with_arg(theta));
Matrix(PredefinedGate::Phase, ArbData.with_arg(theta));
Matrix(PredefinedGate::PhaseK, ArbData.with_arg(k));
Matrix(PredefinedGate::R, ArbData.with_arg(theta).with_arg(phi).with_arg(lambda));

Parameters

gate	The gate to construct the matrix for.
parameters	The parameters for the gate; refer to the docs for `PredefinedGate` for more information.

Returns: A new matrix containing the desired data.

Exceptions

std::runtime_error When constructing the matrix failed.

Definition at line 3242 of file dqcsim.

◆ Matrix() [6/8]

dqcsim::wrap::Matrix::Matrix	(	PredefinedGate	gate,
		const ArbData &	parameters
	)

inline

Constructs a predefined matrix, using ArbData to represent the parameters for parameterized gates.

Parameters

gate	The gate to construct the matrix for.
parameters	The parameters for the gate; refer to the docs for `PredefinedGate` for more information.

Returns: A new matrix containing the desired data.

Exceptions

std::runtime_error When constructing the matrix failed.

Definition at line 3256 of file dqcsim.

◆ Matrix() [7/8]

dqcsim::wrap::Matrix::Matrix ( PauliBasis basis )

inline

Constructs a Pauli basis matrix.

Parameters

basis The basis to construct the matrix for.

Returns: A new matrix containing the desired data.

Exceptions

std::runtime_error When constructing the matrix failed.

Definition at line 3267 of file dqcsim.

◆ Matrix() [8/8]

dqcsim::wrap::Matrix::Matrix ( const Matrix & src )

inline

Copy-constructs a matrix.

Parameters

src	The object to copy from.

Exceptions

std::runtime_error When the source handle is invalid or construction of the new handle failed for some reason.

Definition at line 3278 of file dqcsim.

Member Function Documentation

◆ operator=()

void dqcsim::wrap::Matrix::operator= ( const Matrix & src )

inline

Copy assignment operator for matrices.

Parameters

src	The object to copy from.

Exceptions

std::runtime_error When the source handle is invalid, any previously wrapped handle in the destination object could not be freed, or construction of the new handle failed for some reason.

Definition at line 3290 of file dqcsim.

◆ size()

size_t dqcsim::wrap::Matrix::size ( ) const

inline

Returns the number of elements in the matrix.

Returns: The number of elements in the matrix.

Exceptions

std::runtime_error When the matrix handle is invalid.

Definition at line 3312 of file dqcsim.

◆ dimension()

size_t dqcsim::wrap::Matrix::dimension ( ) const

inline

Returns the number of rows/columns in the matrix.

Returns: The number of rows/columns in the matrix.

Exceptions

std::runtime_error When the matrix handle is invalid.

Definition at line 3322 of file dqcsim.

◆ num_qubits()

size_t dqcsim::wrap::Matrix::num_qubits ( ) const

inline

Returns the number of qubits associated with the matrix.

Returns: The number of qubits associated with the matrix.

Exceptions

std::runtime_error When the matrix handle is invalid.

Definition at line 3332 of file dqcsim.

◆ get()

std::vector<complex> dqcsim::wrap::Matrix::get ( ) const

inline

Returns the data contained by the matrix in row-major form as complex numbers.

Returns: The data contained by the matrix.

Exceptions

std::runtime_error When the matrix handle is invalid.

Definition at line 3343 of file dqcsim.

◆ get_as_doubles()

std::vector<double> dqcsim::wrap::Matrix::get_as_doubles ( ) const

inline

Returns the data contained by the matrix in row-major form as pairs of real/imag doubles.

Returns: The data contained by the matrix.

Exceptions

std::runtime_error When the matrix handle is invalid.

Definition at line 3358 of file dqcsim.

◆ approx_eq()

bool dqcsim::wrap::Matrix::approx_eq	(	const Matrix &	other,
		double	epsilon = `0.000001`,
		bool	ignore_global_phase = `true`
	)		const

inline

Approximate equality operator for two matrices.

If ignore_gphase is set, this checks that the following holds for some x:

\[ This \cdot e^{ix} \approx Other \]

Parameters

other	The matrix to compare to.
epsilon	The maximum tolerated RMS variation of the elements.
ignore_global_phase	Whether global phase differences should be ignored in the comparison.

Returns: Whether the matrices are approximately equal.

Exceptions

std::runtime_error When either handle is invalid.

Definition at line 3382 of file dqcsim.

◆ basis_approx_eq()

bool dqcsim::wrap::Matrix::basis_approx_eq	(	const Matrix &	other,
		double	epsilon = `0.000001`
	)		const

inline

Approximate equality operator for two basis matrices.

This checks that the following holds for some x and y:

\[ This \cdot \begin{bmatrix} e^{ix} & 0 \\ 0 & e^{iy} \end{bmatrix} \approx Other \]

Parameters

other	The matrix to compare to.
epsilon	The maximum tolerated RMS variation of the elements.

Returns: Whether the bases are approximately equal.

Exceptions

std::runtime_error When either handle is invalid.

Definition at line 3407 of file dqcsim.

◆ approx_unitary()

bool dqcsim::wrap::Matrix::approx_unitary ( double epsilon = 0.000001 ) const

inline

Approximate unitary check.

This internally computes the product of this matrix and its Hermetian, and then does an approximate compare against the identity matrix.

Parameters

epsilon The maximum tolerated RMS variation between the identity matrix and the computed product.

Returns: Whether the matrix is approximately unitary.

Exceptions

std::runtime_error When the handle is invalid.

Definition at line 3425 of file dqcsim.

◆ is_predefined()

bool dqcsim::wrap::Matrix::is_predefined	(	PredefinedGate	gate,
		double	epsilon = `0.000001`,
		bool	ignore_global_phase = `true`,
		ArbData *	parameters = `nullptr`
	)		const

inline

Detects whether this matrix is approximately equal to (some parameterization of) the given predefined gate.

The detected parameters are optionally returned as an ArbData if the matrix matches. If you want to compare to a specific parameterization of a predefined gate (for instance, an X rotation of 45 degrees), construct its matrix first, and then compare with approx_eq().

Parameters

gate	The predefined gate matrix to detect.
epsilon	The maximum tolerated RMS variation of the elements.
ignore_global_phase	Whether global phase differences should be ignored in the comparison.
parameters	If non-null, the detected parameters (if any) are written into the referenced `ArbData`. Any previous contents are discarded.

Returns: Whether the matrix matches the given predefined gate type.

Exceptions

std::runtime_error When the current handle is invalid, detection fails, or parameters could not be updated.

Definition at line 3449 of file dqcsim.

◆ add_controls()

Matrix dqcsim::wrap::Matrix::add_controls ( size_t number_of_controls ) const

inline

Constructs a controlled matrix from the given matrix.

Parameters

number_of_controls The number of control qubits to add.

Returns: The new matrix.

Exceptions

std::runtime_error When the handle is invalid or construction of the new matrix failed.

Definition at line 3473 of file dqcsim.

◆ strip_control()

std::pair<std::vector<size_t>, Matrix> dqcsim::wrap::Matrix::strip_control	(	double	epsilon,
		bool	ignore_global_phase
	)		const

inline

Splits a controlled matrix into its non-controlled submatrix and the indices of the control qubits.

Parameters

epsilon	The maximum magitude of the difference between the column vectors of the input matrix and the identity matrix (after dephasing if `ignore_phase` is set) for the column vector to be considered to not affect the respective entry in the quantum state vector. Note that if this is greater than zero, the resulting gate may not be exactly equivalent.
ignore_global_phase	If this is set, any global phase in the matrix is ignored, but note that if control qubits are stripped the "global" phase of the resulting submatrix is always significant.

Returns: A pair consisting of a sorted vector of the qubit indices that were removed and the newly constructed submatrix.

Exceptions

std::runtime_error When the handle is invalid or construction of the new matrix failed.

Definition at line 3495 of file dqcsim.

The documentation for this class was generated from the following file:

dqcsim

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Matrix() [1/8]

◆ Matrix() [2/8]

◆ Matrix() [3/8]

◆ Matrix() [4/8]

◆ Matrix() [5/8]

◆ Matrix() [6/8]

◆ Matrix() [7/8]

◆ Matrix() [8/8]

Member Function Documentation

◆ operator=()

◆ size()

◆ dimension()

◆ num_qubits()

◆ get()

◆ get_as_doubles()

◆ approx_eq()

◆ basis_approx_eq()

◆ approx_unitary()

◆ is_predefined()

◆ add_controls()

◆ strip_control()