API Proposal: Add Tau to System.Math(F) class

[aaronfranke]

This is an API proposal for adding Tau to System.Math and System.MathF. These values would be exactly equal to 2 times Math.PI and 2 times MathF.PI respectively, and would represent a full rotation around the unit circle in radians.

Rationale and usage

The System.Math class currently has PI, but there is one other circle constant that is quite common and useful that is missing: Tau (τ), which is 2π, or about 6.283185307179586476925.

Tau represents a rotation all the way around the circle, in radians. As demonstrated in the Tau manifesto, this value is extremely common throughout numerous mathematical functions.

In my own experience writing code that works with angles and rotations, I have found that using Tau results in much cleaner code. Some examples:

• If you need to write down a rotation in your code, it is much easier to understand when expressed in terms of Tau.

  • It is immediately clear that double rotation = Math.Tau / 3; is a rotation one third of the way around the unit circle in radians, and double rotation = Math.Tau * 0.6; is a rotation 60% of the way around the unit circle in radians.

  • Using Pi, those values would have to be written as Math.PI * 2 / 3 and Math.PI * 1.2 (or * 2 * 0.6) respectively, which is much less clear.

  • Here's an image pulled from the Tau manifesto to illustrate the point:

• If you have rotation represented as a ratio (0 to 1) of how far it is around the unit circle, then you can multiply that ratio by Tau to get a rotation around the unit circle of radians.

  • If you have code that works iteratively, and you have a variable called delta which represents the time passed since last frame, code like rotation += delta * Math.Tau; will rotate once per second. This can then simply be multiplied with the desired rate per second. Without Math.Tau, you would need to multiply by 2, adding complexity and confusion.

• If you are accepting input as a rotation and need to normalize the input, you could use value % Math.Tau to normalize the input. With Pi, you would need to write value % Math.PI * 2

  • Note that if you need to handle negative values, you would also need a helper method.

• While I'm not an expert on audio, just from a search in Godot's source code, it seems that code working with audio waveforms deals with Tau (or 2*Pi) very frequently as well.

Tau is used commonly in the Godot game engine.

Obviously I could just create my own helper class for this, but it would be better if it was implemented in .NET and C#, available for all users of .NET and C#.

Not everyone would use it, and that's fine, but I think it is best if .NET and C# encourage writing cleaner code by allowing developers to use Tau in addition to PI "out of the box".

Proposed API

The following line would be added to System.Math:

public const double Tau = 6.283185307179586476925;

The following line would be added to System.MathF:

public const float Tau = 6.283185307f;

Details

If you need more details, consider reading through the Tau manifesto.

Open Questions

The name TwoPi has also been suggested. It should be considered, but I think Tau is a better choice. The name Tau has been popularized by articles such as the Tau manifesto. The Greek letter τ (tau) resembles a T, which can stand for "turn", and it is visually similar to the Greek letter π (pi).

Pull Request

None so far.

Updates

#24678 (comment)

[tannergooding]

Only Math.Pi and Math.E are exposed constants. The others are special test inputs/outputs (only defined in the unit test library) that are used to validate the math functions return the way expected value for some "well-know" values.

[aaronfranke]

Why not have more exposed constants? They are useful, after all.

[jnm2]

Are they? Let me turn that around and ask, why? Is it super common to maintain your own tau and half-pi constants, such that this would lift a burden from people? That's new to me.

The fact that you seem to not be recognizing xkcd’s ‘pau’ as a joke raises a red flag in my mind.

[tannergooding]

I don't have any specific preference for or against exposing them. There are some libm implementations that expose similar constants, but they also haven't been exposed as part of the "public surface area" in the actual C/C++ standards.

They do represent core values that various math libraries may need to consume/produce; However, they are also just constants with well-defined values, so it isn't difficult for any particular library to define (and has no impact on the IL generated outside of having a member you can discover via reflection).

[aaronfranke]

I do know it's a joke, but it's still a simple name to use. Would you rather call the variable Math.THREEHALVESPI or Math.THREEQUARTERSTAU?

If they're simple to define in any library, why not define them in this library?

[tannergooding]

If they're simple to define in any library, why not define them in this library?

1. I don't think anyone has proposed it yet.
2. There are many more (IMO) useful APIs to add to CoreFX, that provide significant benefit and that are not trivial to implement (this includes APIs in the System.Math library)

[tannergooding]

@aaronfranke, if you do want to "officially" propose CoreFX add the APIs, you should follow the steps here and submit a "formal" API proposal (probably by just updating the OP, rather than opening a new issue).

[karelz]

How common are these constants? How often are they used by System.Math users?
The names should be something everyone recognizes (discoverability), otherwise their value goes significantly down.

why not define them in this library

We don't add every API we can, but only APIs, which are useful for a wider developer audience and are truly used / useful in real-world scenarios. Otherwise we would drown in lots of marginal APIs - making it harder for developers to choose which APIs to use. Everything comes at a cost - general API surface ease-of-use in this case.

[JonHanna]

How common are these constants?

Tau is not very commonly used, but it has its advocates (though the symbol has also been used for ½π and for the golden ratio instead of φ). Pau was invented by Randal Munroe to make fun of people who argue about whether or not we should use Tau.

[tannergooding]

@karelz, they are fairly core mathematical constants that are used in multiple places (we use many of them for validating correctness in our Math APIs, and I've seen a few scattered about in both managed and native land for CoreFX/CoreCLR). They are generally defined to account for minor inaccuracies in the floating-point format (e.g. 2 * Math.PI may be slightly different than Math.TwoPi)

However, as indicated above, since these are well-defined constants, it is also trivial to add them to your own code base (but equally as trivial to add them to CoreFX).

LibM defines the following: https://www.gnu.org/software/libc/manual/html_node/Mathematical-Constants.html#Mathematical-Constants. If we were to add any constants, I would think they should be these

I would also vote we use names like TwoPi, rather than Tau.

[jnm2]

In theory, TwoPi and HalfPi have the exact same precision as PI but the exponent is incremented or decremented, right? Things like M_1_PI make a lot more sense to me.

[tannergooding]

In theory, TwoPi and HalfPi have the exact same precision as PI but the exponent is incremented or decremented, right?

Basically, yes.

const double pi_d      = 3.1415926535897932;    // 0x400921FB54442D18
const double two_pi_d  = 6.2831853071795865;    // 0x401921FB54442D18
const double half_pi_d = 1.5707963267948966;    // 0x3FF921FB54442D18

const float pi_f       = 3.14159265f;           // 0x40490FDB
const float two_pi_f   = 6.28318531f;           // 0x40C90FDB
const float half_pi_f  = 1.57079633f;           // 0x3FC90FDB

[tannergooding]

And, for the default rounding mode, Math.PI * 2 is exactly the same as Math.TwoPi. But it may not always be exactly the same in all rounding modes and other more complex constants may differ.

[jnm2]

In default rounding mode, how is it possible for the most precise representations of ComplexConstant and 2 * ComplexConstant not to have the exact same mantissa no matter how complex the constant is?

[tannergooding]

In default rounding mode, how is it possible for the most precise representations of ComplexConstant and 2 * ComplexConstant not to have the exact same mantissa no matter how complex the constant is?

Denormal numbers, where the exponent is zero 😄