Conversion functions for signed integers

[msoeken]

Conversion functions for signed integers

Conceptual overview

Returns Boolean arrays based on two's complement representations of signed integers.

This should be added to the Numerics package.

Proposal

New and modified functions, operations, and UDTs

namespace Microsoft.Quantum.Convert {

/// # Summary
/// Computes signed integer of two's complement encoding.
function BoolArrayAsSignedInt(bits : Bool[]) : Int { ... }

/// # Summary
/// Computes two's complement encoding as bit array from signed integer
function SignedIntAsBoolArray(number : Int, numBits : Int) : Bool[] { ... }

}

Other functions

The following functions are related and might be discussed in a future API proposal:

namespace Microsoft.Quantum.Convert {

/// # Summary
/// Returns signed integer from bit encoding of unsigned integer
function IntAsSignedInt(number : Int, numBits : Int) : Int { ... }

/// # Summary
/// Returns unsigned integer from bit encoding of signed integer
function SignedIntAsInt(number : Int, numBits : Int) : Int { ... }

}

(see also discussion in the comments)

[tcNickolas]

This API needs examples to clarify what exactly they do, especially the ones converting between Int and SignedInt. I find the last two functions a bit confusing, given that Q# Int type is signed - I wonder if it makes sense to name them UnsignedIntAsSignedInt and SignedIntAsUnsignedInt?

[msoeken]

That makes sense, however, this will result in some inconsistencies with current APIs, e.g., BoolArrayAsInt or IntAsBoolArray. I suggest to drop the last two functions for now.

[msoeken]

Cassandra Granade (@cgranade) remarked during the June 2022 API review that we should coordinate this with the Q# language discussion around bit vectors in general. Stefan J. Wernli (@swernli) and Bettina Heim (@bettinaheim), could you provide some additional input here.

[swernli]

Mathias Soeken (@msoeken), We've been discussing the possibility of introducing an explicitly sized Bitword or Bitfield type to capture the notion of bits of a specific width. These proposed APIs could then be morphed into something that takes a Bitfield while being generic across the width and converting it into our Int representation. I think the APIs as written would continue to encourage folks thinking of the Q# Int type as the type to use for arbitrary bit-wise operations, and we'd like to start moving away from that.

If we do get to the point where we introduce a specific type for bits with a known width, I expect we'd want to deprecate APIs that interpret Int type input with a specific width and push people toward APIs related to the new type.

[msoeken]

Stefan J. Wernli (@swernli), thanks for the input. I created these functions for some tests for fixed point operations which are based on signed integer operations. In light of your comment I am closing this issue and add these functions internally to support the mentioned test cases.