Spin off thermal_gyroradius from gyroradius?

[namurphy]

Our gyroradius function is quite long and complex. The complex control flow can often lead to missed situations in tests. When a function is too long and complex, it's usually an indication that the function is doing too much, and that the function should be split up into multiple short functions that do exactly one thing.

The calculation of the gyroradius needs the perpendicular velocity, which can currently be given by providing the velocity itself, the Lorentz factor, or the temperature. A lot of the complexity arises because of validating inputs (like making sure that only one of the above is provided).

One way to reduce this complexity would be to create a separate function only for the thermal_gyroradius. I'm thinking that spelling out "thermal gyroradius" will make resulting code less ambiguous.

We could perhaps also add a keyword argument to thermal_gyroradius to specify whether it should be the "most probable", "rms", or other thermal velocity.

Before we implement this, it'd be helpful to get some feedback from a few people. Is this a worthwhile idea?

[jwreep]

Would this issue be more easily solved with function overloading? In C++, at least, the trivial solution would be to have three functions with different inputs.

I haven't used it before, but from what I understand, overloading was added to Python > 3.8, so something like:

@overload
def gyroradius( lorentzfactor: u.dimensionless_unscaled ):
    ...
@overload
def gyroradius( T: u.K ):
    ...
def gyroradius( Vperp: u.cm/u.s ):
    ...

[namurphy]

Interesting! It looks like the @overload operator is intended for static type checking, so we'd have to implement the overloading mechanics ourselves, which would be a lot less trivial than in C++ or Julia.

With that said, we recently started doing static type checking in PlasmaPy, and I think there are a few places where @overload would be quite helpful. Thank you for bringing this up!