Add Number Density

[trb5016]

• Add Particles unit to AmountOfSubstance
• Add NumberDensity quantity (based on "Particles per Volume", but labelled as "Number per Volume" to better fit the unit.

Note: the existing AmountOfSubstance quantity had a custom method to calculate the number of particles from that quantity. However, my use case requires actually having the number of particles as a 'unit'. (Did not remove the existing method because that would probably be a breaking change for someone. It doesn't hurt anything, it's just some redundancy)

This in turn supports the NumberDensity quantity.

Both AmountOfSubstance and NumberDensity are a little different than other units because they are generalized and don't refer to a specific 'thing'.

E.g., you can have a "mole" of any 'thing', and you in turn have the density of that 'thing'. While the vast majority of the time the 'thing' is referring to particles, even the 'particles' could more specifically be referring to atoms, neutrons, etc.

If this approach is acceptable, I will likely eventually add in the conversion functions to jump between AmountOfSubstance/NumberDensity/Volume.

[codecov-commenter]

Codecov Report

Merging #814 into master will decrease coverage by 0.14%.
The diff coverage is 73.98%.

@@            Coverage Diff             @@
##           master     #814      +/-   ##
==========================================
- Coverage   80.53%   80.39%   -0.15%     
==========================================
  Files         281      287       +6     
  Lines       41895    42828     +933     
==========================================
+ Hits        33740    34430     +690     
- Misses       8155     8398     +243     

Impacted Files	Coverage Δ
UnitsNet/GeneratedCode/UnitAbbreviationsCache.g.cs	100.00% <ø> (ø)
.../GeneratedCode/Quantities/LinearNumberDensity.g.cs	72.22% <72.22%> (ø)
...et/GeneratedCode/Quantities/AreaNumberDensity.g.cs	72.88% <72.88%> (ø)
...itsNet/GeneratedCode/Quantities/NumberDensity.g.cs	72.88% <72.88%> (ø)
UnitsNet/GeneratedCode/Quantity.g.cs	81.41% <80.00%> (-0.05%)	⬇️
...ratedCode/NumberToAmountOfSubstanceExtensions.g.cs	100.00% <100.00%> (ø)
...ratedCode/NumberToAreaNumberDensityExtensions.g.cs	100.00% <100.00%> (ø)
...tedCode/NumberToLinearNumberDensityExtensions.g.cs	100.00% <100.00%> (ø)
...GeneratedCode/NumberToNumberDensityExtensions.g.cs	100.00% <100.00%> (ø)
...t/CustomCode/Quantities/AmountOfSubstance.extra.cs	70.00% <100.00%> (ø)
... and 8 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 28de3b5...1c600a6. Read the comment docs.

[lipchev]

Have you considered the Molarity (aka "Molar Concentration")? I have already implemented the operators for volume/mass & the other concentration types.
I see how the number density is a more abstract concept- but as such- it would (in the long run) require adding tons of "countable" units like cells & galaxies. There were some discussions about the countable stuff (I remember reading about the "Megadeath" unit in a post somewhere). I was hoping to not have to revive that topic just yet (if we can avoid it) as it requires some serious design decisions (imaho).

[trb5016]

I just pushed an update to add another NumberDensity unit I had missed (NumberPerBarnCentimeter) before seeing your comment.

But anyways:

The concept of Number Density is very close to molarity as they almost effectively the same quantity, but I would argue they are distinct. I did consider just adding the new 'particles' unit (from AmountOfSubstance) and making new Molarity units with particles in the numerator instead of moles.

However, that felt wrong to me. Molarity is, by definition and name, the number of moles per volume. The wikipedia page for Molar concentration points to the related quantity of "Number Concentration" that links to the "Number Density" page. So I don't think it's appropriate to treat molarity and number density as the same quantities.

A while back I also read some of the discussions on 'countable' units, and was also at a loss to a good solution. In fact, the project I was working on a few years ago I just made my own local fork and implemented NumberDensity as atoms/cm3 and called it a day.

I'm now working on a new project and want to actually use the main library and resolve this. I think defining "NumberDensity" as "NumberOf..." is a good fix. It may not be ideal, because yes, it would be better to be more specific and say e.g., atoms/cm3, neutrons/cm3, megadeath/cm3, but I don't think that's ever really going to be possible without a massive overhaul as you note.

I come from a Nuclear background and while what we typically work with are atoms/volume, it's generally synonymously referred to as just the "Number Density" (instead of Atom Density). So I figured that would be an acceptable approach to others as general usage for their application. You'll lost the specificity of what you're working with, but at least you can get by.

Additionally, I think Molarity suffers from the same generality problems that Number Density has, but it's more obscured because of the simple phrasing in that 'mole' sounds like something, whereas 'number of' sounds generic. E.g. a 'mole' of something has no meaning, it's just the number of something divided by avagardo's number. Though Molarity is definietly a more common unit and obviously is basically always used for its chemistry solution purpose.

In summary, I think NumberDensity does need to be distinct from molarity. I don't really like how it feels awkward, but I don't see an alternative.

I was thinking of just doing "AtomDensity", but that skirts the issue because of how you pointed out we would then needs tons of specific units.

P.S. there is the argument that the "Number of" something should be a distinct quantity from the "AmountOfSubstance" quantity, but 1) that opens up the whole "countable" units issue even more, and 2) I don't what you would call that because while the "AmountOfSubstance" is technically defined as the "Number of particles" divided by avagadro's number, it seems superfluous to just have the "Number Of" as its own unit when it's a constant conversion between number of and amount of substance.

I don't know. It's a tricky one to deal with.

[angularsen]

I have no strong opinion here, not being very familiar with either of the unit domains discussed.

A few observations:

• We have Ratio quantity for numeric counts like ratio, fraction, percent, parts per million etc. Would it be possible to shoehorn what you need into that quantity?
• If not, adding XXXDensity would be consistent with a range of existing quantities, like Density, AreaDensity and LinearDensity for 3d, 2d and 1d mass density. There is also LinearPowerDensity and PowerDensity.
  Also, there is a wiki for Number Density so at least the concept seems widely established.

[lipchev]

Indeed, not only does the number density have an "unspecified" nominator- it also doesn't provide any meta-information about the denominator- that is we cannot multiply a NumberDensity by an Area and expect to obtain a "number" (e.g. people).
It would seem therefore reasonable (at least to me) to have different (at least two) dimension-specific densities - e.g. AreaNumberDensity & VolumeNumberDensity - as such we could define division operators for Double and (Area | Volume) -> (Area | Volume)Density and vice-versa for the multiplication. Naturally- AreaNumberDensity * Length -> VolumeNumberDensity.
Additionally one could argue that there exists a number of possible implicit / explicit conversions- such as with the Molarity (basically any unit that has an "L": -2 or "L": -3 should be suitable).

Having settled the denominator- there is still the question of the actual units that go into these densities- do we allow anything other then NumberXXX? Although technically possible (conversions/operators current specify the destination unit)- I'd say not unless/until we switch from struct to class (having some sort of baked in unit-inheritance): as the conversion from AreaNumberDensity.PeoplePerSquareMeter to AreaNumberDensity.DotsPerInch makes no sense.

Finally, may I express my astonishment of the fact that you people are doing particle physics using units that are

Named after the broad side of a barn

[trb5016]

@angularsen Unfortunately, the ratio doesn't really work. I mean, I could make it work, but it wouldn't be conceptually correct. Just as an example we will frequently need to multiply ratios by NumberDensity to get some fraction of atoms of a certain element, so it kind of doesn't make sense if they were both ratios. Also, we frequently multiply Number Density by a particle flux to get a reaction rate (that's a whole other quantity that I will probably need to implement at some point too). But to your second observation, this is very analogous to LinearPowerDensity and PowerDensity, it just gets weird because there's no 'numerator' per se.

@lipchev I agree with you about the handling of the denominator, the use of "AreaNumberDensity" (/m2) and "LinearNumberDensity" (/m) do exist, they're just not as common. I think the 3D form "VolumeNumberDensity" could be left as "NumberDensity" since that does have a defined meaning in usage as referring to 3D space, but I'm not opposed to VolumeNumberDensity either.

As far as the conversions I agree with everything you stated (though I think the one example would be AreaNumberDensity*(1/Length) -> VolumeNumberDensity. Basically any length, area, or volume multiplied by a Linear, Area, or [Volume] Number Density should yield the appropriately dimensioned NumberDensity, or an AmountOfSubstance if the denominator is cancelled.

To the point on the numerator. I think the only 'fully correct' way of handling this is exactly as you state. There has to be some extra property that tracks what thing someone is working with. This would be applicable to several different quantities: NumberDensity (in each 1D, 2D, and 3D form), and AmountOfSubstance. It could also potentially extend to some other quantities, possibly Ratio?

Even looking at the Wikipedia page for Amount Of Substance it states

To avoid ambiguity, the nature of the particles should be specified in any measurement of the amount of substance: thus, 1 mol of molecules of oxygen (O2)

So really whenever we talk about a NumberDensity, Amount of Substance, or even a lot of times with Ratios you are specifying the 'thing', and the current way is to just basically make sure you're doing the arithmetic correct in your code and there's no check making sure you're not e.g. adding 5 moles of Carbon to 5 moles of Oxygen. (Which is perfectly manageable to do)

But with the 'what thing' in the numerator concept you could have e.g.:

• 1E10 atoms C-14/m3
• 4 mols Boron
• 100 ppm of Chlorine

Note: all this ratio talk isn't applicable 100% of the time (ha), because sometimes a ratio does truly have no 'thing' tied to it (I think)

So to sum that up, I'd say either we make that big change where some quantities have an extra property extending 'what' the unit is, or yes, limit it so there's only ever an esoteric, undefined 'number' associated with it. (That change could introduce some cool extra features. Like, throwing exceptions if you try and add moles of O2 to moles of C. Or multiplying the number density of C-12 by a ratio of U-235. But that would be lots of work to implement.

So I guess if you guys agree with the concepts, I can add in the conversion functions and the 1D and 2D versions of Number Density to this PR as an inelegant workaround of the 'fully defined' solution.

If you feel like it's too clunky to implement, I get it, and I can just work around it in my projects by doing the conversions in math outside of Units.Net.

Then maybe someday when I have much more time I could take a look at the 'fully defined' approach as a major change.

Bonus fun facts on the "Barn" unit. It came about from the expression "Can't hit the broad side of the barn" indicating poor aim when shooting at a target. The Barn unit is used to represent the cross-sectional area of a particle when you're "shooting" other particles at it to see if they 'hit', and it honestly helped me understand the concept when I was learning it haha.

Double bonus fun-facts: There are also real units called the "Outhouse" and "Shed" (10E−34 m2 and 10E−52 m2, respectively), though nobody actually uses those, and they surely just came from physicists weird sense of humor.

[angularsen]

So to recap, is this what you are proposing to add?

• 3 new quantities: LinearNumberDensity, AreaNumberDensity and NumberDensity (or VolumeNumberDensity)
• Conversions between these and AmountOfSubstance by multiplying/dividing by Length, Area and Volume

And for now we don't add:

• extra property extending 'what' the unit is

If so, it looks good to me if it is something that will be useful for you.

[trb5016]

Correct @angularsen. I wasn't originally planning on the full scope because I only need NumberDensity at the moment. However, I think it's probably best to just do it all at once (and me not be lazy) so it stays consistent.

Within the next few weeks I'll update this PR with the code changes.

Thank you both for talking through this.

[angularsen]

Great, look forward to it 👍

[trb5016]

That last update is not the full PR, still going to add the conversion functions, but inadvertently pushed the branch

[trb5016]

Alright, this isn't going to work this way. When adding the conversion operators I couldn't add one for converting too number density because, as @lipchev pointed out, it's the 'same' as Molarity.

I have some grandiose ideas for how this could work, but I don't know when I'd be able to work on that. Some day hopefully I'll open an issue specifically to address those ideas.

I'll just close PR out. Apologies for the waste of time, but I appreciated the discussion.

Thanks.

[angularsen]

No problem, thanks for letting us know 👍