This page was generated by nbsphinx from docs/notebooks/getting_started/particles.ipynb.
Interactive online version: .

Using PlasmaPy Particles

The plasmapy.particles subpackage contains functions to access basic particle data and classes to represent particles.

from plasmapy.particles import (
    CustomParticle,
    DimensionlessParticle,
    Particle,
    ParticleList,
    atomic_number,
    charge_number,
    element_name,
    half_life,
    is_stable,
    molecule,
    particle_mass,
)
from plasmapy.particles.particle_class import valid_categories

Contents

1. Particle properties

2. Particle objects

3. Custom particles

4. Molecules

5. Particle lists

6. Dimensionless particles

7. Nuclear reactions

Particle properties

There are several functions that provide information about different particles that might be present in a plasma. The input of these functions is a representation of a particle, such as a string for the atomic symbol or the element name.

atomic_number("Fe")

26

We can provide a number that represents the atomic number.

element_name(26)

'iron'

We can also provide standard symbols or the names of particles.

is_stable("e-")

True

charge_number("proton")

1

The symbols for many particles can even be used directly, such as for an alpha particle. To create an “α” in a Jupyter notebook, type \alpha and press tab.

particle_mass("α")

$6.6446572 \times 10^{-27} \; \mathrm{kg}$

We can represent isotopes with the atomic symbol followed by a hyphen and the mass number. In this example, half_life returns the time in seconds as a Quantity from astropy.units.

half_life("C-14")

$1.8082505 \times 10^{11} \; \mathrm{s}$

We typically represent an ion in a string by putting together the atomic symbol or isotope symbol, a space, the charge number, and the sign of the charge.

charge_number("Fe-56 13+")

13

Functions in plasmapy.particles are quite flexible in terms of string inputs representing particles. An input is particle-like if it can be transformed into a Particle.

particle_mass("iron-56 +13")

$9.2870305 \times 10^{-26} \; \mathrm{kg}$

particle_mass("iron-56+++++++++++++")

$9.2870305 \times 10^{-26} \; \mathrm{kg}$

Most of these functions take additional arguments, with Z representing the charge number of an ion and mass_numb representing the mass number of an isotope. These arguments are often keyword-only to avoid ambiguity.

particle_mass("Fe", Z=13, mass_numb=56)

$9.2870305 \times 10^{-26} \; \mathrm{kg}$

Particle objects

Up until now, we have been using functions that accept representations of particles and then return particle properties. With the Particle class, we can create objects that represent physical particles.

proton = Particle("p+")
electron = Particle("electron")
iron56_nuclide = Particle("Fe", Z=26, mass_numb=56)

Particle properties can be accessed via attributes of the Particle class.

proton.mass

$1.6726219 \times 10^{-27} \; \mathrm{kg}$

electron.charge

$-1.6021766 \times 10^{-19} \; \mathrm{C}$

electron.charge_number

-1

iron56_nuclide.nuclear_binding_energy

$7.8868678 \times 10^{-11} \; \mathrm{J}$

Antiparticles

We can get antiparticles of fundamental particles by using the antiparticle attribute of a Particle.

electron.antiparticle

Particle("e+")

We can also use the tilde operator on a Particle to get its antiparticle.

~proton

Particle("p-")

Ionization and recombination

The recombine and ionize methods of a Particle representing an ion or neutral atom will return a different Particle with fewer or more electrons.

deuterium = Particle("D 0+")
deuterium.ionize()

Particle("D 1+")

When provided with a number, these methods tell how many bound electrons to add or remove.

alpha = Particle("alpha")
alpha.recombine(2)

Particle("He-4 0+")

If the inplace keyword is set to True, then the Particle will be replaced with the new particle.

argon = Particle("Ar 0+")
argon = argon.ionize()
print(argon)

Ar 1+

Custom particles

Sometimes we want to use a particle with custom properties. For example, we might want to represent an average ion in a multi-species plasma. For that we can use CustomParticle.

import astropy.constants as const
import astropy.units as u

custom_particle = CustomParticle(9.27e-26 * u.kg, 13.6 * const.e.si, symbol="Fe 13.6+")

Many of the attributes of CustomParticle are the same as in Particle.

custom_particle.mass

$9.27 \times 10^{-26} \; \mathrm{kg}$

custom_particle.charge

$2.1789602 \times 10^{-18} \; \mathrm{C}$

custom_particle.symbol

'Fe 13.6+'

If we do not include one of the physical quantities, it gets set to nan (not a number) in the appropriate units.

CustomParticle(9.27e-26 * u.kg).charge

${\rm NaN} \; \mathrm{C}$

CustomParticle objects are not yet able to be used by many of the functions in plasmapy.formulary, but are expected to become compatible with them in a future release of PlasmaPy. Similarly, CustomParticle objects are not able to be used by the functions in plasmapy.particles that require that the particle be real.

Particle lists

The ParticleList class is a container for Particle and CustomParticle objects.

iron_ions = ParticleList(["Fe 12+", "Fe 13+", "Fe 14+"])

By using a ParticleList, we can access the properties of multiple particles at once.

iron_ions.mass

$[9.2721873 \times 10^{-26},~9.2720962 \times 10^{-26},~9.2720051 \times 10^{-26}] \; \mathrm{kg}$

iron_ions.charge

$[1.922612 \times 10^{-18},~2.0828296 \times 10^{-18},~2.2430473 \times 10^{-18}] \; \mathrm{C}$

iron_ions.symbols

['Fe 12+', 'Fe 13+', 'Fe 14+']

We can also create a ParticleList by adding Particle and/or CustomParticle objects together.

proton + electron + custom_particle

ParticleList(['p+', 'e-', 'Fe 13.6+'])

Molecules

We can use molecule to create a CustomParticle based on a chemical formula. The first argument to molecule is a string that represents a chemical formula, except that the subscript numbers are not given as subscripts. For example, water is "H2O".

water = molecule("H2O")
water.symbol

'H2O'

The properties of the molecule are found automatically.

water.mass

$2.9914611 \times 10^{-26} \; \mathrm{kg}$

acetic_acid_anion = molecule("CH3COOH 1-")
acetic_acid_anion.charge

$-1.6021766 \times 10^{-19} \; \mathrm{C}$

Particle categorization

The categories attribute of a Particle provides a set of the categories that the Particle belongs to.

muon = Particle("muon")
muon.categories

{'charged', 'fermion', 'lepton', 'matter', 'unstable'}

The is_category() method lets us determine if a Particle belongs to one or more categories.

muon.is_category("lepton")

True

If we need to be more specific, we can use the require keyword for categories that a Particle must belong to, the exclude keyword for categories that the Particle cannot belong to, and the any_of keyword for categories of which a Particle needs to belong to at least one.

electron.is_category(require="lepton", exclude="baryon", any_of={"boson", "fermion"})

True

All valid particle categories are included in valid_categories.

print(valid_categories)

{'charged', 'lepton', 'uncharged', 'lanthanide', 'antineutrino', 'boson', 'antimatter', 'noble gas', 'isotope', 'electron', 'proton', 'transition metal', 'custom', 'unstable', 'neutrino', 'positron', 'antilepton', 'post-transition metal', 'fermion', 'metal', 'alkali metal', 'ion', 'actinide', 'metalloid', 'baryon', 'neutron', 'nonmetal', 'matter', 'halogen', 'stable', 'element', 'alkaline earth metal', 'antibaryon'}

The is_category() method of ParticleList returns a list of boolean values which correspond to whether or not each particle in the list meets the categorization criteria.

particles = ParticleList(["e-", "p+", "n"])
particles.is_category(require="lepton")

False

Dimensionless particles

When we need a dimensionless representation of a particle, we can use the DimensionlessParticle class.

dimensionless_particle = DimensionlessParticle(mass=0.000545, charge=-1)

The properties of dimensionless particles may be accessed by its attributes.

dimensionless_particle.mass

np.float64(0.000545)

dimensionless_particle.charge

np.float64(-1.0)

Because a DimensionlessParticle does not uniquely describe a physical particle, it cannot be contained in a ParticleList.

Nuclear reactions

We can use plasmapy.particles to calculate the energy of a nuclear reaction using the > operator.

deuteron = Particle("D+")
triton = Particle("T+")
alpha = Particle("α")
neutron = Particle("n")

energy = deuteron + triton > alpha + neutron

energy.to("MeV")

$17.589253 \; \mathrm{MeV}$

If the nuclear reaction is invalid, then an exception is raised that states the reason why.

deuteron + triton > alpha + 3 * neutron

ParticleError: The baryon number is not conserved for reactants = [Particle("D 1+"), Particle("T 1+")] and products = [Particle("He-4 2+"), Particle("n"), Particle("n"), Particle("n")].