Shamrock 2025.10.0
Astrophysical Code
Loading...
Searching...
No Matches
shamunits Directory Reference
Directory dependency graph for shamunits:

Files

 
exemple.cpp

Detailed Description

Shamrock units library

This is the units library in use in the Shamrock code, this repository will be updated when change are made to this library in the Shamrock monorepo.

A unit, a prefix and a physical constant are all the same thing: a shamunits::Unit, i.e. an SI dimension and a factor. They live in three tables:

and compose with *, / and upow. A UnitSystem<T> gives the value of any of them in that system with get<u>(), and to<u>() goes the other way. Each table also has a from_name lookup for names only known at run time (this is what the Python bindings use).

Everything is constexpr: with a compile-time unit, get<u>() is the product of the needed base-unit powers and the unit's factor, with no division, and it folds to a constant when the unit system is itself constexpr.

Here is an example of the usage of the units library (exemple.cpp):

#include <iostream>
int main(void) {
using namespace shamunits;
// create si units
constexpr UnitSystem<double> si{};
// get the value of au^2 in the unit system
// but it is quite big :)
std::cout << si.get<upow(units::astronomical_unit, 2)>() << std::endl;
/*
* create a unit system with time in Myr, length in au, mass in solar masses
*/
constexpr UnitSystem<double> astro{
};
// this time it returns 1 because the base length is the astronomical unit
std::cout << astro.get<upow(units::astronomical_unit, 2)>() << std::endl;
// in those units G is 3.94781e+13
std::cout << astro.get<constants::G>() << std::endl;
// units compose: one km/s is 210950 au/Myr
std::cout << astro.get<prefix::kilo * units::metre / units::second>() << std::endl;
// a value returned by the code in astro units (here 12 Myr) converted to seconds:
// prints 3.78691e+14 s
double t = 12;
std::cout << t * astro.to<units::second>() << " s" << std::endl;
// units, prefixes and constants can also be looked up by name at run time:
// one parsec is 206266 au
std::cout << astro.get(units::from_name("pc")) << std::endl;
// Constants<T> is kept for backward compatibility: this is astro.get<constants::G>()
std::cout << Constants<double>{astro}.get<constants::G>() << std::endl;
}
Physical constants in a unit system, plus a few dimensionless numbers.
A unit system: the values of the seven SI base units in code units.
constexpr Tret to() const noexcept
constexpr Tret get() const noexcept
Value of the compile-time unit u in this system.
The table of physical constants: each constant is a Unit (its SI value and dimension).
constexpr Unit sol_mass
solar mass
namespace containing the units library
constexpr Unit< T > upow(Unit< T > u, int n) noexcept
Integer power of a unit.
Definition Unit.hpp:147
The table of unit prefixes: a prefix is a dimensionless Unit.
constexpr Unit kilo
k
constexpr Unit mega
M.
The table of units: one constexpr Unit per unit, plus its name registry.
Unit from_name(std::string_view name)
Unit from its long or short name; throws std::invalid_argument if unknown.
constexpr Unit second
s
constexpr Unit metre
m
constexpr Unit year
yr (Julian)
constexpr Unit astronomical_unit
au

src/shamunits/doc/godbolt.cpp is a single-file version of the library plus this example, ready to paste in Compiler Explorer (with -std=c++20). It is generated by tools/gen_shamunits_amalgamation.py.