API: Consider the formatted output/logging functions

[kuzminrobin]

(Request For Early Feedback. Work in Progress)

Latest State

• Brief Illustration of the Proposed Changes (with Code Fragments and Usage Examples)
• What Happens to DoubleAsStringWithFormat() and IntAsStringWithFormat().
• How the Changes Cope With the Other Proposals

---

Earlier Story

(Links DoubleAsStringWithFormat(), IntAsStringWithFormat(), Standard numeric format strings, Custom numeric format strings).

Discussion:

[12:42 PM] Bettina Heim
Hi all,
As part of adding support for Q# to the QIR runtime, we came across the logging functions that allow to give a formatting option. Right now, the option seems to be exactly what C# provides. Since this is pretty extensive and I am not eager to blindly duplicate the C# behavior in our native implementation, I would like to gather your input regarding what formatting options we need and want to support going forward?
[12:50 PM] Chris Granade (THEY/THEM)
There's not a single line of Q# in all of our libraries or samples that calls either function...
Thinking to kind of first principles for the language and libraries, though, the whole point of Message is to provide optional logging information back to the host. To that end, I wouldn't think that it's intended that we should provide UX features like formatting at the Q# level.
I know Bettina, Alan and I played around with the concept of a function that would emit logging info other than strings years ago (e.g.: if a Q# program wants to send a Double to the host as a log message); that may be better than trying to handle formatting at the Q# level.
[12:57 PM] Bettina Heim
Chris Granade (THEY/THEM) Do you know why these have been added in the first place? Do you know of anyone else that could be using them? Would it be good to keep some minimal formatting options, or would you suggest deprecating them?
My inclination would be to allow for some minimal formatting, but definitively not the extensive support that C# provides.
Robin Kuzmin, What kind of formatting support does C++ provide?
[1:32 PM] Robin Kuzmin
The simple option is the printf() formatting of C, see "Conversion specifiers" (or a broader picture - "Format of the format string") in the printf() manual page.
As for C++, let me summarize...
As a short answer I would say, C++ formatted output is harder to adapt as an implementation of the Q# calls. And that C++ formatted output would be described here. E.g. see "hex" that will take you to here and show the examples like std::cout << std::hex, after which all the integer output will be in hexadecimal form.

[1:48 PM] Robin Kuzmin
As a minimalistic implementation I would say that we need

• the conversion of any type to string,
• concatenating the strings and string literals,
• and outputting/logging a string.

[1:48 PM] Robin Kuzmin
And most (if not all) of that is already implemented, I believe.

[2:07 PM] Chris Granade (THEY/THEM)

Do you know why these have been added in the first place?

I don't, no; they are amongst the first intrinsics added to the language, IIRC, back when everything was somewhat chaotic.

Do you know of anyone else that could be using them? Would it be good to keep some minimal formatting options, or would you suggest deprecating them?

I'm not aware of such, no; was unable to find a single usage when I looked, so I'm not sure there's a lot of demand for that feature. My initial thought would be to deprecate entirely for now, but happy to discuss further.

[8:20 PM] Robin Kuzmin
I looked at .NET's (C#'s) formatting - Standard numeric format strings and Custom numeric format strings.
looks like for the minimalistic implementation (mentioned in my previous 2 posts) we also need (EN-US locale):

• Hexadecimal (at least for Int type)
• Exponential (scientific)
• Fixed-point (with the specification of number of digits before and after the .)

[msoeken]

The new C++ standard formatting library is similar to Python's formatting capabilities.

[cgranade]

@kuzminrobin: Thank you for opening this; it sounds like there's a few different suggestions made in the thread above. Would you be willing to clarify what changes you'd propose to the Q# API surface so that we can get that scheduled for Thursday's API review board meeting? Thank you!

[kuzminrobin]

@cgranade, @bettinaheim,
Yes, it definitely makes sense to come up with a particular proposal. I'm diving into this and will try to figure out the minimalistic formatting proposal by the API Review Meeting.

@msoeken, thank you for sharing your knowledge! The C++ standard formatting library has been added in C++20, there can be temporary issues with that. In particular, we currently compile our QIR/C++ code with C++14 compiler flag, and the attempt to use C++17 causes compilation errors in the headers provided by MSVC++. I didn't try C++20, this can require an update to the clang/LLVM toolchain, but I expect even more issues with migration to C++20. So the C++ standard formatting library is not something that we can immediately start using (it can require updates in MSVC++).
None the less I don't see that as a blocking issue. We can still move towards that kind of formatting in the minimalistic formatting facility in Q# and implement that formatting manually in C++14 for now, and later on we can replace the manual implementation with the direct calls to the C++ standard formatting library.
It seems to me a good idea to move towards the formatting already known (to the broad audience) from the popular programming languages, such as Python (and less known C++20 features).
I'm working on this.

[kuzminrobin]

Wow!

(C++20) Standard format specification
For basic types and string types, the format specification is based on the format specification in Python.

That's definitely a way to go...

[kuzminrobin]

(Work in progress. Can change)

For Int

Either FormattedI() or Interpolated String Literals.

FormattedI()
Proposed:

namespace Microsoft.Quantum.Convert {
    function FormattedI(fmt : String, value : Int) : String { 
        body intrinsic; 
    }
}

Based on Python's Format Specification Mini-Language.
Usage Example:

// Hexadecimal representation for Int:
let intNum = 42;
let logString = FormattedI("x", intNum);
// Todo: Test corresponding formatting in C++.
// Format String    logString
// "x"             "2a"
// "#x"            "0x2a"
// "04X"           "002A"
// "#06X"          "0X002A"
// "#015_X"        "0X000_0000_002A"    // Optional
Message(logString);

Interpolated String Literals

If chosen then the topic is to be considered in a separate proposal against the qsharp-language.
Based on

• String Literals
• Python's Format examples

Usage Example:

// Hexadecimal representation for Int:
let intNum = 42;
// Todo: Test corresponding formatting in C++.
// Harder to implement, likely requires language change (grammar change):
let logString = $"dec: {intNum}; hex: {intNum:x}; hex: {intNum:#x}; hex: 0x{intNum:04X}; hex: {intNum:#015_X}";
// "dec: 42; hex: 2a; hex: 0x2a; hex: 0x002A; hex: 0X000_0000_002A"
// "dec: {intNum}" is already implemented.
Message(logString);

---

Tested in Python:

>>> intNum = 42
>>> f"dec: {intNum}; {intNum:x}; {intNum:#x}; 0x{intNum:04X}; {intNum:#06X}; {intNum:#015_X}"
'dec: 42; 2a; 0x2a; 0x002A; 0X002A; 0X000_0000_002A'

[kuzminrobin]

(Work in progress. Can change)

For Double

Either FormattedD() or Interpolated String Literals.

FormattedD()
Proposed:

namespace Microsoft.Quantum.Convert {
    function FormattedD(fmt : String, value : Double) : String { 
        body intrinsic; 
    }
}

Usage Examples:

// Fixed point representation for Double:
let doubleNum = 1234567.8901678;   // Or NaN() or <infinity>.
let logString = FormattedD(".4f", doubleNum);
// Todo: Test corresponding formatting in C++.
// Format String    logString
// ".4f"            "1234567.8902"  // Or `nan` or `inf`.
// ".4F"            "1234567.8902"  // Or `NAN` or `INF`. Optional.
// "012.2f"         "001234567.89"  // Or `000000000nan` or `000000000inf`.
Message(logString);

// Scientific notation for Double:
let doubleNum = 1234567.8901678;   // Or NaN() or <infinity>.
let logString = FormattedD(".4e", doubleNum);
// Todo: Test corresponding formatting in C++.
// Format String    logString
// ".4e"            "1.2346e+06"  // Or `nan` or `inf`
// ".4E"            "1.2346E+06"  // Or `NAN` or `INF` Optional.
// "010.2e"         "001.23e+06"  // Or `0000000nan` or `0000000inf`.
Message(logString);

Interpolated String Literals

If chosen then the topic is to be considered in a separate proposal against the qsharp-language.
Usage Examples:

let doubleNum = 1234567.8901678;   // Or NaN() or <infinity>.
let logString = $"{doubleNum:.4f}, {doubleNum:.4F}, {doubleNum:012.2f}";
// Todo: Test corresponding formatting in C++.
// "1234567.8902, 1234567.8902, 001234567.89"
// "nan, NAN, 000000000nan"
// "inf, INF, 000000000inf"

let doubleNum = 1234567.8901678;   // Or NaN() or <infinity>.
let logString = $"{doubleNum:.4e}, {doubleNum:.4E}, {doubleNum:0010.2e}";
// Todo: Test corresponding formatting in C++.
// "1.2346e+06, 1.2346E+06, 001.23e+06"
// "nan, NAN, 0000000nan"
// "inf, INF, 0000000inf"

---

Tested in Python:

>>> doubleNum = 1234567.8901678
>>> f"{doubleNum:.4f}, {doubleNum:.4F}, {doubleNum:012.2f}"
'1234567.8902, 1234567.8902, 001234567.89'

>>> import math
>>> doubleNum = math.nan
>>> f"{doubleNum:.4f}, {doubleNum:.4F}, {doubleNum:012.2f}"
'nan, NAN, 000000000nan'

>>> doubleNum = math.inf
>>> f"{doubleNum:.4f}, {doubleNum:.4F}, {doubleNum:012.2f}"
'inf, INF, 000000000inf'


>>> doubleNum = 1234567.8901678
>>> f"{doubleNum:.4e}, {doubleNum:.4E}, {doubleNum:010.2e}"
'1.2346e+06, 1.2346E+06, 001.23e+06'

>>> doubleNum = math.nan
>>> f"{doubleNum:.4e}, {doubleNum:.4E}, {doubleNum:010.2e}"
'nan, NAN, 0000000nan'

>>> doubleNum = math.inf
>>> f"{doubleNum:.4e}, {doubleNum:.4E}, {doubleNum:010.2e}"
'inf, INF, 0000000inf'

[cgranade]

(Work in progress. Can change)

Duly noted; in the interest of getting this through quickly, please take the following as early feedback.

Format Specification Mini-Language

// Hexadecimal representation for Int:
let intNum = 42;
let logString = Format(intNum, "x");
// Format String    logString
// "x"             "2a"
// "#x"            "0x2a"
// "04X"           "002A"
// "#04X"          "0x002A"
// "#012_X"        "0x0000_0000_002A"    // Optional
Message(logString);

Format examples

In terms of Q# style guide and design principles, we'll need a noun or adjective phrase instead of Format, since this new callable should likely be a function rather than an operation.

Aside from that, which order of inputs is most consistent with currying? I'd imagine the same format string getting applied to multiple different numeric values would be significantly more common than the same numeric value getting formatted with different strings, such that Formatted : (String, Int) -> String might make more sense.

With respect to input types, is it expected that this should only ever work on integers? If we want formatted strings for other kinds of inputs, then we'll need type suffixes to distinguish them:

function FormattedI(fmt : String, value : Int) : String { ... }
function FormattedL(fmt : String, value : BigInt) : String { ... }
function FormattedD(fmt : String, value : Double) : String { ... }

Other questions:

• What namespace would you suggest for this? At the moment, the most analogous functions are in the Microsoft.Quantum.Convert namespace, such that these new functions could go there, perhaps?
• What should happen to IntAsStringWithFormat and other similar existing functions? Should those be deprecated?
• How does this relate to other current or proposed Q# features? E.g., how would this API change if we get discriminated unions feature from Discriminated Unions qsharp-language#51?

// Hexadecimal representation for Int:
let intNum = 42;
// Harder to implement, likely requires language change (grammar change):
let logString = "dec: {intNum}; hex: {intNum:x}; hex: {intNum:#x}; hex: 0x{intNum:04X}";
// "dec: 42; hex: 2a; hex: 0x2a; hex: 0x002A"
Message(logString);

@bettinaheim can speak to this better than I can, but if you want to go on and suggest that as a language change, filing a Q# suggestion would be the right next step to kick off that process. I would be slightly concerned with the use of : here, though, given that in Q# a single colon means exclusively "has the type of," but I digress.

[kuzminrobin]

Thank you for the early feedback, @cgranade.

(For oneself: To do:
See also qsharp-runtime\src\Simulation\QSharpFoundation\Convert\Convert.qs:

    function DoubleAsString(a : Double) : String {
        return $"{a}";
    }

BoolAsString(), IntAsString(), fail $"Unexpected Pauli value {p}.", microsoft/qsharp-language#81,

[msoeken]

Thanks for your response, @kuzminrobin

The C++ standard formatting library has been added in C++20

This just means that it has been to the standard version since C++20, and in the future compilers will pick up implementing it into the standard libraries. However, there is a popular implementation of the formatting proposal, called libfmt, which can be used with earlier versions of C++. But as you already mentioned, the main take away is the formatting syntax and it's familiarity to Python.

[kuzminrobin]

(Work in progress. Can change)

What should happen to IntAsStringWithFormat and other similar existing functions? Should those be deprecated?

DoubleAsStringWithFormat(), IntAsStringWithFormat():
It is proposed to deprecate them.
I don't feel I have enough experience to propose the deprecation period at the moment. See Q# API Design Principles, search for "deprecation period".