particle_input

plasmapy.particles.decorators.particle_input(wrapped_function: Optional[Callable] = None, require: Optional[Union[str, Set, List, Tuple]] = None, any_of: Optional[Union[str, Set, List, Tuple]] = None, exclude: Optional[Union[str, Set, List, Tuple]] = None, none_shall_pass: bool = False) → Any

Convert arguments to methods and functions to Particle objects.

Take positional and keyword arguments that are annotated with Particle, and pass through the Particle object corresponding to those arguments to the decorated function or method.

Optionally, raise an exception if the particle does not satisfy the specified categorical criteria.

Parameters

  • wrapped_function (callable) – The function or method to be decorated.

  • require (str, set, list, or tuple, optional) – Categories that a particle must be in. If a particle is not in all of these categories, then an ParticleError will be raised.

  • any_of (str, set, list, or tuple, optional) – Categories that a particle may be in. If a particle is not in any of these categories, then an ParticleError will be raised.

  • exclude (str, set, list, or tuple, optional) – Categories that a particle cannot be in. If a particle is in any of these categories, then an ParticleError will be raised.

  • none_shall_pass (bool, optional) – If set to True, then the decorated argument may be set to None without raising an exception. In such cases, this decorator will pass None through to the decorated function or method. If set to False and the annotated argument is given a value of None, then this decorator will raise a TypeError.

Notes

If the annotated argument is named element, isotope, or ion, then the decorator will raise an InvalidElementError, InvalidIsotopeError, or InvalidIonError if the particle does not correspond to an element, isotope, or ion, respectively.

If exactly one argument is annotated with Particle, then the keywords Z and mass_numb may be used to specify the integer charge and/or mass number of an ion or isotope. However, the decorated function must allow Z and/or mass_numb as keywords in order to enable this functionality.

Raises

  • TypeError – If the annotated argument is not a str, int, tuple, list or Particle; or if Z or mass_numb is not an int.

  • ValueError – If the number of input elements in a collection do not match the number of expected elements.

  • InvalidParticleError – If the annotated argument does not correspond to a valid particle.

  • InvalidElementError – If an annotated argument is named element, and the input does not correspond to an element, isotope, or ion.

  • InvalidIsotopeError – If an annotated argument is named isotope, and the input does not correspond to an isotope or an ion of an isotope.

  • InvalidIonError – If an annotated argument is named ion, and the input does not correspond to an ion.

  • ChargeError – If 'charged' is in the require argument and the particle is not explicitly charged, or if any_of = {'charged',     'uncharged'} and the particle does not have charge information associated with it.

  • ParticleError – If an annotated argument does not meet the criteria set by the categories in the require, any_of, and exclude keywords; if more than one argument is annotated and Z or mass_numb are used as arguments; or if none of the arguments have been annotated with Particle.

Examples

The following simple decorated function returns the Particle object created from the function’s sole argument:

from plasmapy.particles import particle_input, Particle
@particle_input
def decorated_function(particle: Particle):
    return particle

This decorator may also be used to accept arguments using tuple annotation containing specific number of elements or using list annotation which accepts any number of elements in an iterable. Returns a tuple of Particle:

from plasmapy.particles import particle_input, Particle
@particle_input
def decorated_tuple_function(particles: (Particle, Particle)):
    return particles
sample_particles = decorated_tuple_function(('He', 'Li'))

@particle_input
def decorated_list_function(particles: [Particle]):
    return particles
sample_particles = decorated_list_function(('Al 3+', 'C'))
sample_particles = decorated_list_function(['He', 'Ne', 'Ar'])

This decorator may be used for methods in instances of classes, as in the following example:

from plasmapy.particles import particle_input, Particle
class SampleClass:
    @particle_input
    def decorated_method(self, particle: Particle):
        return particle
sample_instance = SampleClass()
sample_instance.decorated_method('Fe')

Some functions may intended to be used with only certain categories of particles. The require, any_of, and exclude keyword arguments enable this functionality.

from plasmapy.particles import particle_input, Particle
@particle_input(
    require={'matter'},
    any_of={'charged', 'uncharged},
    exclude={'neutrino', 'antineutrino'},
)
def selective_function(particle: Particle):
    return particle