adding units of measure to the type system for numerical types

[massivefermion]

I just found out that F# has this very cool feature where numeric types can have a unit attached to them, so you can say that a integer distance variable is equal to 2 meters which has a different type from another integer distance variable equal to 2 inches.
There are no predefined units in the language, but F# has defined the SI units in its standard library but anything that is not there has to be defined by the developer.
The cool thing is, you can combine these units using arithmetic operators which empowers the compiler to catch some bugs that are usually very elusive.
I understand that some people may think this is an unnecessary feature given the amount of effort needed to implement it in the type system but the main reason this may seem unnecessary to some people is because no other language has this feature and people are just used to not having it. But I think if we have it in gleam and actually use it properly, this can help enormously in a lot of areas.
happy to hear your thoughts!

[lpil]

This is a really cool feature of F#. It'd be grand to explore what this might look like in Gleam. Could we start writing out a design?

[lpil]

Great stuff!

I think we may need to think of a new syntax for the combination of a unit and Int or Float as it looks too much like a type parameter currently.

How does this work with int <-> float conversions? Is the unit information preserved by functions like float.round?

[massivefermion]

I suppose changing the delimiters from [ and ] wouldn't help. So maybe we can do something like Float\newton. The drawback is that without having left and right delimiters, we can't allow "unit expressions" coupled with types. So any unit defined in terms of other units should be defined beforehand. So this:

fn calculate_pressure(force: Float[newton], area: Float[meter^2]) -> Float[newton / meter^2] {
  todo
}

would change to:

pub unit meter_squared = meter^2
pub unit pascal = newton / meter_squared
fn calculate_pressure(force: Float\newton, area: Float\meter_squared]) -> Float\pascal {
  todo
}

And yes, in the case of conversions, the unit should be preserved. But I suppose we may add a module to the stdlib with some functions that do unit-related things like adding or removing units to and from numbers.

[lpil]

In which case we'll need to design a system of parametric polymorphism for units so that these functions can generically operate on numbers while preserving the unit, much like functions with type variables.

It may make more sense to use capitalised unit names to distinguish them from unit variables, like with types.

I wonder what other syntaxes we could use.

• unit(Float, Mile)
• Float unit(Mile)
  Or something else?

[massivefermion]

yeah, polymorphism over units seems like the right idea. But I'm worried about allowing generic types and functions over units. The developer may easily shoot themselves in the foot while at the same time believing this feature is protecting them! Of course this can be avoided by grouping related units together and somehow making sure that in a generic context, the developer is handling all the related units. Something like:

pub unit Hour
pub unit group DistanceUnit {
  Kilometer
  Mile
}

pub fn calculate_speed(distance: Float\unit[DistanceUnit], time: Float\unit[Hour]) -> Float\unit[DistanceUnit/Hour]{
  todo
}

In the above definitions, the developer should be able to use Kilometer and Mile separately too.
I also suggested a new syntax in the above function definition. I don't like unit(Float, Mile) or Float unit(Mile) because using parentheses makes it too much like a function call and also having a space between the type and the unit seems somehow wrong to me because anytime I see whitespace after something, I instinctively think that part is done!

EDIT: The above example doesn't show a problematic situation because everything will be fine if the developer just does the calculation and doesn't care about the units. I can't think of an example now but a situation may occur where the calculations depend on the unit of a particular number and that would be problematic in a generic context if the developer doesn't handle all the defined units. One good example is temperature. The conversion between Celsius and Fahrenheit involves addition and subtraction so a conversion between them changes any formula involving temperature.

[lpil]

I don't think we would add subtyping (sub-uniting?), either the user would have to use miles or kilometers in their program.

To expand on what I mean by generically operating on units, I mean the user should be able to define this function:

pub fn add(a, b) {
  a + b
}

And then be able to use it without losing unit information. So add(int_miles_1, int_miles_2) would return integer miles.

This would work by parametric polymorphism, but we need a syntax. i.e.

pub fn add(a: Int of u, b: Int of u) -> Int of u {
   a + b
}

I instinctively think that part is done!

I don't think any of the unit proposals here are a good fit for Gleam, we'll need to keep searching and proposing options here.

[massivefermion]

I was just reminded of this and thought about it a little. It's clear that just going back and forth between different delimiters is not helpful. We need to totally change our perspective.
What if units are themselves actually types that are defined over numeric types:

pub unit Meter over Int
pub unit Foot over Int
pub unit Second over Int
pub unit MeterPerSecond = Meter / Second

let distance_in_meter: Meter = 8
let distance_in_feet: Foot = 4
let time: Second = 5

let speed_in_meters_per_second = distance_in_meter / time // type -> Meter / Second
let new_speed = 10 as MeterPerSecond + speed_in_meters_per_second
let invalid_speed = speed_in_meters_per_second + distance_in_feet / time // compile error!

Now we can have:

pub fn calculate_speed(distance: Meter, time: Second) -> Meter/Second {
  a/b
}

and

pub fn calculate_speed(distance: a, time: b) -> a/b {
  a/b
}

It's also clear that because the return type is using an arithmetic operator, a and b can only be units and cannot be simple numeric types.
And, of course, if you want to work with Float instead of Int, you need to define a separate unit unit PreciseMeter over Float.
The only problem is, I don't immediately see a way to preserve the units when converting between Int and Float. Maybe an explicit cast?

[lpil]

This design seems a lot more complex and would require some sort of type class like system to constraint the type variables to types which a/b makes sense for.

What would you say the advantage is to making units types rather than a property of the numerical types?

[massivefermion]

Honestly, I was just looking for an alternative design, not any particular benefit comes to mind.

[lpil]

Always a good idea! 👍

[massivefermion]

ok, I'm just summarizing what options we have, in order of my preference:

1. Float\Kg: This seems fine but I think it should not allow for unit arithmetic because it's not enclosing the unit and Float\Meter/Second looks wrong! So if you want to use composite units, you'll have to pre-define them, which does not seem to be that big of a deal, it may even be an advantage because having unit arithmetic all over the place wouldn't be pretty, enforcing pre-defined units makes things cleaner. Overall I think this is the best design we have here.
2. Float of Kg: Seems fine!
3. Float unit(Kg): I can't really point out a specific issue but Float\Kg just feels better.
4. unit(Float, Kg): This could allow for unit arithmetic but not sure if that's a benefit anymore. It also seems to be too much of a departure from regular type annotations. I'm also not sure about having the unit in there. But again (Float, Kg) could easily be confused with a tuple type, so no! Not a fan!

As for unit definitions and usage:

pub unit Meter
pub unit Second
pub unit Foot
pub unit SpeedUnitWithSecond(d) = d / Second
pub unit AccelerationUnitWithSecond(d) = d / { Second ^ 2 }
pub unit UnitConverter(a, b) = b / a

const jump_height = 4.2 [Meter]
const minimum_speed = 16 [SpeedUnitWithSecond(Meter)]
const acceleration = 4 [AccelerationUnitWithSecond(Meter)]

pub fn calculate_speed(distance: Float\d, time: Float\Second) -> Float\SpeedUnitWithSecond(d) {
  distance/time
}

pub fn meters_to_feet(m: Float\Meter) -> Float\Foot {
  m *. 3.28 [UnitConverter(Meter, Foot)]
}

Did I miss anything?

[Ulberg]

Just out of curiosity, has there been any updates or decisions made in regards to unit of measure?

It is actually one of the features that made me like F# when one of our newcomers wanted us to try FP in production. It is such a easy sell, especially if you work with science or analysis-like workloads.

[Ulberg]

That is a fair assessment. For our sake it has stopped us from making faulty unit conversions several times. We work in the energy sector, and are considering using Gleam for some data collection on our IoT devices. For our kind of work it is actually valuable, we work with so many units all the time, that having some of the responsibility moved into the typesystem is less error prone.

We actually have moved to have units as suffix on all APIs responses, because it is so important to not get it wrong, i.e. total_production_kwh, total_installed_capacity_kwp...etc

I never knew i wanted units of measure before we started using it, I do not know if our experience is analogous to other people, but now that i have it, it seems unsafe and unnecessarily hard/risky to not have it.

Also : Always very impressed with your reply times ✨ Makes it more thankful to ask questions and share thoughts

[lpil]

Given your experience and good use case I'd be very interested in your feedback on the libraries we have presently, if you ever find the opportunity to use them in a real project. It'll be helpful to work out if this is an area where further work will be worthwhile.

[Ulberg]

I'll for sure test them, and I can make the commitment to follow up here afterwards with my thoughts after using it 😊

[massivefermion]

I'm really excited to see actual demand for this feature. I think this is such a cool feature and it's unfortunate that till now only one language(that I know of) has this feature. @Ulberg I'd be interested to go into more detail about your use-cases and the specific situations you've been using it for because concrete examples are the best thing for designing an API.

[Ulberg]

Hey @massivefermion,

For sure, let's look into that next week ^^

I'd like to test the current community solutions to get a bit of a feeling for the designs they have made, are you perchance familiar with any of them. I was able to find gleameter, if there are any others I'd like to test them