Particle objects
PlasmaPy contains several classes to represent particles, including
Particle, CustomParticle, ParticleList, and
DimensionlessParticle.
Particles
To create a Particle object, pass it a particle-like string that
represents a particle.
>>> from plasmapy.particles import Particle
>>> electron = Particle('e-')
The Particle class accepts a variety of different str formats to
represent particles. Atomic symbols are case-sensitive, but element
names and many aliases are not.
An int may be used as the first positional argument to Particle to
represent an atomic number. For isotopes and ions, the mass number may
be represented with the mass_numb keyword and the charge number
may be represented with the Z keyword.
The most frequently used Particle objects may be imported directly
from plasmapy.particles.
>>> from plasmapy.particles import proton, electron
The Particle objects that may be imported directly are:
proton, electron,
neutron, positron,
deuteron, triton, and
alpha.
Accessing particle properties
The properties of each particle may be accessed using the attributes of
the corresponding Particle object.
>>> proton.atomic_number
1
>>> electron.charge_number
-1
>>> triton.mass_number
3
These properties are often returned as a Quantity in SI units.
>>> alpha.charge
<Quantity 3.20435324e-19 C>
>>> deuteron.mass
<Quantity 3.34358372e-27 kg>
>>> triton.half_life
<Quantity 3.888e+08 s>
>>> iron56.binding_energy.to('GeV')
<Quantity 0.49225958 GeV>
Strings representing particles may be accessed using the
symbol,
element,
isotope, and
ionic_symbol attributes.
>>> antimuon.symbol
'mu+'
>>> triton.element
'H'
>>> alpha.isotope
'He-4'
>>> deuteron.ionic_symbol
'D 1+'
Categories
The categories attribute
returns a set with the classification categories corresponding to the
particle.
>>> sorted(electron.categories)
['charged', 'electron', 'fermion', 'lepton', 'matter', 'stable']
Membership of a particle within a category may be checked using
is_category.
>>> alpha.is_category('lepton')
False
>>> electron.is_category('fermion', 'lepton', 'charged')
True
>>> iron56.is_category(['element', 'isotope'])
True
The particle must be in all of the categories in the require
keyword, at least one of the categories in the any_of keyword, and
none of the categories in the exclude in order for it to return
True.
>>> deuteron.is_category(require={'element', 'isotope', 'ion'})
True
>>> iron56.is_category(any_of=['charged', 'uncharged'])
False
>>> alpha.is_category(exclude='lepton')
True
Valid particle categories are listed in the docstring for is_category.
Conditionals and equality properties
Equality between particles may be tested either between two Particle
objects, or between a Particle object and a str.
The is_electron and
is_ion attributes
provide a quick way to check whether or not a particle is an electron or
ion, respectively.
>>> electron.is_electron
True
>>> hydride.is_electron
False
>>> deuteron.is_ion
True
.. _particle-class-antiparticles:
Returning antiparticles
The antiparticle of an elementary particle or antiparticle may be found
by either using Python’s unary invert operator (~) or the
antiparticle attribute
of a Particle object.
>>> ~electron
Particle("e+")
>>> antimuon.antiparticle
Particle("mu-")
Custom particles
We can use CustomParticle to create particle objects with a mass,
charge, and/or symbol that we provide. The mass and charge must be
Quantity objects from astropy.units.
>>> import astropy.units as u
>>> from plasmapy.particles import CustomParticle
>>> cp = CustomParticle(mass = 9.3e-26 * u.kg, charge = 1.5e-18 * u.C, symbol = "Fe 9.5+")
CustomParticle has many of the same attributes and methods as
Particle, and can often be used interchangeably.
If the charge and/or mass is not provided, the attribute will return
nan in the appropriate units.
Molecules
We can use molecule to convert a
chemical symbol into a CustomParticle object with the appropriate
mass, charge, and symbol.
>>> from plasmapy.particles import molecule
>>> molecule("CO2 1+") # carbon dioxide cation
CustomParticle(mass=7.30786637819994e-26 kg, charge=1.602176634e-19 C, symbol=CO2 1+)
Particle lists
ParticleList lets us work with multiple particles at once. A
ParticleList can contain Particle and/or CustomParticle objects.
We can create a ParticleList by providing it with a
particle-list-like object (i.e., a list containing particle-like
objects). For example, we could provide ParticleList with a list of
strings that represent individual particles.
>>> from plasmapy.particles import ParticleList
>>> helium_ions = ParticleList(["He-4 0+", "He-4 1+"])
ParticleList objects behave similarly to list objects, but convert
its contents into the appropriate Particle or CustomParticle
objects.
>>> helium_ions.append("alpha")
>>> print(helium_ions)
ParticleList(['He-4 0+', 'He-4 1+', 'He-4 2+'])
>>> helium_ions[1]
Particle("He-4 1+")
ParticleList shares many of the same attributes as Particle and
CustomParticle. Attributes of Particle and CustomParticle that
provide a scalar Quantity will provide a Quantity array from
ParticleList.
>>> helium_ions.charge
<Quantity [0.00000000e+00, 1.60217663e-19, 3.20435327e-19] C>
>>> helium_ions.mass
<Quantity [6.64647907e-27, 6.64556813e-27, 6.64465719e-27] kg>
If we provide a Quantity with units of mass or charge, it will get
converted into a CustomParticle.
>>> cp_list = ParticleList([1 * u.kg, 1 * u.C])
>>> cp_list[0]
CustomParticle(mass=1.0 kg, charge=nan C)
>>> cp_list.charge
<Quantity [nan, 1.] C>
>>> cp_list.mass
<Quantity [ 1., nan] kg>
We can create a CustomParticle with the mean mass and charge of the
particles in a ParticleList with its
average_particle
method.
>>> helium_ions.average_particle()
CustomParticle(mass=6.645568133213004e-27 kg, charge=1.602176634e-19 C)
We can create a ParticleList by adding Particle, CustomParticle,
and/or ParticleList objects together.
>>> helium_ions + cp + proton
ParticleList(['He-4 0+', 'He-4 1+', 'He-4 2+', 'Fe 9.5+', 'p+'])
The machinery contained with ParticleList lets us calculate plasma
parameters from plasmapy.formulary for multiple particles at once.
>>> from plasmapy.formulary import gyroradius
>>> gyroradius(B = 5 * u.nT, particle=["e-", "p+"], Vperp = 100 * u.km/u.s)
<Quantity [1.13712608e+02, 2.08793710e+05] m>
Dimensionless particles
We can use DimensionlessParticle to represent particles that have been
normalized (i.e., both the mass and charge are dimensionless).
>>> dp = DimensionlessParticle(mass=1, charge=-1)
>>> dp.charge
-1.0
>>> dp.mass
1.0
Because DimensionlessParticle objects do not directly represent
physical particles without normalization information, they cannot be
contained within a ParticleList or used in plasmapy.formulary.