Function applyMultiVarPhaseFuncOverrides

pub unsafe extern "C" fn applyMultiVarPhaseFuncOverrides(
    qureg: Qureg,
    qubits: *mut c_int,
    numQubitsPerReg: *mut c_int,
    numRegs: c_int,
    encoding: bitEncoding,
    coeffs: *mut f64,
    exponents: *mut f64,
    numTermsPerReg: *mut c_int,
    overrideInds: *mut c_longlong,
    overridePhases: *mut f64,
    numOverrides: c_int,
)

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

See applyMultiVarPhaseFunc() first for a full description.

• As in applyMultiVarPhaseFunc(), the arguments \p coeffs and \p exponents specify a multi-variable phase function \f$f(\vec{r})\f$, where \f$\vec{r}\f$ is determined by the sub-registers in \p qubits, and ::bitEncoding \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$\vec{r}\f$ for which to explicitly set the induced phase change.\n While flat, \p overrideInds should be imagined grouped into sub-lists of length \p numRegs, which specify the full \f${r_1,; \dots ;r_{\text{numRegs}} } \f$ coordinate to override. \n Each sublist corresponds to a single element of \p overridePhases. \n For example,

  int numRegs = 3;
  int numOverrides = 2;
  long long int overrideInds[] = { 0,0,0,   1,2,3  };
  qreal overridePhases[]       = { M_PI,   - M_PI };

  denotes that any basis state of \p qureg with sub-register values \f${r_3,r_2,r_1} = {0, 0, 0}\f$ (or \f${r_3,r_2,r_1} = {1,2,3}\f$) should receive phase change \f$\pi\f$ (or \f$-\pi\f$) in lieu of \f$\exp(i f(r_3=0,r_2=0,r_1=0))\f$.\n\n

  Note that you cannot use applyMultiVarPhaseFuncOverrides() to override divergences in \f$f(\vec{r})\f$, since each diverging value \f$r_j\f$ would need to be overriden as an \f$\vec{r}\f$ coordinate for every basis state of the other registers; the number of overrides grows exponentially. Ergo, if \p exponents contains a negative number (diverging at \f$r_j=0\f$), or \p exponents contains a fractional number despite \p encoding = ::TWOS_COMPLEMENT (producing complex phases at negative indices), you must instead call applyPhaseFuncOverrides() for each variable in turn and override the diverging \f$r_j\f$ (each independently of the other registers).

• The interpreted overrides can be previewed in the QASM log, as a comment. \n For example:

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

  may show

  // Here, applyMultiVarPhaseFunc() multiplied ...
  //   though with overrides
  //     |x=0, y=0, z=0> -> exp(i 3.14159)
  //     |x=1, y=2, z=3> -> exp(i (-3.14159))

\n

@see

• applyNamedPhaseFunc() for a set of specific and potentially multi-variable 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 all the qubit indices contained in each sub-register @param[in] numQubitsPerReg a list of the lengths of each sub-list in \p qubits @param[in] numRegs the number of sub-registers, which is the length of both \p numQubitsPerReg and \p numTermsPerReg @param[in] encoding the ::bitEncoding under which to infer the binary value \f$r_j\f$ from the bits of a sub-register @param[in] coeffs the coefficients of all terms of the exponential polynomial phase function \f$f(\vec{r})\f$ @param[in] exponents the exponents of all terms of the exponential polynomial phase function \f$f(\vec{r})\f$ @param[in] numTermsPerReg a list of the number of \p coeff and \p exponent terms supplied for each variable/sub-register @param[in] overrideInds a flattened list of sub-register coordinates (values of \f$\vec{r}\f$) of which to explicit set the phase change @param[in] overridePhases a list of replacement phase changes, for the corresponding \f$\vec{r}\f$ values in \p overrideInds @param[in] numOverrides the lengths of list \p overridePhases (but not necessarily of \p overrideInds) @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 (including if sub-registers overlap)
• if \p numRegs <= 0 or \p numRegs > 100 (constrained by MAX_NUM_REGS_APPLY_ARBITRARY_PHASE in QuEST_precision.h)
• if \p encoding is not a valid ::bitEncoding
• if the size of any sub-register is incompatible with \p encoding (e.g. contains fewer than two qubits in \p encoding = \p TWOS_COMPLEMENT)
• if any element of \p numTermsPerReg is < 1
• if \p exponents contains a negative number
• if \p exponents contains a fractional number despite \p encoding = ::TWOS_COMPLEMENT
• if any value in \p overrideInds is not producible by its corresponding sub-register under the given \p encoding (e.g. 2 unsigned qubits cannot represent index 9)
• if \p numOverrides < 0 @author Tyson Jones