ParticleList

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

Bases: collections.UserList

A list like collection of Particle and/or CustomParticle objects.

Parameters

particles (iterable, optional) – An iterable that provides a sequence of ParticleLike objects. Objects that are not a Particle or CustomParticle instance will be cast into a Particle instance.

Raises

Examples

A ParticleList can be created by calling it with a list, tuple, or other iterable that provides ParticleLike 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 ParticleLike objects.

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

Normal list methods may also be used on ParticleList objects. When a ParticleLike object is appended to a ParticleList, that object will be cast into a Particle.

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

A Quantity array of the electric charges of the particles.

charge_number

An array of the quantized charges of the particles, as multiples of the elementary charge.

data

A list containing the particles contained in the ParticleList instance.

half_life

A Quantity array of the half-lives of the particles.

mass

A Quantity array of the masses of the particles.

mass_energy

A Quantity array of 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 ParticleLike items from iterable into Particle or CustomParticle instances.

index(item, *args)

Return first index of a ParticleLike value.

insert(index, particle)

Insert a particle before an index.

pop([i])

Remove and return item at index (default last).

remove(item)

Remove the first occurrence of a ParticleLike item.

reverse()

Reverse the ParticleList in place.

sort([key, reverse])

Sort the ParticleList in-place.

Attributes Documentation

charge

A Quantity array of the electric charges of the particles.

charge_number

An array of the quantized charges of the particles, as multiples of the elementary charge.

data

A list containing the particles contained in the ParticleList instance.

The data attribute should not be modified directly.

half_life

A Quantity array of the half-lives of the particles.

mass

A Quantity array of the masses of the particles.

mass_energy

A Quantity array of the mass energies of the particles.

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

symbols

A list of the symbols of the particles.

Methods Documentation

append(particle: Union[str, numbers.Integral, plasmapy.particles.particle_class.Particle, plasmapy.particles.particle_class.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[plasmapy.particles.particle_class.CustomParticle, plasmapy.particles.particle_class.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 the same, then this method will return that item.

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) – If True, use the root mean square charge instead of the mean charge. Defaults to False.

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

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 may be a Particle, CustomParticle, or ParticleLike representation of a particle.

extend(iterable: Iterable[Union[str, numbers.Integral, plasmapy.particles.particle_class.Particle, plasmapy.particles.particle_class.CustomParticle]])

Extend ParticleList by casting ParticleLike items from iterable into Particle or CustomParticle instances.

index(item, *args)

Return first index of a ParticleLike value. Raise ValueError if the value is not present.

insert(index, particle: Union[str, numbers.Integral, plasmapy.particles.particle_class.Particle, plasmapy.particles.particle_class.CustomParticle])

Insert a particle before an index.

pop(i=- 1)

Remove and return item at index (default last). Raise IndexError if the ParticleList is empty or the index is out of range.

remove(item)

Remove the first occurrence of a ParticleLike item. Raise 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.

For more information, refer to the documentation for list.sort.