Enabling both std and libm APIs at the same time

[aleksa2808]

Would it be feasible to have both the std and libm functionalities enabled at the same time, so that users of this library can choose which implementation to use on their own? As far as I understand, at the moment only one or the other can be used which is problematic in certain scenarios.

As an example, I am currently working on an issue in a multiplayer game demo that uses the Bevy engine, GGRS rollback networking and Rapier physics. In it, it is required for most physics-related operations to be deterministic across hardware, but currently two networked instances desynchronize at some point because of sin_cos function results. The specific call in question is happening in glam's Quat::from_rotation_z method, which when replaced with the libm implementation behaves consistently across an M1 and x86 machine. However, I cannot enable the usage of libm functions from outside glam because if any other crate in the dependency tree is using glam with the std feature turned on it overrides the usage of libm. If both APIs would be exposed then the crates that need the deterministic functionality could offer an enhanced-determinism feature without affecting crates that want faster hardware-dependent functions.

Another benefit of offering both implementations at the same time would be that the crate features would better conform to cargo's "additive features" guidline. Quoting from the cargo book:

When a dependency is used by multiple packages, Cargo will use the union of all features enabled on that dependency when building it. This helps ensure that only a single copy of the dependency is used. [...] A consequence of this is that features should be additive. That is, enabling a feature should not disable functionality, and it should usually be safe to enable any combination of features.

Of course, while this would certainly benefit me (and others that wish to build a rollback networking based game on top of Bevy), I might be missing important insight into why things are the way they are right now so I would greatly appreciate any feedback regarding this proposal.

Edit:

Updating with some more information based on a related discussion in bevy engine's discord. The following quote presents two different, mutually exclusive changes to glam which, if either of these were implemented, would enable building games such as the one mentioned above:

• glam exposes both implementations (these can be behind flags) and leaves it up to downstream crates to implement their own enhanced-determinism feature-flags
• glam makes libm override std, so that it's at least never non-deterministic when you expect determinism

My personal concern regarding the second approach would be that it would be possible to unintentionally introduce a crate which depends on the libm feature for some minor deterministic calculations to a large dependency tree which would turn on the slower math operations for the entire project which might not need deterministic operations. However, as I stated in the discord discussion, I might be overestimating the performance hit of enabling libm.

[bitshifter]

I think that sounds reasonable. There were some other suggestions around being able to swap out trig functions for something more precise I'll try to find and link to this thread.

Currently glam has a fast-math option which is less deterministic on the premise that out of the box glam should be deterministic. However as you point out, users may need to use libm for more deterministic math functions, which would suggest making the fast-math behaviour the default and enhanced determinism opt in (which was originally suggested by the contributor to introduce fast-math but at the time I disagreed).

[bitshifter]

The discussion I was thinking of was on this PR, ehanced-determinism was suggested there as well. #270

[bitshifter]

And another thread #350.

[aleksa2808]

Which of the two options from the edit would you prefer then? 'glam' having both APIs exposed, or making the 'std' feature the default (remove the flag) and 'libm' one the one that has precedence if enabled (and possibly rename it to 'enhanced-determinism')?

[bitshifter]

It sounds like rapier does something like this so I'd like to check how they are handling it before committing to one way or another.

[bitshifter]

In rapier the enhanced-determinism feature enables simba/force_libm. In simba there's the following dep:

libm_force  = { package = "libm", version = "0.2", optional = true }

in glam it would be a case of adding that and then providing a wrapper for math calls, since std will still be there we need to call the libm ones instead.

[aleksa2808]

Yeah, from the brief look I've had of this part it seems like their order of precedence is libm < std < libm_force with std being the default flag.
In this scenario I'm not really sure what would be the use case for the libm flag itself? std having lower priority I understand as "if it's not an issue to anyone, let's prefer speed", but I'm not sure what the libm flag would communicate?
This also seems more like the second option from my edit, with the libm flag in glam taking precedence over std. For me personally the two APIs approach still seems more like the "Cargo way" but I'm completely open to the idea that users just find the swappable implementations easier since both simba and glam do things like this.

[bitshifter]

It's not clear to me why they've done it that way in simba.

At the moment in glam libm uses num-traits to implement math methods if std is not enabled. If you have std and libm enabled then num-traits will use the std math implementations, libm will only be used if std is not enabled.

I think for glam probably the easiest way to do this would be to not use num-traits and provide math functions that forward to the method that the use has requested. That way if they depend on libm then they get libm whether or not std is enabled. It we don't use traits then there will be a compile error with the libm feature enabled if people accidentally try and use the std math methods.

See https://github.com/rust-num/num-traits/blob/master/src/float.rs

[bitshifter]

I had a draft PR for this #389. If the libm feature is enabled, those methods are used regardless of whether or not std is enabled.
For determinism there are probably some other things that need to happen like using libm in some places instead of simd. Which I'd probably tie to an enhanced-determinism feature (which would also enable libm).

[maniwani]

SIMD is OK to use where it doesn't change the order of operations. For example, it's OK to have each lane calculate an independent sum, but not OK to calculate one sum using multiple lanes. Every operation rounds its result, so floating-point math is non-associative. As long as every computation happens in the same order as the scalar case, it should be consistent.

Would libm need to add x2, x4, x8, etc. variants of its functions to ensure that?

[bitshifter]

Ultimately the simd method implementations are different so without testing it I can't make any guarantees that the order of operations and results will be the same. There's also at least one simd trig function that would need to be switched to using libm for enhanced determinism, but that's a relatively easy problem to solve.

[bitshifter]

I've merged that change to main now so libm will override std if building with std.

I haven't added any other determinism flags. I think for cross platform determinism you will probably also need to build with scalar-math enabled.

[aleksa2808]

Wow, you work fast! After overriding the glam crate with the one containing these changes the issue I was working on seems fixed (no more desyncs on M1/x86 in a rollback networked game).

I'll have to delve a bit deeper into the cross-platform determinism problem in order to understand what more needs to be added for the enhanced-determinism flag, but bevy might then want to wait until that is available in order to implement enhanced-determinism itself.