Skip to content

0.4.0

Latest
Latest
Compare
Choose a tag to compare
@chiphogg chiphogg released this 12 Dec 16:22
· 1 commit to main since this release
0.4.0
13a7ab9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

0.4.0

Release Notes

User-facing library changes

Potentially breaking changes 💥

  • Old-style .in and .as APIs are finally removed (#350). (These
    have been deprecated for the entire public existence of the library,
    so these callsites really shouldn't exist!) If you have
    q.in<Meters>(), replace with q.in(meters), and so on.
  • Greatly consolidated and simplified our CMake target breakdown: thus,
    many targets disappeared, and were combined into Au::au (#300)
  • Certain qualified function calls (e.g., au::min(a, b)) will now
    cause compiler errors (#330). The fix is to replace them with
    unqualified calls (e.g., min(a, b)). This was always the guidance,
    but now it is mandatory for these functions.
  • Deprecated pascal (#285)

⚠️ The following is not a breaking change, but prepares for a
future breaking change. We have added the as_raw_number(...)
utility (#333). Pass it any dimensionless quantity to have it safely
convert to the equivalent (unitless) raw number. If you pass it a raw
number, it's a no-op. We recommend using this wherever you have a
Quantity calculation that you want to result in a raw number. In the
future (#185), all Quantity calculations will produce Quantity, not
raw numbers, and this function will become necessary --- start using it
today to get ahead of the curve.

Library-included constants

Au now includes certain exactly-defined physical constants out of the
box! Each one can be found in the new "au/constants/..." folder. The
name of the constant will be in all-caps (e.g., SPEED_OF_LIGHT), and
the name of the file will be the snake-case version (e.g.,
speed_of_light.hh). They can be included in a single-file packaging
via --constants (#335). See our constants docs for a full list.

Explicit-rep runtime conversion checkers

We now provide utilities to check every Quantity conversion in the
library! (At least, those whose rep is a fundamental arithmetic type.)
You can call will_conversion_overflow<T>(q, target),
will_conversion_truncate<T>(q, target), or
is_conversion_lossy<T>(q, target) (which is the disjunction of the
first two). As far as we know, runtime conversion checkers (#347, #351)
are a first for any units library!

Integer division updates

Integer division generally has undergone a huge overhaul. We switched
to a much more user friendly API, replacing the integer_quotient(a, b)
pattern with the much more flexible a / unblock_int_div(b) pattern
(#315). We also expanded the set of cases that work out of the box:
quantity-equivalent units no longer require any manual override for
integer division (#275).

Improved unit labels

We have eliminated virtually all instances of the dreaded
[UNLABELED_UNIT]!

First, when scaling a unit by a magnitude, we automatically generate a
new label (#332) that combines the magnitude label (#331) and the input
unit label.

Next, common units will now "do the math for you": the automatically
generated label will express the magnitude in terms of every unique
input unit: instead of COM[in, cm], you get
EQUIV{[(1 / 50) cm], [(1 / 127) in]} (#334). This works for common
point-units as well (#339).

We also removed sources of redundancy from common units, and now
simplify them as much as possible (#310, #338).

Forward declarations

We now provide authoritative forward declarations for core library
features (#312), individual units (#314), and compound units (#342).
See our how-to guide for more on how (and when) to use this feature.

Quantity template parameters

If your Quantity has an integral rep, you can now safely emulate using
values of it as template parameters! This is generally a C++20
feature, but we have provided a C++14 compatible workaround (#318). See
template param docs for a how-to guide on this feature.

CMake, conan, vcpkg updates

This is the first release since we gained community support for both
conan and vcpkg, the two most popular C++ package managers! We updated
the installation instructions to reflect this (#302, #305).

For CMake, we made some changes to make packaging future versions for
conan and vcpkg easier. We consolidated our targets so that most end
users only need to depend on Au::au (#300). We also provided new
options: AU_ENABLE_TESTING (#303) can be disabled to avoid building
tests, and AU_EXCLUDE_GTEST_DEPENDENCY (#311) can be disabled to avoid
the GTest dependency completely (which also disables the testing).
These new options gained CI tests, too (#313).

Improved factoring

We have greatly expanded the set of values N that can be used with our
mag<N>() utility! Instead of naive trial division, we now use two
advanced algorithms. First, the Baillie-PSW fast primality test
(#320, 321, #322, #323, #324) can quickly identify when a number is
prime. (This test is known to be deterministic on all 64-bit inputs.)
Next, for a number known to be composite, we use Pollard's rho algorithm
(#325, #326, #329) as a much faster way to find non-trivial factors.
There are still numbers we cannot factor at compile time, but we do not
know of any that are actually relevant for quantity use cases.

Other enhancements, bugfixes, and refactorings:

  • Several math functions (including min, max, clamp, and %) now
    work with Constant instances; moreover, more overloads of these work
    with Zero than was formerly the case (#330)
  • When any chrono duration auto-converts to an au::Quantity, it'll end
    up with the correct named unit instead of an anonymous scaled unit
    (#276)
  • Added partial support for complex rep types, including std::complex
    (#278)
  • Improved compiler errors when trying to make a Quantity from
    something that is already a Quantity, and similar for
    QuantityPoint (#294)
  • Default-constructed Quantity now explicitly default-constructs its
    value, by policy (#296)
  • Unit symbols can now be scaled by a magnitude (#341)
  • UIToA<uint64_t> generates compile-time string versions of unsigned
    integer types (#337)

Compile time impact

Compile time impact varies depending on the target (and depending on
which features get used). Overall, compile times have increased by
about 100 ms on our test configuration. While this shouldn't be
noticeable for most end users --- for example, it's easily smaller than
the variation in building a single version of the code --- it is around
the upper limit of what we would accept.

It's hard to root cause the slowdown precisely to individual features,
but here are the changes that appear to be the biggest culprits. These
numbers are very rough, but should be in the right ballpark relative
to that 100 ms total:

  • Quantity template parameters: 30 to 50 ms.
  • EQUIV label generation: 10 to 20 ms.
  • Improved factoring: 0 to 30 ms.
  • Mixed Constant/Quantity math: 0 to 20 ms.
  • Magnitude labels and scaled units: 0 to 20 ms.
  • Simplify common unit: 0 to 20 ms.

The individual feature measurements vary from file to file, but the
overall cost is pretty consistent (although 1 out of 4 files experienced
only 60 ms overall regression, not 100 ms).

New units and constants

Units:

Constants:

  • avogadro_constant (#336)
  • boltzmann_constant (#336)
  • cesium_hyperfine_transition_frequency (#336)
  • elementary_charge (#336)
  • luminous_efficacy_540_terahertz (#336)
  • planck_constant (#336)
  • reduced_planck_constant (#336)
  • speed_of_light (#308)
  • standard_gravity (#348)

Tooling updates

  • Single-file script supports constants, individually via --constants,
    or all at once via --all-constants (#335)

Documentation updates

  • Documented constants (#340)
  • Refreshed installation instructions in light of CMake, conan, vcpkg
    support (#302)
  • Added how-to guide for Quantity template parameters (#343)
  • Explained why we do not provide a raw number constructor (#309)
  • Added quantity template params to alternatives guide (#356)
  • Added a new section to troubleshooting guide, and refreshed contents
    (#319)
  • Updated godbolt link so that it automatically includes <iostream>
    (#291)
  • Updated Au's logo, consistent with Aurora's brand refresh (#277)

Repo updates

  • Updated GitHub actions versions (#279, #280, #281, #282, #293, #306)
  • Changed gcc toolchain fetch URL to be more robust (#287)
  • Changed the naming scheme for MSVC compiler versions (#286)
  • Updated to latest version of python packages for generating docs
    (#345)
  • Added a new CI modality that explicitly runs all the tests in C++20
    mode, alongside new C++20-specific use cases (#354)

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2024-07-23..2024-12-12

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

Contributors

tobin, timhirsh, and 13 other contributors
Assets 3
Loading