Measurements

Functions for effecting destructive measurements. More...

Functions
qreal	applyForcedMultiQubitMeasurement (Qureg qureg, int *qubits, int *outcomes, int numQubits)
qreal	applyForcedMultiQubitMeasurement (Qureg qureg, std::vector< int > qubits, std::vector< int > outcomes)
qreal	applyForcedQubitMeasurement (Qureg qureg, int target, int outcome)
qindex	applyMultiQubitMeasurement (Qureg qureg, int *qubits, int numQubits)
qindex	applyMultiQubitMeasurementAndGetProb (Qureg qureg, int *qubits, int numQubits, qreal *probability)
qindex	applyMultiQubitMeasurementAndGetProb (Qureg qureg, std::vector< int > qubits, qreal *probability)
int	applyQubitMeasurement (Qureg qureg, int target)
int	applyQubitMeasurementAndGetProb (Qureg qureg, int target, qreal *probability)

Detailed Description

Functions for effecting destructive measurements.

Function Documentation

applyForcedMultiQubitMeasurement() [1/2]

qreal applyForcedMultiQubitMeasurement	(	Qureg	qureg,
		int *	qubits,
		int *	outcomes,
		int	numQubits )

Note

Documentation for this function or struct is under construction!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 1877 of file operations.cpp.

                                                                                               {
    validate_quregFields(qureg, __func__);
    validate_targets(qureg, qubits, numQubits, __func__);
    validate_measurementOutcomesAreValid(outcomes, numQubits, __func__);
 
    auto qubitVec = util_getVector(qubits, numQubits);
    auto outcomeVec = util_getVector(outcomes, numQubits);
 
    // ensure probability of the forced measurement outcome is not negligible
    qreal prob = calcProbOfMultiQubitOutcome(qureg, qubits, outcomes, numQubits); // harmlessly re-validates
    validate_measurementOutcomesProbNotZero(outcomes, numQubits, prob, __func__);
 
    // project to the outcome, renormalising the surviving states
    (qureg.isDensityMatrix)?
        localiser_densmatr_multiQubitProjector(qureg, qubitVec, outcomeVec, prob):
        localiser_statevec_multiQubitProjector(qureg, qubitVec, outcomeVec, prob);
 
    return prob;
}

Referenced by applyForcedMultiQubitMeasurement(), and TEST_CASE().

applyForcedMultiQubitMeasurement() [2/2]

qreal applyForcedMultiQubitMeasurement	(	Qureg	qureg,
		std::vector< int >	qubits,
		std::vector< int >	outcomes )

Warning

This function has not yet been unit tested and may contain bugs. Please use with caution!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Note

Documentation for this function or struct is under construction!

Remarks

This function is only available in C++.

Definition at line 1904 of file operations.cpp.

                                                                                              {
    validate_measurementOutcomesMatchTargets(qubits.size(), outcomes.size(), __func__);
 
    return applyForcedMultiQubitMeasurement(qureg, qubits.data(), outcomes.data(), outcomes.size());
}

applyForcedQubitMeasurement()

qreal applyForcedQubitMeasurement	(	Qureg	qureg,
		int	target,
		int	outcome )

Note

Documentation for this function or struct is under construction!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 1813 of file operations.cpp.

                                                                        {
    validate_quregFields(qureg, __func__);
    validate_target(qureg, target, __func__);
    validate_measurementOutcomeIsValid(outcome, __func__);
 
    // note that we do not merely invoke applyForcedMultiQubitMeasurement()
    // because we must validate the renormalising probability and
    // report this function's name during the error message
    qreal prob = calcProbOfQubitOutcome(qureg, target, outcome); // harmlessly re-validates
    validate_measurementOutcomeProbNotZero(outcome, prob, __func__);
 
    // project to the outcome, renormalising the surviving states
    (qureg.isDensityMatrix)?
        localiser_densmatr_multiQubitProjector(qureg, {target}, {outcome}, prob):
        localiser_statevec_multiQubitProjector(qureg, {target}, {outcome}, prob);
 
    return prob;
}

Referenced by TEST_CASE().

applyMultiQubitMeasurement()

qindex applyMultiQubitMeasurement	(	Qureg	qureg,
		int *	qubits,
		int	numQubits )

Note

Documentation for this function or struct is under construction!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 1832 of file operations.cpp.

                                                                           {
    validate_quregFields(qureg, __func__);
    validate_targets(qureg, qubits, numQubits, __func__);
 
    qreal prob = 0; // ignored
 
    // below validates post-measurement and would report 'AndGetProb' function suffix. Eh!
    return applyMultiQubitMeasurementAndGetProb(qureg, qubits, numQubits, &prob);
}

Referenced by TEST_CASE().

applyMultiQubitMeasurementAndGetProb() [1/2]

qindex applyMultiQubitMeasurementAndGetProb	(	Qureg	qureg,
		int *	qubits,
		int	numQubits,
		qreal *	probability )

Note

Documentation for this function or struct is under construction!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 1842 of file operations.cpp.

                                                                                                         {
    validate_quregFields(qureg, __func__);
    validate_targets(qureg, qubits, numQubits, __func__);
 
    // find the probability of all possible outcomes...
    qindex numProbs = powerOf2(numQubits);
 
    // by allocating a temp vector, and validating successful (since exponentially big!)
    vector<qreal> probs;
    auto callback = [&]() { validate_tempAllocSucceeded(false, numProbs, sizeof(qreal), __func__); };
    util_tryAllocVector(probs, numProbs, callback);
 
    // populate probs
    calcProbsOfAllMultiQubitOutcomes(probs.data(), qureg, qubits, numQubits); // harmlessly re-validates
 
    // we cannot meaningfully sample these probs if not normalised
    validate_measurementProbsAreNormalised(probs, __func__);
 
    // randomly choose an outcome
    qindex outcome = rand_getRandomMultiQubitOutcome(probs);
    *probability = probs[outcome];
 
    // map outcome to individual qubit outcomes
    auto qubitVec = util_getVector(qubits, numQubits);
    auto outcomeVec = vector<int>(numQubits);
    getBitsFromInteger(outcomeVec.data(), outcome, numQubits);
 
    // project to the outcomes, renormalising the surviving states
    (qureg.isDensityMatrix)?
        localiser_densmatr_multiQubitProjector(qureg, qubitVec, outcomeVec, *probability):
        localiser_statevec_multiQubitProjector(qureg, qubitVec, outcomeVec, *probability);
 
    return outcome;
}

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

applyMultiQubitMeasurementAndGetProb() [2/2]

qindex applyMultiQubitMeasurementAndGetProb	(	Qureg	qureg,
		std::vector< int >	qubits,
		qreal *	probability )

Warning

This function has not yet been unit tested and may contain bugs. Please use with caution!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Note

Documentation for this function or struct is under construction!

Remarks

This function is only available in C++.

Definition at line 1899 of file operations.cpp.

                                                                                                 {
 
    return applyMultiQubitMeasurementAndGetProb(qureg, qubits.data(), qubits.size(), probability);
}

applyQubitMeasurement()

int applyQubitMeasurement	(	Qureg	qureg,
		int	target )

Note

Documentation for this function or struct is under construction!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 1780 of file operations.cpp.

                                                   {
    validate_quregFields(qureg, __func__);
    validate_target(qureg, target, __func__);
 
    qreal prob = 0; // ignored
    return applyQubitMeasurementAndGetProb(qureg, target, &prob); // harmlessly re-validates
}

Referenced by TEST_CASE().

applyQubitMeasurementAndGetProb()

int applyQubitMeasurementAndGetProb	(	Qureg	qureg,
		int	target,
		qreal *	probability )

Note

Documentation for this function or struct is under construction!

Attention

This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 1788 of file operations.cpp.

                                                                                 {
    validate_quregFields(qureg, __func__);
    validate_target(qureg, target, __func__);
 
    // we do not assume state normalisation (that is posteriori checked),
    // so we must perform two reductions; one for each outcome. We choose
    // to re-enumerate the state (potentially doubling caching costs) to
    // avoid the nuisances/race-cons of parallel adding to two scalars.
    vector<qreal> probs(2);
    probs[0] = calcProbOfQubitOutcome(qureg, target, 0); // harmlessly re-validates
    probs[1] = calcProbOfQubitOutcome(qureg, target, 1); // " "
    validate_measurementProbsAreNormalised(probs, __func__);
 
    // randomly choose the outcome
    int outcome = rand_getRandomSingleQubitOutcome(probs[0]);
    *probability = probs[outcome];
 
    // collapse to the outcome
    (qureg.isDensityMatrix)?
        localiser_densmatr_multiQubitProjector(qureg, {target}, {outcome}, *probability):
        localiser_statevec_multiQubitProjector(qureg, {target}, {outcome}, *probability);
 
    return outcome;
}

Referenced by applyQubitMeasurement(), and TEST_CASE().