Units#

Within POLARIS there are many quantities that are represented within the various models, each of which has a variety of representations that it could take. The distance between two points could be 2 miles or equivalently 3.2 kilometers.

There are occasions where our code won’t really care about what units a quantity is expressed in. For example if we are calculating the free-flow speed of a road segment as a fraction of its posted speed - we might say somehting like:

auto freeflow_speed = 0.95 * link->posted_speed();

We care that the units are preserved, but we don’t care what they actually are.

There are many other occasions where we absolutely need to care about the units being used. For example if we define a cost function for a choice model that uses distance as a component, it will be very important if that cost function evaluates using the distance in miles or the distance in kilometers.

To keep track of the various unit types and the conversion between them, we utilise the units library.

The general rule of thumb for using units is to keep our quantity in a compatible unit type for as long as possible and only convert back to a float/double when we are performing model calculations that are no longer representable as any unit type. For example:

// All of these operations are performed using unit types (_t)
meter_per_second_t link_speed = link->congested_speed();
kilometer_t        link_length = link->length();
second_t           travel_time = link_length / link_speed;

// when we convert back to a dummy variable (bool) we compare against another unit type (20 minutes)
bool dummy_is_long_travel_time = travel_time > 20_mins;

// If we were going to put this into a utility function, we would **only** then convert to a primitive (float) type
// as utility is no longer a physical quantity
float utility = _beta_tt * travel_time.to<float> + _beta_x * person->owns_an_ev();

Examples of expected behaviours for the units library are demonstrated in the tests/core_tests/Units_Tests.h test file.