ParticleList

class plasmapy.particles.particle_collections.ParticleList(particles: Iterable | None = 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:

• InvalidParticleError – If an object supplied to ParticleList is not particle-like.

• TypeError – If a DimensionlessParticle is provided.

See also

CustomParticle, Particle

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

A ParticleList can also be created using Quantity objects.

>>> import astropy.units as u
>>> quantities = [2.3e-26 * u.kg, 4.8e-19 * u.C]
>>> particle_list = ParticleList(quantities)
>>> particle_list.mass
<Quantity [2.3e-26,     nan] kg>
>>> particle_list.charge
<Quantity [    nan, 4.8e-19] C>

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()	Determine 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: str | int | integer | Particle | CustomParticle | Quantity,

) → None

Append a particle to the end of the ParticleList.

average_particle(

abundances=None,

*,

use_rms_charge: bool = False,

use_rms_mass: bool = False,

) → 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, keyword-only, default: False) – If True, use the root-mean-square charge instead of the mean charge.

• use_rms_mass (bool, 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[str | int | integer | Particle | CustomParticle | Quantity],

) → None

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: str | int | integer | Particle | CustomParticle | Quantity,

) → None

Insert a particle before an index.

is_category(

*category_tuple,

require: str | Iterable[str] | None = None,

any_of: str | Iterable[str] | None = None,

exclude: str | Iterable[str] | None = None,

particlewise: Literal[True] = False,

) → bool

is_category(

*category_tuple,

require: str | Iterable[str] | None = None,

any_of: str | Iterable[str] | None = None,

exclude: str | Iterable[str] | None = None,

particlewise: Literal[False],

) → list[bool]

Determine if the particles in the ParticleList meet categorization criteria.

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

Parameters:

particlewise (bool, default: False) – If True, return a list of bool in which an element will be True if the corresponding particle is consistent with the categorization criteria, and False otherwise. If False, return a bool which will be True if all particles are consistent with the categorization criteria and False otherwise.

Return type:

bool or list of bool

See also

None

Examples

>>> particles = ParticleList(["proton", "electron", "tau neutrino"])
>>> particles.is_category("lepton")
False
>>> particles.is_category("lepton", particlewise=True)
[False, True, True]
>>> particles.is_category(require="lepton", exclude="neutrino")
False
>>> particles.is_category(
...     require="lepton", exclude="neutrino", particlewise=True
... )
[False, True, False]
>>> particles.is_category(any_of=["lepton", "charged"])
True
>>> particles.is_category(any_of=["lepton", "charged"], particlewise=True)
[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: Callable | None = 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'])