angular_freq_to_hz

plasmapy.utils.decorators.converter.angular_freq_to_hz(fn)

A decorator that adds to a function the ability to convert the function’s return from angular frequency (rad/s) to frequency (Hz).

A kwarg to_hz is added to the function’s signature, with a default value of False. The keyword is also added to the function’s docstring under the “Other Parameters” heading.

Parameters:fn (function) – The function to be decorated
Raises:ValueError – If fn has already defined a kwarg to_hz
Returns:The decorated function
Return type:callable

Notes

  • If angular_freq_to_hz is used with decorator validate_quantities(), then angular_freq_to_hz should be used inside validate_quantities() but special consideration is needed for setup. The following is an example of an appropriate setup:

    import astropy.units as u
    from plasmapy.utils.decorators.converter import angular_freq_to_hz
    from plasmapy.utils.decorators.validators import validate_quantities
    
    @validate_quantities(validations_on_return={'units': [u.rad / u.s, u.Hz]})
    @angular_freq_to_hz
    def foo(x: u.rad / u.s) -> u.rad / u.s
        return x
    

    Adding u.Hz to the allowed units allows the converted quantity to pass the validations.

Examples

>>> import astropy.units as u
>>> from plasmapy.utils.decorators.converter import angular_freq_to_hz
>>>
>>> @angular_freq_to_hz
... def foo(x):
...     return x
>>>
>>> foo(5 * u.rad / u.s, to_hz=True)
<Quantity 0.79577472 Hz>
>>>
>>> foo(-1 * u.rad / u.s, to_hz=True)
<Quantity -0.15915494 Hz>

Decoration also works with methods

>>> class Foo:
...     def __init__(self, x):
...         self.x = x
...
...     @angular_freq_to_hz
...     def bar(self):
...         return self.x
>>>
>>> foo = Foo(0.5 * u.rad / u.s)
>>> foo.bar(to_hz=True)
<Quantity 0.07957747 Hz>