How to use a base unit that's not predefined?
Anaphory opened this issue · comments
It took me a while, reading documentation and experimenting, to define my system of units as
#[macro_use]
extern crate uom;
ISQ!(
uom::si,
i32,
(
millimeter,
kilogram,
millisecond,
ampere,
kelvin,
mole,
candela
)
);
I feel it is not particularly well stated that this is the way to do it.
The target I am aiming for wants to resolve location in centimeters, so the underlying model should use millimeters to avoid too many rounding artefacts. The velocities go up to 300 km/h, so I would ideally want time resolutions of 10^-4 seconds. This would also mean that I could still store a full day in i32, which would be an advantage over just using microseconds.
But I don't see how I can set the resolution to 10^-4 seconds. What's the best way to do it, and could it also go into the documentation somehow?
If anyone else is confused about how to use it, or if you base as an example on this, this is what I did for now. (I noticed I need a smaller length resolution, not a smaller time resolution, to get a better speed resolution, duh, so it's decimillimeters, not decimilliseconds as in my previous post.)
#[macro_use]
extern crate uom;
// With a target location resolution in centimeters, the underlying model
// should use millimeters to avoid too many rounding artefacts. For speeds
// up to 300 km/h at that space resolution, we would need time resolutions
// of 10^-3 seconds.
//
// Now, working in millimeters and i32 already gives us a maximum length of
// 2147 km, which should be sufficient for any track within Germany. Any
// bigger data type will also be sufficient.
//
// For 10^-3 seconds, i32 can represent about 25 days, which is just about
// sufficient most use cases of our simulation. Larger time frames will have to
// use offsets external to the simulation, and have to be persisted, adapted to
// the new offset, and re-started.
//
// However, with millimeters and milliseconds, the base unit of velocity is
// mm/ms = m/s, which is less than resolution of km/h = 0.278 m/s we would like
// to be able to talk about. So we reduce the space resolution once again, to
// 10^-4 meters.
mod trainphysics_units {
#[macro_use]
mod length {
quantity! {
/// Length (base unit meter, m).
quantity: Length; "length";
/// Length dimension, m
dimension: LMT<P1, Z0, Z0>;
units {
@decimillimeter: 0.0001; "dmm", "decimillimeter", "decimillimeters";
@millimeter: 0.001; "mm", "millimeter", "millimeters";
@centimeter: 0.01; "cm", "centimeter", "centimeters";
@meter: 1.; "m", "meter", "meters";
@kilometer: 1000.; "km", "kilometer", "kilometers";
}
}
}
#[macro_use]
mod mass {
quantity! {
/// Mass (base unit kilogram, kg).
quantity: Mass; "mass";
/// Mass dimension, kg
dimension: LMT<Z0, P1, Z0>;
units {
@kilogram: 1.; "kg", "kilogram", "kilograms";
@ton: 1000.; "T", "ton", "tons";
}
}
}
#[macro_use]
mod time {
quantity! {
/// Time (base unit second, s).
quantity: Time; "time";
/// Time dimension, s
dimension: LMT<Z0, Z0, P1>;
units {
@millisecond: 0.001; "ms", "millisecond", "milliseconds";
@second: 1.; "s", "second", "seconds";
@minute: 60.; "min", "minute", "minutes";
@hour: 3600.; "h", "hour", "hours";
@day: 86400.; "d", "day", "days";
}
}
}
#[macro_use]
mod velocity {
quantity! {
/// Velocity (base unit meters per second, m/s).
quantity: Velocity; "velocity";
/// Velocity dimension, m/s
dimension: LMT<P1, Z0, N1>;
units {
@meter_per_second: 1.; "m/s", "meter per second", "meters per second";
@kilometer_per_hour: 2.777_777_777_777_778_E-1; "km/h", "kilometer per hour", "kilometers per hour";
}
}
}
#[macro_use]
mod acceleration {
quantity! {
/// Acceleration (base unit meters per second squared, m/s²).
quantity: Acceleration; "acceleration";
/// Acceleration dimension, m/s²
dimension: LMT<P1, Z0, N2>;
units {
@meter_per_second_squared: 1.; "m/s²", "meter per second squared", "meters per second squared";
}
}
}
#[macro_use]
mod power {
quantity! {
/// Power (base unit Watt).
quantity: Power; "power";
/// Power dimension, m²kg/s³
dimension: LMT<P2, P1, N3>;
units {
@watt: 1.; "W", "watt", "watts";
}
}
}
system! {
/// System of quantities, Q.
quantities: LMT {
length: meter, L;
mass: kilogram, M;
time: second, T;
}
/// System of units, U.
units: U {
mod length::Length,
mod mass::Mass,
mod time::Time,
mod velocity::Velocity,
mod acceleration::Acceleration,
mod power::Power,
}
}
pub mod i32 {
LMT!(
crate::trainphysics_units,
i32,
(decimillimeter, kilogram, millisecond)
);
}
}
use trainphysics_units::i32::{Acceleration, Length, Mass, Time, Velocity, Power};
@Anaphory Did you end up resolving all your issues or did you still have some questions?
Setting up new type aliases with different base units is definitely not intuitive and probably not easy to discover. Any concrete suggestions, especially about documentation, based on your experience?
For anyone coming to this issue in the future, examples/base.rs, gives a minimal example of setting up type aliases with different base units. The ISQ! macro is also documented.
Bumping this thread. I for one would like a clearer example of defining custom unit systems with nonstandard base units such as mm or ms to avoid the use of floating point numbers.
Thanks in advance
A link to examples in the top level folder would be very helpful, as would additional explanation of what the macros actually do.