decorators.rst

Decorators

Passing objects to functions and methods

When calculating plasma parameters, we frequently need to access the properties of the particles that make up that plasma. The decorator allows functions and methods to easily access properties of different particles.

The decorator takes valid representations of particles given in arguments to functions and passes through the corresponding object. The arguments must be annotated with so that the decorator knows to create the object. The decorated function can then access particle properties by using attributes. This decorator will raise an if the input does not correspond to a valid particle.

Here is an example of a decorated function.

from plasmapy.particles import Particle, particle_input

@particle_input
def particle_mass(particle: Particle):
    return particle.mass

This function can now accept either objects or valid representations of particles.

>>> particle_mass('p+') # string input <Quantity 1.67262192e-27 kg> >>> proton = Particle("proton") >>> particle_mass(proton) # Particle object input <Quantity 1.67262192e-27 kg>

If only one positional or keyword argument is annotated with , then the keywords mass_numb and Z may be used when the decorated function is called.

@particle_input
def charge_number(particle: Particle, Z: int = None, mass_numb: int = None) -> int:
    return particle.charge_number

The above example includes optional type hint annotations for Z and mass_numb and the returned value. The decorator may be used in methods in classes as well:

class ExampleClass:
    @particle_input
    def particle_symbol(self, particle: Particle) -> str:
        return particle.symbol

On occasion it is necessary for a function to accept only certain categories of particles. The decorator enables several ways to allow this.

If an annotated keyword is named element, isotope, or ion; then will raise an , , or if the particle is not associated with an element, isotope, or ion; respectively.

@particle_input
def capitalized_element_name(element: Particle):
    return element.element_name

@particle_input
def number_of_neutrons(isotope: Particle):
    return isotope.mass_number - isotope.atomic_number

@particle_input
def number_of_bound_electrons(ion: Particle):
    return ion.atomic_number - ion.charge_number

The keywords require, any_of, and exclude to the decorator allow further customization of the particle categories allowed as inputs. These keywords are used as in ~plasmapy.particles.particle_class.Particle.is_category.

@particle_input(require='charged')
def sign_of_charge(charged_particle: Particle):
    """Require a charged particle."""
    return '+' if charged_particle.charge_number > 0 else '-'

@particle_input(any_of=['charged', 'uncharged'])
def charge_number(particle: Particle) -> int:
    """Accept only particles with charge information."""
    return particle.charge_number

@particle_input(exclude={'antineutrino', 'neutrino'})
def particle_mass(particle: Particle):
    """
    Exclude neutrinos/antineutrinos because these particles have
    weakly constrained masses.
    """
    return particle.mass