Constructors

Functions for creating channel data structures. More...

Functions
KrausMap	createInlineKrausMap (int numQb, int numOps, {{{ matrices }}})
SuperOp	createInlineSuperOp (int numQb, {{ matrix }})
KrausMap	createKrausMap (int numQubits, int numOperators)
SuperOp	createSuperOp (int numQubits)

Detailed Description

Functions for creating channel data structures.

Function Documentation

createInlineKrausMap()

KrausMap createInlineKrausMap	(	int	numQb,
		int	numOps,
		{{{ matrices }}}	)

Creates and initialises a KrausMap from an inline literal.

This is a convenience macro which combines createKausMap() and setInlineKrausMap().

The {{{matrices}}} argument is a 3D array literal, of dimensions numOps by 1<<numQb by 1<<numQb.

• In C, this is a macro, where numQb and numOps must be compile-time literals, and turn {{{matrices}}} into a compound literal.
• In C++, this is a function which accepts {{{matrices}}} as a nested std::vector literal.

The returned KrausMap should be later destroyed with destroyKrausMap().

Example

KrausMap map = createInlineKrausMap(1, 3, {
    {{1,2},{3,4}},
    {{5,5},{6,6}},
    {{1i,2i},{-3i,-4i}}
});

Parameters

[in]	numQb	the number of qubits acted upon by the Kraus map.
[in]	numOps	the number of Kraus operators.

Returns

A new KrausMap initialised with matrices.

Exceptions

error

if the QuEST environment is not initialised. if numQb or numOps are invalid. if dimensions or memory requirements overflow. if any memory allocation fails.

See also

• createKrausMap()
• setKrausMap()
• syncKrausMap()
• C and C++ examples

Author

Tyson Jones

createInlineSuperOp()

SuperOp createInlineSuperOp	(	int	numQb,
		{{ matrix }}	)

Creates and initialises a SuperOp from an inline literal.

This is a convenience macro which combines createSuperOp() and setInlineSuperOp().

The {{matrix}} argument is a 2D array literal, of dimensions 1<<(2*numQb) by 1<<(2*numQb).

• In C, this is a macro, where numQb must be a compile-time literal, amd turns {{matrix}} into a compound literal.
• In C++, this is a function which accepts {{matrix}} as a nested std::vector literal.

The returned SuperOp should be later destroyed with destroySuperOp().

Example

SuperOp op = createInlineSuperOp(1, {
    {1,2,3,4},
    {5,6*3.14i,7,8},
    {9,10,11,12},
    {13,14,15,16+1.23i}
});

Parameters

[in]

numQb

the number of qubits acted upon by the superoperator.

Returns

A new SuperOp initialised with matrix.

Exceptions

error

if the QuEST environment is not initialised. if numQb is invalid. if dimensions or memory requirements overflow. if any memory allocation fails.

See also

• createSuperOp()
• setSuperOp()
• syncSuperOp()
• C and C++ examples

Author

Tyson Jones

createKrausMap()

KrausMap createKrausMap	(	int	numQubits,
		int	numOperators )

Creates an uninitialised Kraus map.

The returned KrausMap contains numOperators Kraus operators, each of which spans numQubits many qubits. Before being passed to functions like reportKrausMap() and mixKrausMap(), its elements must be populated with setKrausMap() or setInlineKrausMap(), or directly modified through KrausMap::matrices, though any direct modification must be followed by a call to syncKrausMap().

The returned KrausMap should be later destroyed with destroyKrausMap().

‍See C or C++ examples of initialising a KrausMap.

Parameters

[in]	numQubits	the number of qubits acted upon by the Kraus map.
[in]	numOperators	the number of Kraus operators in the map.

Returns

A new KrausMap instance.

Exceptions

error

if the QuEST environment is not initialised. if numQubits or numOperators are invalid. if the dimensions or memory requirements overflow. if any memory allocation fails.

See also

• createInlineKrausMap()
• createSuperOp()
• setKrausMap()
• setInlineKrausMap()
• C or C++ examples

Author

Tyson Jones

Definition at line 176 of file channels.cpp.

                                                                    {
    validate_envIsInit(__func__);
    validate_newKrausMapParams(numQubits, numOperators, __func__);
 
    // validation ensures this never overflows
    qindex numRows = powerOf2(numQubits);
 
    // attempt to allocate output KrausMap fields (avoiding C++20 designated initialiser)
    KrausMap out;
    out.numQubits = numQubits,
    out.numMatrices = numOperators,
    out.numRows = numRows,
    out.matrices = cpu_allocMatrixList(numRows, numOperators); // is or contains nullptr if failed
    out.superop = allocSuperOp(numQubits); // heap fields are or contain nullptr if failed
    out.isApproxCPTP = util_allocEpsilonSensitiveHeapFlag(); // nullptr if failed
 
    // free memory before throwing validation error to avoid memory leaks
    freeAllMemoryIfAnyAllocsFailed(out); // sets out.matrices=nullptr if failed
    validate_newKrausMapAllocs(out, __func__);
 
    // mark CPTP as unknown; it will be lazily evaluated whene a function asserts CPTP-ness
    util_setFlagToUnknown(out.isApproxCPTP);
 
    return out;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

createSuperOp()

SuperOp createSuperOp

(

int

numQubits

)

Creates an uninitialised superoperator.

The returned SuperOp represents an arbitrary linear map on vectorised density matrices, spanning numQubits many ket-qubits and an equal number of bra-qubits. Before being passed to functions like reportSuperOp() and mixSuperOp(), its elements must be populated with setSuperOp() or setInlineSuperOp(), or directly modified through SuperOp::cpuElems, though direct modification must be followed by a call to syncSuperOp().

The returned SuperOp should be later destroyed with destroySuperOp().

‍See C or C++ examples of initialising a SuperOp.

Parameters

[in]

numQubits

the number of qubits acted upon by the superoperator.

Returns

A new SuperOp instance.

Exceptions

error

if the QuEST environment is not initialised. if numQubits is invalid. if the dimensions or memory requirements overflow. if any memory allocation fails.

See also

• createInlineSuperOp()
• createKrausMap()
• setSuperOp()
• setInlineSuperOp()
• C or C++ examples

Author

Tyson Jones

Definition at line 162 of file channels.cpp.

                                                {
    validate_envIsInit(__func__);
    validate_newSuperOpParams(numQubits, __func__);
 
    SuperOp out = allocSuperOp(numQubits); // fields may be or contain nullptr if failed
 
    // free all memory before we throw validation errors to avoid leaks
    freeAllMemoryIfAnyAllocsFailed(out);
    validate_newSuperOpAllocs(out, __func__);
 
    return out;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().