Agree, document, and enforce a `bluemira` unit convention

[CoronelBuendia]

Description of issue / requirement to address

We are not fully consistent in units across bluemira. We've had some discussion regarding unit conventions, but we need to actually agree, document, and enforce a unit convention.

We've already resolved the topic of degrees vs radians: degrees as inputs and outputs to user-facing functionality

We also need to agree on units, e.g. SI or whatever, but sadly there are some pretty weird ones in the plasma physics and neutronics worlds. So plasma densities in 10^19/m^2 or neutron fluxes in n/cm^2/s. I don't condone such units... but we do need to strike a balance between consistency and usability.

Proposed solution

• Discuss and agree a unit convention.
• Document it and add it to the documentation somewhere
• Enforce it in the externally-facing functionality of the code

The latter will probably need to happen progressively...

Alternative solutions

Live with unit quirks forever.

Proposed Unit Convention

SI unit convention, (C or K), degrees not radians, no mega-milli-kilo-centi-pico stuff, except for kilogram..

• time: seconds [s]
• distance: metres [m]
• mass: kilograms [kg]
• current: Ampères [A]
• temperature: AHHH!
• amounts: moles [mol]
• angles: degrees [°]

We'll probably encounter some weird ones.

[je-cook]

A time to consider some use of Pint?

[CoronelBuendia]

A time to consider some use of Pint?

Everywhere? Or just in the user interface?

I fear passing that metadata around everywhere will break as soon as you hit a numba-accelerated block

[je-cook]

Just for conversion from the user interface to our units (whatever they may be) then just use the raw numbers, say in the setup of a parameter.

If we want to be really fancy we could do a conversion back to the users units at the end, but thats probably a nicety that is cared less about

[CoronelBuendia]

Yeah I'd be happy with that. Just going through their docs and there's also a fair amount of computational overhead, so avoid that in the main body of code would be good.

We still need to make sure about all our units internally though... cough [MA] cough [A]. That will probably be the hard part.

[CoronelBuendia]

Just an additional thought, this kind of feeds into the data/interfacing task. For example, in PROCESS, I'm pretty sure there are something like plasma density that will come out in plasma physicist units.

[CoronelBuendia]

Thoughts @fabrizio-franza @ivanmaione @jmorris-uk ?

[je-cook]

yep, we can maybe do the same sort of conversion, if we know the units going between the codes. Semi treating it like another user

[DanShort12]

This would be great at our interfacing levels - our Parameters are already unit-aware, so if we use those at the interfacing level (or at least use their json equivalents) then it could be fairly straightforward to convert when reading in external data. We should definitely keep that conversion only at the interfacing level, and just be consistent about our internal units once something has landed in bluemira.

[DanShort12]

Perhaps we could add a unit to the ParameterMapping class - that way if we know the external source and how they treat the units then we (or better yet, the users) have a single point of record for the inbound unit and then can see what conversion will take place.

[fabrizio-franza]

Thoughts @fabrizio-franza @ivanmaione @jmorris-uk ?

Here is how I coped with this problem in MIRA. Anywhere in the core classes (solvers, geometry builder, etc.), the SI units are used, meaning that any class properties or input parameters to each method are implicitly meant to feature and operate with SI units. However, there are few exceptions to evaluate case by case, such as:

• plasma density [1E19/m^3] or also [1E20/m^3]. On that, I believe it's all about making a choice based on practical convenience, and that will apply to all plasma physics-related modules, such as SOL physics or particle heat fluxes calculation. So the normal "Praxis" would suggest using [1E19/m^3], I guess. Another option would be to assume pure atomic concentrations, i.e. particles/m^3 or mol/m^3. That would fulfil the SI criterion and be more coherent.
• plasma ion and electron temperature [keV]. Again, here is another purely plasma-physics related unit, meaning that one will handle these variables only in certain plasma physics solvers. However, I assume we will rely on external MHD solvers, meaning that these will eventually dictate the units of the parameters they take as inputs (e.g. PLASMOD reads the temperature at the plasma separatrix in keV). It would be rather tedious to continuously convert a plasma temperature from K to keV and from keV to K, also because plasma temperatures in K would yield non-comprehensive scales. So, in this case, I would simply make a choice based on the application (and the much larger convenience of using keV rather than using K). Actually, it all comes down to the kinetic energy of plasma particles than purely temperature-related values.
• neutron flux density [n/cm^2/s] or [n/m^2/s]. In MIRA I decided to be consistent with the full SI unit rules, i.e. using n/m^2/s. The radiation transport codes operate with cm for the XS and with n/cm^2/s for the flux densities. And that is something to keep in mind when doing I/O parsing operations to and from these codes (I assume that holds for OpenMC. too). This is a problem that we encounter when running external solvers within bluemira, and that is also the case for the physics unit listed above when running PLASMOD.

Finally, from the user side, I use ad-hoc methods or multiplications constants, to perform units conversion. But that occurs from the user-interface (or main) script, i.e. the one that runs the full configurations.