Ambiguous parameter name in custatevecSwapIndexBits

[TysonRayJones]

Hi beautiful cuStateVec team!

Imagine performing an arbitrarily-controlled (i.e. some control qubits may be in state 0) SWAP gate using the non-distributed custatevecSwapIndexBits(). Unlike other arbitrarily-controlled functions (e.g. custatevecapplymatrix()) which accept explicit control bit values:

const int32_t *controls,
const int32_t *controlBitValues, 

the custatevecSwapIndexBits function instead accepts

const int32_t *maskBitString,
const int32_t *maskOrdering, 

The doc does not make clear how to use these arguments; are they merely the reversed order of the above control parameters?

The relevant example code makes the unfortunate choice of controlling upon qubit index 1 with state 1, so does not disambiguate:

// swap the state vector elements only if 1st qubit is 1
const int maskLen = 1;
int maskBitString[] = {1};
int maskOrdering[] = {1};

...

custatevecSwapIndexBits(
    handle, d_sv, CUDA_C_64F, nIndexBits, bitSwaps, nBitSwaps,
    maskBitString, maskOrdering, maskLen)

What is really throwing me off is the vagueness of the parameter name maskOrdering, which the doc describes as

maskOrdering – [in] pointer to a host array to specify the ordering of maskBitString

Yet the example code appears to set maskOrdering to a list of bit indices of the masked bits, corresponding to the order of maskBitString. This is a stronger specification than just an "ordering".

If I have understood the doc and example correctly, I would propose a change like:

• swap the order of maskOrdering and maskBitIndices, to make it consistent with the order of controls and controlBitValues in the rest of the API
• rename maskOrdering to maskBitIndices

[ymagchi]

Hi @TysonRayJones,
Thank you for raising this item.

The input arguments controls/controlBitValues and maskBitString/maskOrdering are different in some contexts:

• In index bit swap APIs, a bit position can be included in both the mask string and swapped bits.
• Gate application APIs can pass null pointer to controlBitValues when all control values are 1 while index bit swap APIs require both maskBitString and maskOrdering parameters to specify the bit mask.

For the bit ordering scheme in the cuStateVec, we describe it in https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/overview.html#bit-ordering. We uniformly call the bit positions of each element of a bit string array as bitOrdering or maskOrdering.

[TysonRayJones]

Hi @ymagchi,

Ahh that's very helpful, thanks very much! So there are four functions accepting controlBitValues, seven accepting maskOrdering and ten accepting bitOrdering.

I suppose that custatevecSwapIndexBits is somewhat unique in the API; it is both imaginable as a ubiquitous quantum gate (or a sequence thereof) or generically as a bit-based permuter (much like the real gate). Users expecting the former treatment (like me hehe) may be surprised that its API differs from the other gates. I wonder if that warrants an additional note in the documentation under the paragraph about maskBitString, such as:

To effect a controlled-swap operation, set maskBitString=controlBitValues and maskOrdering=controls, where controlBitValues and controls are as they appear in functions like custatevecApplyMatrix()

In any case, it seems prudent to disambiguate the example from this...

    // swap the state vector elements only if 1st qubit is 1
    const int maskLen = 1;
    int maskBitString[] = {1};
    int maskOrdering[] = {1};

to something like

    // swap the state vector elements where the 2nd and 3rd qubits are respectively 0 and 1
    const int maskLen = 2;
    int maskBitString[] = {0, 1};  // bits
    int maskOrdering[] = {1, 2};  // indices

(although of course that requires changing the example statevector)

In any case, thank you for the clarification!