Add RadiantExposure to SI

[nicodemus26]

Adds the unit for radiant exposure, the integral radiant flux over some period of time.

Some examples:
http://glossary.ametsoc.org/wiki/Radiant_exposure
https://omlc.org/classroom/ece532/class1/irradiance.html
https://en.wikipedia.org/wiki/Radiant_exposure

[adamreichold]

Isn't this basically an energy area density? I mean there is nothing specific to radiation defined here in contrast to e.g. spectral exposure defined as energy per area and frequency. Maybe we should rename this to EnergyAreaDensity so it can be used in more generic contexts?

[nicodemus26]

That seems like a reasonable direction, though I'm not sure AreaDensity is the right suffix to capture this (and I've not seen it in the literature I've looked at). This is -3->-2 time exponent versus HeatFluxDensity aka EnergyFluxDensity (both kg⋅s−3).

Parallel names for the same quantities seems to be a recurring problem. Perhaps there's value in figuring out some appropriate way to alias these versus trying to find some cross-discipline canononical name. Perhaps a QuantityAlias trait that allows seamless, zero-cost transitive interaction to the alias target?

[adamreichold]

That seems like a reasonable direction, though I'm not sure AreaDensity is the right suffix to capture this (and I've not seen it in the literature I've looked at).

I am admittedly not sure this is a good name either. I came there from the German term "Flächendichte" which seems to translate to either area density or areal density to differentiate from a generic density which is usually w.r.t. volume. But then again HeatFluxDensity is per area as well whereas MassDensity is per volume...

Perhaps a QuantityAlias trait that allows seamless, zero-cost transitive interaction to the alias target?

Maybe plain Rust type aliases could work, e.g.

pub type RadiantExposure = EnergyAreaDensity;

? But we would have to rename both the quantity and its units, so I guess we would end up with a macro that creates the module aliases.

[nicodemus26]

I came there from the German term "Flächendichte" which seems to translate to either area density or areal density to differentiate from a generic density which is usually w.r.t. volume.

I definitely hear where you are coming from with the proposal. Maybe there is a canonical name more generic than radiometry available? Does the ISQ publish derived unit names? Would NIST or other standards bodies be good fallbacks?

But then again HeatFluxDensity is per area as well whereas MassDensity is per volume...

My guess is that Flux implies a surface, escaping the L^-3 implication that comes with Density.

Maybe plain Rust type aliases could work

Unfortunately this abandons all of the trait impls of the target type, along with accessors for unit and tuple types. This is done this way to allow type aliasing in dependent crates while preserving coherence.

https://doc.rust-lang.org/reference/items/type-aliases.html

A lot of the value that comes from this crate is the algebraic type relations including to anonymous Quantities. I think any named Quantity aliasing should take care to preserve and extend this paradigm.

[iliekturtles]

Thanks for the PR! Work has been busy the last couple days so I haven't gotten a chance to review or catch up on the conversation. Just wanted to let you know I'll get back to this ASAP.

[iliekturtles]

I did quick review of the code, which looks really good (one question in the diff). I still need to do a detailed review to make sure all the units have no typos.

In regards to the quantity name the desire is to use the canonical name for the derived units. If there are multiple quantities that have the same derived units (Temperature/TemperatureInterval, Ratio/Angle, ...) use Kinds to differentiate them. Looking in NIST 811 I see J/m^2 conversion factors listed under "density of heat." Wikipedia only lists "radiant exposure" under J/m^2, but I note that it includes "heat flux density" and "irradiance" under W/m^2.

In the limited time I've spent so far it seems "radiant exposure" is used for energy contexts while "heat density" is used for heat contexts. uom only has an Energy quantity right now. Should the ability to do type aliases be added so Energy/Heat quantities can be interchangeable (I still need to read @nicodemus26's link)? Should Heat quantities have an explicit Kind?

[iliekturtles]

Shouldn't this be applied to joule_per_square_meter?

[adamreichold]

Should Heat quantities have an explicit Kind?

Considering a units of measurement library is often used primarily to avoid messing up quantities of different type/kind/dimension, I guess a distinct kind for quantities with the same dimension but coming from different applications (ratio/angle, energy/heat) is a good design point. Especially since forcing a heat quantity into an energy quantity will only need one more .into() call.

[nicodemus26]

Should Heat quantities have an explicit Kind?

FWIW I am using HeatFluxDensity to simulate energy transfer across a surface. I don't think they should be a different kind, but Temperature and TemperatureInterval are certainly correctly differently-kinded in the same simulations. It's plausible to have an EnergyInterval ~== Heat, but I don't think its as necessary as negative Energy is valid whereas negative Temperature is not (as distinct from the valid negative TemperatureInterval)

Shouldn't this be applied to joule_per_square_meter?

Yep!

[iliekturtles]

Based on the reading I have done so far I'm inclined to merge J/m^2 as "radiant exposure" and punt on the decision to use distinct kinds or not:

1. This seems to be the more common name for energy vs. using "heat density" which is more applicable to heat contexts.
2. If support is added non aliased quantities no changes would need to be made.
3. If "heat density" is added with a distinct Kind no changes would need to be made.
4. If we find that "heat density" really is more common uom is still pre-1.0 so I'm not as concerned about a breaking change.

@nicodemus26 @adamreichold Objections?

---

Could make one more change to trim some trailing white-space. See the diff below.

diff --git a/src/si/radiant_exposure.rs b/src/si/radiant_exposure.rs
index 597fb4a..c8b272c 100644
--- a/src/si/radiant_exposure.rs
+++ b/src/si/radiant_exposure.rs
@@ -57,7 +57,7 @@ quantity! {
             "zeptojoule per square meter", "zeptojoules per square meter";
         @yoctojoule_per_square_meter: prefix!(yocto); "yJ/m²",
             "yoctojoule per square meter", "yoctojoules per square meter";
-        
+
         // square centimeter denominator
         @gigajoule_per_square_centimeter: 1.0E13; "GJ/cm²",
             "gigajoule per square centimeter", "gigajoules per square centimeter";
@@ -81,7 +81,7 @@ quantity! {
             "microjoule per square centimeter", "microjoules per square centimeter";
         @nanojoule_per_square_centimeter: 1.0E-5; "nJ/cm²",
             "nanojoule per square centimeter", "nanojoules per square centimeter";
-        
+
         // square millimeter denominator
         @gigajoule_per_square_millimeter: 1.0E15; "GJ/mm²",
             "gigajoule per square millimeter", "gigajoules per square millimeter";
@@ -150,7 +150,7 @@ mod test {
             test::<e::attojoule, a::square_meter, re::attojoule_per_square_meter>();
             test::<e::zeptojoule, a::square_meter, re::zeptojoule_per_square_meter>();
             test::<e::yoctojoule, a::square_meter, re::yoctojoule_per_square_meter>();
-            
+
             test::<e::gigajoule, a::square_centimeter, re::gigajoule_per_square_centimeter>();
             test::<e::megajoule, a::square_centimeter, re::megajoule_per_square_centimeter>();
             test::<e::kilojoule, a::square_centimeter, re::kilojoule_per_square_centimeter>();
@@ -162,7 +162,7 @@ mod test {
             test::<e::millijoule, a::square_centimeter, re::millijoule_per_square_centimeter>();
             test::<e::microjoule, a::square_centimeter, re::microjoule_per_square_centimeter>();
             test::<e::nanojoule, a::square_centimeter, re::nanojoule_per_square_centimeter>();
-            
+
             test::<e::gigajoule, a::square_millimeter, re::gigajoule_per_square_millimeter>();
             test::<e::megajoule, a::square_millimeter, re::megajoule_per_square_millimeter>();
             test::<e::kilojoule, a::square_millimeter, re::kilojoule_per_square_millimeter>();

[iliekturtles]

Merged, thanks!