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+'])
As with an individual Particle
and CustomParticle
, we can check whether
all the particles in a list fall within a category using is_category
.
>>> helium_ions.is_category("ion")
False
We may also check each particle in the list individually by setting
the keyword particlewise
to True
.
>>> helium_ions.is_category("ion", particlewise=True)
[False, True, True]
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
.