Function applyPhaseFuncOverrides

Source

pub unsafe extern "C" fn applyPhaseFuncOverrides(
    qureg: Qureg,
    qubits: *mut c_int,
    numQubits: c_int,
    encoding: bitEncoding,
    coeffs: *mut f64,
    exponents: *mut f64,
    numTerms: c_int,
    overrideInds: *mut c_longlong,
    overridePhases: *mut f64,
    numOverrides: c_int,
)

Expand description

Induces a phase change upon each amplitude of \p qureg, determined by the passed exponential polynomial “phase function”, and an explicit set of ‘overriding’ values at specific state indices.

See applyPhaseFunc() first for a full description.

As in applyPhaseFunc(), the arguments \p coeffs and \p exponents specify a phase function \f$f(r)\f$, where \f$r\f$ is determined by \p qubits and \p encoding for each basis state of \p qureg.\n\n
Additionally, \p overrideInds is a list of length \p numOverrides which specifies the values of \f$r\f$ for which to explicitly set the induced phase change.\n The overriding phase changes are specified in the corresponding elements of \p overridePhases.\n\n For example,
```
   int qubits[] = {0,1};
   enum bitEncoding encoding = UNSIGNED;

   long long int overrideInds[] = {2};
   qreal overridePhases[] = {M_PI};

   applyPhaseFuncOverrides(...);
```
would effect the same diagonal unitary of applyPhaseFunc(), except that all instance of \f$f(r=2)\f$ are overriden with phase \f$\pi\f$. \n I.e. \f[ \begin{aligned} |0\mathbf{00}\rangle & \rightarrow , e^{i f(0)},|0\mathbf{00}\rangle \ |0\mathbf{01}\rangle & \rightarrow , e^{i f(1)},|0\mathbf{01}\rangle \ |0\mathbf{10}\rangle & \rightarrow , e^{i \pi} \hspace{12pt} |0\mathbf{10}\rangle \ |0\mathbf{11}\rangle & \rightarrow , e^{i f(3)},|0\mathbf{11}\rangle \ |1\mathbf{00}\rangle & \rightarrow , e^{i f(0)},|1\mathbf{00}\rangle \ |1\mathbf{01}\rangle & \rightarrow , e^{i f(1)},|1\mathbf{01}\rangle \ |1\mathbf{10}\rangle & \rightarrow , e^{i \pi} \hspace{12pt} |1\mathbf{10}\rangle \ |1\mathbf{11}\rangle & \rightarrow , e^{i f(3)},|1\mathbf{11}\rangle \end{aligned} \f] Note that if \p encoding = ::TWOS_COMPLEMENT, \a and \f$f(r)\f$ features a fractional exponent, then every negative phase index must be overriden. This is checked and enforced by QuEST’s validation, \a unless there are more than 16 targeted qubits, in which case valid input is assumed (due to an otherwise prohibitive performance overhead). \n

Overriding phases are checked at each computational basis state of \p qureg before evaluating the phase function \f$f(r)\f$, and hence are useful for avoiding singularities or errors at diverging values of \f$r\f$.

If \p qureg is a density matrix \f$\rho\f$, the overrides determine the diagonal unitary matrix \f$\hat{D}\f$, which is then applied to \p qureg as \f[ \rho ; \rightarrow ; \hat{D} , \rho \hat{D}^\dagger. \f] This means that with overrides \f$f(r_j) \rightarrow \theta\f$ and \f$f(r_k) \rightarrow \phi\f$, element \f$\rho_{jk}\f$ is modified to \f[ \alpha , |j\rangle\langle k| ; \rightarrow ; \exp(, i , (\theta - \phi) , ) ; \alpha , |j\rangle\langle k|. \f]\n

The interpreted phase function and list of overrides can be previewed in the QASM log, as a comment. \n For example:

startRecordingQASM(qureg);
applyPhaseFunc(qureg, ...);
printRecordedQASM(qureg);

may show

// Here, applyPhaseFunc() multiplied a complex scalar of the form
//     exp(i (0.3 x^(-5) + 4 x^1 + 1 x^3))
//   upon every substate |x>, informed by qubits (under a two's complement binary encoding)
//     {4, 1, 2, 0}
//   though with overrides
//     |0> -> exp(i 3.14159)
//     |1> -> exp(i (-3.14159))
//     |2> -> exp(i 0)

\n

@see

applyPhaseFunc() for full doc on how \f$f(r)\f$ is evaluated.
applyMultiVarPhaseFunc() for multi-variable exponential polynomial phase functions.
applyNamedPhaseFunc() for a set of specific phase functions.
applyDiagonalOp() to apply a non-unitary diagonal operator.

@ingroup operator @param[in,out] qureg the state-vector or density matrix to be modified @param[in] qubits a list of the indices of the qubits which will inform \f$r\f$ for each amplitude in \p qureg @param[in] numQubits the length of list \p qubits @param[in] encoding the ::bitEncoding under which to infer the binary value \f$r\f$ from the bits of \p qubits in each basis state of \p qureg @param[in] coeffs the coefficients of the exponential polynomial phase function \f$f(r)\f$ @param[in] exponents the exponents of the exponential polynomial phase function \f$f(r)\f$ @param[in] numTerms the length of list \p coeffs, which must be the same as that of \p exponents @param[in] overrideInds a list of sub-state indices (values of \f$r\f$) of which to explicit set the phase change @param[in] overridePhases a list of replacement phase changes, for the corresponding \f$r\f$ values in \p overrideInds (one to one) @param[in] numOverrides the lengths of lists \p overrideInds and \p overridePhases @exception invalidQuESTInputError()

if any qubit in \p qubits has an invalid index (i.e. does not satisfy 0 <= qubit < qureg.numQubitsRepresented)
if the elements of \p qubits are not unique
if \p numQubits < 0 or \p numQubits >= qureg.numQubitsRepresented
if \p encoding is not a valid ::bitEncoding
if \p encoding is not compatible with \p numQubits (i.e. \p TWOS_COMPLEMENT with 1 qubit)
if \p numTerms <= 0
if any value in \p overrideInds is not producible by \p qubits under the given \p encoding (e.g. 2 unsigned qubits cannot represent index 9)
if \p numOverrides < 0
if \p exponents contains a negative power and the (consequently diverging) zero index is not contained in \p overrideInds
if \p encoding is ::TWOS_COMPLEMENT, and \p exponents contains a fractional number, but \p overrideInds does not contain every possible negative index (checked only up to 16 targeted qubits) @author Tyson Jones

Function applyPhaseFuncOverridesCopy item path

Function applyPhaseFuncOverrides