# ParticleList

class plasmapy.particles.particle_collections.ParticleList(particles: = 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. Remove all items from the ParticleList. 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 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
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

Methods Documentation

append(particle: )

Append a particle to the end of the ParticleList.

average_particle(abundances=None, *, use_rms_charge: bool = False, use_rms_mass: bool = False)

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
Return type

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: )

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: )

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

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: = None, reverse: bool = False)

Sort the ParticleList in-place.

Parameters
Raises

TypeError – If key is not provided.

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'])