Function applyParamNamedPhaseFunc

pub unsafe extern "C" fn applyParamNamedPhaseFunc(
    qureg: Qureg,
    qubits: *mut c_int,
    numQubitsPerReg: *mut c_int,
    numRegs: c_int,
    encoding: bitEncoding,
    functionNameCode: phaseFunc,
    params: *mut f64,
    numParams: c_int,
)

Induces a phase change upon each amplitude of \p qureg, determined by a named, paramaterized (and potentially multi-variable) phase function.

See applyNamedPhaseFunc() for full documentation. \n This function merely accepts additional ::phaseFunc names which accept one (or more) parameters.

• Argument \p functionNameCode, which determines the phase function \f$f(\vec{r}, \vec{\theta})\f$, can include parameterised ::phaseFunc names like \p SCALED_NORM, which require additional parameters \f$\vec{\theta}\f$ passed via list \p params.\n For example,

  enum phaseFunc functionNameCode = SCALED_PRODUCT;
  qreal params[] = {0.5};
  int numParams = 1;
  applyParamNamedPhaseFunc(..., functionNameCode, params, numParams);

  invokes phase function \f[ f(\vec{r}, \theta)|_{\theta=0.5} ; = ; 0.5 \prod_j^{\text{numRegs}} ; r_j,. \f] See ::phaseFunc for all named phased functions.

• Functions with divergences, like \p INVERSE_NORM and \p SCALED_INVERSE_DISTANCE, must accompany an extra parameter to specify an overriding phase at the divergence. For example,

  enum phaseFunc functionNameCode = SCALED_INVERSE_NORM;
  qreal params[] = {0.5, M_PI};
  int numParams = 2;
  applyParamNamedPhaseFunc(..., functionNameCode, params, numParams);

  invokes phase function \f[ f(\vec{r}, \theta)|_{\theta=0.5} ; = ; \begin{cases} \pi & ;;; \vec{r}=\vec{0} \ \displaystyle 0.5 \left[ \sum_j^{\text{numRegs}} {r_j}^2 \right]^{-1/2} & ;;;\text{otherwise} \end{cases}. \f] Notice the order of the parameters matches the order of the words in the \p phaseFunc.

  Functions \p SCALED_INVERSE_SHIFTED_NORM and \p SCALED_INVERSE_SHIFTED_DISTANCE, which can have denominators arbitrarily close to zero, will invoke the divergence parameter whenever the denominator is smaller than (or equal to) machine precision REAL_EPS.

• Functions allowing the shifting of unweighted sub-register values, which are \p SCALED_INVERSE_SHIFTED_NORM, and \p SCALED_INVERSE_SHIFTED_DISTANCE, need these shift values to be passed in the \p params argument after the scaling and divergence override parameters listed above. The function \p SCALED_INVERSE_SHIFTED_NORM needs as many extra parameters, as there are sub-registers; \p SCALED_INVERSE_SHIFTED_DISTANCE needs one extra parameter for each pair of sub-registers. For example,

  enum phaseFunc functionNameCode = SCALED_INVERSE_SHIFTED_NORM;
  int qubits[] = {0,1,2,3, 4,5,6,7};
  int qubitsPerReg[] = {4, 4};
  qreal params[] = {0.5, M_PI, 0.8, -0.3};
  int numParams = 4;
  applyParamNamedPhaseFunc(..., qubits, qubitsPerReg, 2, ..., functionNameCode, params, numParams);

  invokes phase function \f[ f(\vec{r}) ; = ; \begin{cases} \pi & ;;; \vec{r}=\vec{0} \ \displaystyle 0.5 \left[(r_1-0.8)^2 + (r_2+0.3)^2\right]^{-1/2} & ;;;\text{otherwise} \end{cases}. \f] and

  enum phaseFunc functionNameCode = SCALED_INVERSE_SHIFTED_DISTANCE;
  int qubits[] = {0,1, 2,3, 4,5, 6,7};
  int qubitsPerReg[] = {2, 2, 2, 2};
  qreal params[] = {0.5, M_PI, 0.8, -0.3};
  int numParams = 4;
  applyParamNamedPhaseFunc(..., qubits, qubitsPerReg, 4, ..., functionNameCode, params, numParams);

  invokes phase function \f[ f(\vec{r}) ; = ; \begin{cases} \pi & ;;; \vec{r}=\vec{0} \ \displaystyle 0.5 \left[(r_1-r_2-0.8)^2 + (r_3-r_4+0.3)^2\right]^{-1/2} & ;;;\text{otherwise} \end{cases}. \f]

• Function \p SCALED_INVERSE_SHIFTED_WEIGHTED_DISTANCE, which effects phase \f[ \text{coeff}/\sqrt{f_x , (x_1-x_2-\Delta_x)^2 + f_y ; (y_1-y_2-\Delta_y)^2 + \dots} \f] (and phase \f$\phi\f$ at divergences) accepts parameters in the following order: \f[ { ; \text{coeff}, ; \phi, ; f_x, ; \Delta x, ; f_y, ; \Delta y, ; \dots ; } \f]

  Note that where the denominator’s \f$\text{sqrt}\f$ argument would be negative (and the resulting phase function complex), the phase is instead set to the divergence parameter \f$\phi\f$.

You can further override \f$f(\vec{r}, \vec{\theta})\f$ at one or more \f$\vec{r}\f$ values via applyParamNamedPhaseFuncOverrides().

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

  startRecordingQASM(qureg);
  applyParamNamedPhaseFunc(...);
  printRecordedQASM(qureg);

  may show

  // Here, applyNamedPhaseFunc() multiplied a complex scalar of form
  //     exp(i (-0.5) / (x y z))

\n

@see

• applyParamNamedPhaseFuncOverrides() to additionally specify phase values for specific sub-register indices.
• applyPhaseFunc() to specify a general single-variable exponential polynomial phase function.
• applyMultiVarPhaseFunc() to specify a general multi-variable exponential polynomial phase function.
• 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] functionNameCode the ::phaseFunc \f$f(\vec{r}, \vec{\theta})\f$ @param[in] params a list of any additional parameters needed by the ::phaseFunc \p functionNameCode @param[in] numParams the length of list \p params @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 \p functionNameCode is not a valid ::phaseFunc
• if \p numParams is incompatible with \p functionNameCode (for example, no parameters were passed to \p SCALED_PRODUCT) @author Tyson Jones @author Richard Meister (shifted functions)