feat: added value_in method to SIObject

[dhfwc18]

Hi all,

I am an Energy Economist working for a public sector consultancy. Stumble on this library and think this is really useful to a lot of the build physics modelling we are currently doing in the industry, especially with the overhead improvement compare to unyt or pint. My only concern is that the library is very technical and may be a little bit more challenging to use for less technically inclined researcher outside of the physics/engineering discipline. Regardless, really grateful for all the hard work here is one of my suggestion to make the library slightly more readable for the less technical inclined normies like us XD.

feat: added value_in method to SIObject

Allows for better readability compare to single division back to dimensionless quantity.

Example:

• obj / METER <- unclear if it is per meter or dimensionless
• obj.value_in(METER) <- clear dimensionless numeric

Also fixed some formatting/trailing white spaces stuff that my linter picks up.

Many Thanks,
David

[prehner]

Hi David, thank you for this suggestion. I think that is a valuable addition, because it is not just a replacement of the operator overloading, but also checks the unit at that point, so it might help debugging in some cases.

@g-bauer what do you think? And what would be the best name?

distance_to_moon.value_in(METER)
distance_to_moon.in(METER) # is that even allowed? Probably not
distance_to_moon.convert_into(METER) # what we have in Rust, but the into is also a bit Rust specific and it's rather long.

[g-bauer]

Looks good to me. We have value so I think value_in is consistent and value_in(si.METER) is nice to read.

@dhfwc18 Thanks for the contribution and the feedback. Much appreciated. I was wondering - did you benchmark this package against unyt or pint? We never really looked into performance aspects.
Regarding the PR, could you please add your method to the docs? Adding a line with the method name in this file should be enough.

[dhfwc18]

Hi @g-bauer added the docs as you suggested.

I haven't done quite as much benchmarking re this package as I would wished to but I don't think that would even be necessary to see the appeal of what you are working here -- unless you really want to put a number down for the claim. Just by not wrapping the numeric data, your package is already doing wonders for me. It is so much easier to understand and also it is the only system that has both Python and Rust support.

I will give an example of how this is helping me:

I lead my company's research that is designed around an open-source build physics model. We use the model to help households, tech developer/manufacturer and local governments understand how new low carbon technology can help improve household energy use. I find the model so interesting that I decided to contribute some of my ideas in my free time.

One of my (more ambitious) idea is to replace how they currently track unit (fixed ad-hoc reference in docstrings) with more consistent Python/Rust native options, but there is a problem -- the model is designed and proto-typed in Python and implemented in Rust (iteratively, ongoing).

To implement the design I suggested in the Rust library, say with a custom uom extension that I built, the model would need to break with its upstream Python design. On the other hand, if I use unyt or pint to help out the Python design, not only am I adding insane overhead -- because the model's calculations (literally 90% of the functions) are designed to run in a 17520 steps half-hourly simulation loop -- it is likewise lacking a good Rust equivalent where I can implement with ease using the same design philosophy.

This library literally will help bridge that upstream/downstream problem, making it easier to build more newcomer friendly Python prototype that can be easily ported to a more preformative Rust based design.

What you guys have here is literally what I have been looking for for quite a while XD. Really appreciate all the hard work!

[g-bauer]

Thanks! Sounds similar to what we do. In Rust we get compile-time, zero-overhead units and this package is the bridge to Python. If you find more features are missing, let us know!