ParticleList

class plasmapy.particles.particle_collections.ParticleList(particles: Optional[Iterable] = None)

Bases: UserList

A list like collection of Particle and CustomParticle objects.

Parameters

particles (iterable of particle-like, optional) – An iterable that provides a sequence of particle-like objects. Objects that are not a Particle or CustomParticle will be cast into a Particle or CustomParticle. If not provided, an empty ParticleList will be created.

Raises

Examples

A ParticleList can be created by calling it with an iterable like a list or tuple that provides particle-like objects.

>>> from plasmapy.particles import ParticleList
>>> particle_list = ParticleList(["e-", "e+"])
>>> particle_list[0]
Particle("e-")

Attributes such as mass and charge will return a Quantity array containing the values of the corresponding attribute for each particle in the ParticleList.

>>> particle_list.mass
<Quantity [9.1093...e-31, 9.1093...e-31] kg>
>>> particle_list.charge
<Quantity [-1.60217663e-19,  1.60217663e-19] C>
>>> particle_list.symbols
['e-', 'e+']

ParticleList instances can also be created through addition and multiplication with Particle, CustomParticle, and ParticleList instances.

>>> from plasmapy.particles import Particle, CustomParticle
>>> import astropy.units as u
>>> proton = Particle("p+")
>>> custom_particle = CustomParticle(mass=1e-26*u.kg, charge=6e-19*u.C)
>>> 2 * proton + custom_particle
ParticleList(['p+', 'p+', 'CustomParticle(mass=1e-26 kg, charge=6e-19 C)'])

These operations may also be performed using particle-like objects.

>>> particle_list + "deuteron"
ParticleList(['e-', 'e+', 'D 1+'])

Normal list methods may also be used on ParticleList objects. When a particle-like object is appended to a ParticleList, that object will be cast into a Particle or CustomParticle.

>>> noble_gases = ParticleList(["He", "Ar", "Kr", "Xe", "Rn"])
>>> noble_gases.append("Og")
>>> noble_gases[-1]
Particle("Og")

The > operator may be used with Particle and ParticleList instances to access the nuclear reaction energy.

>>> reactants = ParticleList(["deuterium", "tritium"])
>>> products = ParticleList(["alpha", "neutron"])
>>> energy = reactants > products
>>> energy.to("MeV")
<Quantity 17.58925... MeV>

Attributes Summary

charge

The electric charges of the particles.

charge_number

The charges of the particles in units of the elementary charge.

data

A list containing the particles contained in the ParticleList instance.

half_life

The half-lives of the particles.

mass

The masses of the particles.

mass_energy

The mass energies of the particles.

symbols

A list of the symbols of the particles.

Methods Summary

append(particle)

Append a particle to the end of the ParticleList.

average_particle([abundances, ...])

Return a particle with the average mass and charge.

clear()

Remove all items from the ParticleList.

copy()

Return a shallow copy of the ParticleList.

count(item)

Return the number of occurrences of item.

extend(iterable)

Extend ParticleList by casting particle-like items from iterable into particle objects.

index(item, *args)

Return first index of a particle-like value.

insert(index, particle)

Insert a particle before an index.

is_category(*category_tuple[, require, ...])

Determine element-wise if the particles in the ParticleList meet categorization criteria.

pop([i])

Remove and return item at index (default last).

remove(item)

Remove the first occurrence of a particle-like item.

reverse()

Reverse the ParticleList in place.

sort([key, reverse])

Sort the ParticleList in-place.

Attributes Documentation

charge

The electric charges of the particles.

Return type

Quantity

charge_number

The charges of the particles in units of the elementary charge.

Return type

ndarray

data

A list containing the particles contained in the ParticleList instance.

Important

This attribute should not be modified directly.

Return type

list of Particle or CustomParticle

half_life

The half-lives of the particles.

Return type

Quantity

mass

The masses of the particles.

Return type

Quantity

mass_energy

The mass energies of the particles.

If the particle is an isotope or nuclide, return the mass energy of the nucleus only.

Return type

Quantity

symbols

A list of the symbols of the particles.

Return type

list of str

Methods Documentation

append(particle: Union[str, Integral, Particle, CustomParticle])

Append a particle to the end of the ParticleList.

average_particle(abundances=None, *, use_rms_charge: bool = False, use_rms_mass: bool = False) Union[CustomParticle, Particle]

Return a particle with the average mass and charge.

By default, the mean will be used as the average. If the abundances are provided, then this method will return the weighted mean. If use_rms_charge or use_rms_mass is True, then this method will return the root-mean-square of the charge or mass, respectively. If all items in the ParticleList are equal to each other, then this method will return the first item in the ParticleList.

Parameters
  • abundances (array_like, optional) – Real numbers representing relative abundances of the particles in the ParticleList. Must have the same number of elements as the ParticleList. This parameter gets passed to numpy.average via that function’s weights parameter. If not provided, the particles contained in the ParticleList are assumed to be equally abundant.

  • use_rms_charge (bool, optional, keyword-only, default: False) – If True, use the root-mean-square charge instead of the mean charge.

  • use_rms_mass (bool, optional, keyword-only, default: False) – If True, use the root-mean-square mass instead of the mean mass.

Return type

Particle or CustomParticle

Examples

>>> reactants = ParticleList(["electron", "positron"])
>>> reactants.average_particle()
CustomParticle(mass=9.109383...e-31 kg, charge=0.0 C)
>>> reactants.average_particle(abundances=[1, 0.5])
CustomParticle(mass=9.109383...e-31 kg, charge=-5.34058...e-20 C)
>>> reactants.average_particle(use_rms_charge=True)
CustomParticle(mass=9.109383...e-31 kg, charge=1.6021766...-19 C)
>>> protons = ParticleList(["p+", "p+", "p+"])
>>> protons.average_particle()
Particle("p+")
clear()

Remove all items from the ParticleList.

copy()

Return a shallow copy of the ParticleList.

count(item)

Return the number of occurrences of item. Here, item must be particle-like.

extend(iterable: Iterable[Union[str, Integral, Particle, CustomParticle]])

Extend ParticleList by casting particle-like items from iterable into particle objects.

index(item, *args)

Return first index of a particle-like value.

Raises

ValueError – If the value is not present.

insert(index, particle: Union[str, Integral, Particle, CustomParticle])

Insert a particle before an index.

is_category(*category_tuple, require: Optional[Union[str, Iterable[str]]] = None, any_of: Optional[Union[str, Iterable[str]]] = None, exclude: Optional[Union[str, Iterable[str]]] = None) List[bool]

Determine element-wise if the particles in the ParticleList meet categorization criteria.

Return a list in which each element will be True if the corresponding particle is consistent with the categorization criteria, and False otherwise.

Please refer to the documentation of is_category for information on the parameters and categories, as well as more extensive examples.

Return type

list of bool

Examples

>>> particles = ParticleList(["proton", "electron", "tau neutrino"])
>>> particles.is_category("lepton")
[False, True, True]
>>> particles.is_category(require="lepton", exclude="neutrino")
[False, True, False]
>>> particles.is_category(any_of=["lepton", "charged"])
[True, True, True]
pop(i=-1)

Remove and return item at index (default last).

Raises

IndexError – If the ParticleList is empty or the index is out of range.

remove(item)

Remove the first occurrence of a particle-like item.

Raises

ValueError – If the value is not present.

reverse()

Reverse the ParticleList in place.

sort(key: Optional[Callable] = None, reverse: bool = False)

Sort the ParticleList in-place.

Parameters
  • key (callable) – A function that accepts one argument that is used to extract a comparison key for each item in the ParticleList.

  • reverse (bool, default: False) – If True, the items in the ParticleList are sorted as if each comparison were reversed.

Raises

TypeError – If key is not provided.

See also

list.sort, sorted

Examples

To sort a ParticleList by atomic number, set key to atomic_number().

>>> from plasmapy.particles import ParticleList, atomic_number
>>> elements = ParticleList(["Li", "H", "He"])
>>> elements.sort(key=atomic_number)
>>> print(elements)
ParticleList(['H', 'He', 'Li'])

We can also create a function to pass to key. In this example, we sort first by atomic number and second by mass number using different attributes of Particle.

>>> def sort_key(isotope):
...     return isotope.atomic_number, isotope.mass_number
>>> isotopes = ParticleList(["He-3", "T", "H-1", "He-4", "D"])
>>> isotopes.sort(key=sort_key)
>>> print(isotopes)
ParticleList(['H-1', 'D', 'T', 'He-3', 'He-4'])