# Particle

class plasmapy.particles.particle_class.Particle(argument: , *_, mass_numb: = None, Z: = None)

A class for an individual particle or antiparticle.

Parameters
Raises

Notes

Valid particle categories include: "actinide", "alkali metal", "alkaline earth metal", "antibaryon", "antilepton", "antimatter", "antineutrino", "baryon", "boson", "charged", "custom", "electron", "element", "fermion", "halogen", "ion", "isotope", "lanthanide", "lepton", "matter", "metal", "metalloid", "neutrino", "neutron", "noble gas", "nonmetal", "positron", "post-transition metal", "proton", "stable", "transition metal", "uncharged", and "unstable".

Examples

Particles may be defined using a wide variety of aliases:

>>> proton = Particle('p+')
>>> electron = Particle('e-')
>>> neutron = Particle('neutron')
>>> deuteron = Particle('D', Z=1)
>>> triton = Particle('T+')
>>> alpha = Particle('He', mass_numb=4, Z=2)
>>> positron = Particle('positron')
>>> hydrogen = Particle(1)  # atomic number


The symbol attribute returns the particle’s symbol in the standard form.

>>> positron.symbol
'e+'


The element, isotope, and ionic_symbol attributes provide the symbols for each of these different types of particles.

>>> proton.element
'H'
>>> alpha.isotope
'He-4'
>>> deuteron.ionic_symbol
'D 1+'


The ionic_symbol attribute works for neutral atoms if charge information is available.

>>> deuterium = Particle("D", Z=0)
>>> deuterium.ionic_symbol
'D 0+'


If the particle doesn’t belong to one of those categories, then these attributes are None.

>>> positron.element is None
True


The attributes of a Particle instance may be used to test whether or not a particle is an element, isotope, or ion.

>>> True if positron.element else False
False
>>> True if deuterium.isotope else False
True
>>> True if Particle('alpha').is_ion else False
True


Many of the attributes provide physical properties of a particle.

>>> electron.charge_number
-1
>>> proton.spin
0.5
>>> alpha.atomic_number
2
>>> deuteron.mass_number
2
>>> deuteron.binding_energy.to('MeV')
<Quantity 2.224... MeV>
>>> alpha.charge
<Quantity 3.20435...e-19 C>
>>> neutron.half_life
<Quantity 881.5 s>
>>> Particle('C-14').half_life.to(u.year)
<Quantity 5730. yr>
>>> deuteron.electron_number
0
>>> alpha.neutron_number
2


If a Particle instance represents an elementary particle, then the unary ~ (invert) operator may be used to return the particle’s antiparticle.

>>> ~positron
Particle("e-")


A Particle instance may be used as the first argument to Particle.

>>> iron = Particle('Fe')
>>> iron == Particle(iron)
True
>>> Particle(iron, mass_numb=56, Z=6)
Particle("Fe-56 6+")


If the previously constructed Particle instance represents an element, then the Z and mass_numb arguments may be used to specify an ion or isotope.

>>> iron = Particle('Fe')
>>> Particle(iron, Z=1)
Particle("Fe 1+")
>>> Particle(iron, mass_numb=56)
Particle("Fe-56")


Adding particles together will create a ParticleList, which is a list-like collection of particles.

>>> proton + 2 * electron
ParticleList(['p+', 'e-', 'e-'])


The > operator can be used with Particle and/or ParticleList objects to return the nuclear reaction energy.

>>> deuteron + triton > alpha + neutron
<Quantity 2.81810898e-12 J>


The categories attribute and is_category method may be used to find and test particle membership in categories. Please refer to is_category for more details, including a list of all valid particle categories.

Attributes Summary

 antiparticle The antiparticle corresponding to the particle. atomic_number The number of protons in an element, isotope, or ion. baryon_number The number of baryons in a particle. binding_energy The particle's nuclear binding energy. categories The particle's categories. charge The particle's electrical charge in coulombs. charge_number The particle's electrical charge in units of the elementary charge. electron_number The number of electrons in an ion. element The atomic symbol if the particle corresponds to an element, and None otherwise. element_name The name of the element corresponding to this particle. half_life The particle's half-life in seconds, or a str with half-life information. ionic_symbol The ionic symbol if the particle corresponds to an ion or neutral atom, and None otherwise. is_electron True if the particle is an electron, and False otherwise. is_ion True if the particle is an ion, and False otherwise. isotope The isotope symbol if the particle corresponds to an isotope, and None otherwise. isotope_name The name of the element along with the isotope symbol if the particle corresponds to an isotope, or None if it does not. isotopic_abundance The isotopic abundance of an isotope. json_dict A JSON friendly dictionary representation of the particle. lepton_number 1 for leptons, -1 for antileptons, and 0 otherwise. mass The mass of the particle in kilograms. mass_energy The mass energy of the particle in joules. mass_number The total number of protons and neutrons in an isotope or nuclide. neutron_number The number of neutrons in an isotope or nucleon. nuclide_mass The mass of the bare nucleus of an isotope or a neutron. periodic_table A namedtuple that provides access to category, period, group, and block information about an element. roman_symbol The spectral name of the particle (i.e. spin The intrinsic spin of the particle. standard_atomic_weight The element's standard atomic weight in kg. symbol The symbol of the particle, atom, isotope, or ion.

Methods Summary

 ionize([n, inplace]) Create a new Particle instance corresponding to the current Particle after being ionized n times. is_category(*category_tuple[, require, ...]) Determine if the particle meets categorization criteria. json_dump(fp, **kwargs) Write the particle's json_dict to the fp file object using json.dump. json_dumps(**kwargs) Serialize the particle's json_dict into a JSON formatted str using json.dumps. recombine([n, inplace]) Create a new Particle instance corresponding to the current Particle after undergoing recombination n times.

Attributes Documentation

antiparticle

The antiparticle corresponding to the particle.

This attribute may be accessed by using the unary operator ~ on a Particle instance.

Raises

ParticleError – If the particle is not an elementary particle and does not have a defined antiparticle.

Examples

>>> electron = Particle('e-')
>>> electron.antiparticle
Particle("e+")

>>> antineutron = Particle('antineutron')
>>> ~antineutron
Particle("n")

atomic_number

The number of protons in an element, isotope, or ion.

Raises

InvalidElementError – If the particle does not correspond to an element.

Examples

>>> proton = Particle('p+')
>>> proton.atomic_number
1
>>> curium = Particle('Cm')
>>> curium.atomic_number
96

baryon_number

The number of baryons in a particle.

This attribute will return the number of protons and neutrons minus the number of antiprotons and antineutrons. The baryon number is equivalent to the mass number for isotopes.

Raises

MissingParticleDataError – If the baryon number is unavailable.

Examples

>>> alpha = Particle('alpha')
>>> alpha.baryon_number
4

binding_energy

The particle’s nuclear binding energy.

Raises

InvalidIsotopeError – If the particle is not a nucleon or isotope.

Examples

>>> alpha = Particle('alpha')
>>> alpha.binding_energy
<Quantity 4.53346...e-12 J>
>>> Particle('T').binding_energy.to('MeV')
<Quantity 8.481... MeV>


The binding energy of a nucleon equals 0 joules.

>>> neutron = Particle('n')
>>> proton = Particle('p+')
>>> neutron.binding_energy
<Quantity 0. J>
>>> proton.binding_energy
<Quantity 0. J>

categories

The particle’s categories.

Examples

>>> gold = Particle('Au')
>>> 'transition metal' in gold.categories
True
>>> 'antilepton' in gold.categories
False

charge

The particle’s electrical charge in coulombs.

Raises

ChargeError – If the charge has not been specified.

Examples

>>> electron = Particle('e-')
>>> electron.charge
<Quantity -1.60217662e-19 C>

charge_number

The particle’s electrical charge in units of the elementary charge.

Raises

ChargeError – If the charge has not been specified.

Examples

>>> muon = Particle('mu-')
>>> muon.charge_number
-1

electron_number

The number of electrons in an ion.

This attribute will return the number of bound electrons in an ion, or 1 for an electron.

Raises

InvalidIonError – If this particle is not an ion or electron.

Examples

>>> Particle('Li 0+').electron_number
3
>>> Particle('e-').electron_number
1

element

The atomic symbol if the particle corresponds to an element, and None otherwise.

Examples

>>> alpha = Particle('alpha')
>>> alpha.element
'He'

element_name

The name of the element corresponding to this particle.

Raises

InvalidElementError – If the particle does not correspond to an element.

Examples

>>> tritium = Particle('T')
>>> tritium.element_name
'hydrogen'

half_life

The particle’s half-life in seconds, or a str with half-life information.

Particles that do not have sufficiently well-constrained half-lives will return a str containing the information that is available about the half-life and issue a MissingParticleDataWarning.

Examples

>>> neutron = Particle('n')
>>> neutron.half_life
<Quantity 881.5 s>

ionic_symbol

The ionic symbol if the particle corresponds to an ion or neutral atom, and None otherwise.

Examples

>>> deuteron = Particle('deuteron')
>>> deuteron.ionic_symbol
'D 1+'
>>> hydrogen_atom = Particle('H', Z=0)
>>> hydrogen_atom.ionic_symbol
'H 0+'

is_electron

True if the particle is an electron, and False otherwise.

Examples

>>> Particle('e-').is_electron
True
>>> Particle('e+').is_electron
False

is_ion

True if the particle is an ion, and False otherwise.

Examples

>>> Particle('D+').is_ion
True
>>> Particle('H-1 0+').is_ion
False
>>> Particle('e+').is_ion
False

isotope

The isotope symbol if the particle corresponds to an isotope, and None otherwise.

Examples

>>> alpha = Particle('alpha')
>>> alpha.isotope
'He-4'

isotope_name

The name of the element along with the isotope symbol if the particle corresponds to an isotope, or None if it does not.

Raises

Examples

>>> deuterium = Particle("D")
>>> deuterium.isotope_name
'deuterium'
>>> iron_isotope = Particle("Fe-56", Z=16)
>>> iron_isotope.isotope_name
'iron-56'

isotopic_abundance

The isotopic abundance of an isotope.

Raises

Examples

>>> D = Particle('deuterium')
>>> D.isotopic_abundance
0.000115

json_dict

A JSON friendly dictionary representation of the particle.

See AbstractParticle.json_dict for more details.

Examples

>>> lead = Particle('lead')
{'plasmapy_particle': {'type': 'Particle',
'module': 'plasmapy.particles.particle_class',
'date_created': '...',
'__init__': {'args': ('Pb',), 'kwargs': {}}}}
>>> electron = Particle('e-')
>>> electron.json_dict
{'plasmapy_particle': {'type': 'Particle',
'module': 'plasmapy.particles.particle_class',
'date_created': '...',
'__init__': {'args': ('e-',), 'kwargs': {}}}}

lepton_number

1 for leptons, -1 for antileptons, and 0 otherwise.

This attribute returns the number of leptons minus the number of antileptons, excluding bound electrons in an atom or ion.

Raises

MissingParticleDataError – If the lepton number is unavailable.

Examples

>>> Particle('e-').lepton_number
1
>>> Particle('mu+').lepton_number
-1
>>> Particle('He-4 0+').lepton_number
0

mass

The mass of the particle in kilograms.

If the particle is an element and not an isotope or ion, then this attribute will return the standard atomic weight, if available.

If the particle is an isotope but not an ion, then this attribute will return the isotopic mass, including bound electrons.

If the particle is an ion, then this attribute will return the mass of the element or isotope (as just described) minus the product of the charge number and the electron mass.

For special particles, this attribute will return the standard value for the particle’s mass.

Raises

MissingParticleDataError – If the mass is unavailable (e.g., for neutrinos or elements with no standard atomic weight.

Examples

>>> Particle('He').mass
<Quantity 6.64647...e-27 kg>
>>> Particle('He+').mass
<Quantity 6.64556...e-27 kg>
>>> Particle('He-4 +1').mass
<Quantity 6.64556...e-27 kg>
>>> Particle('alpha').mass
<Quantity 6.64465...e-27 kg>

mass_energy

The mass energy of the particle in joules.

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

If the mass of the particle is not known, then raise a MissingParticleDataError.

Examples

>>> proton = Particle('p+')
>>> proton.mass_energy
<Quantity 1.503277...e-10 J>

>>> protium = Particle('H-1 0+')
>>> protium.mass_energy
<Quantity 1.503277...e-10 J>

>>> electron = Particle('electron')
>>> electron.mass_energy.to('MeV')
<Quantity 0.510998... MeV>

mass_number

The total number of protons and neutrons in an isotope or nuclide.

Raises

InvalidIsotopeError – If the particle does not correspond to an isotope.

Examples

>>> alpha = Particle('helium-4 2+')
>>> alpha.mass_number
4

neutron_number

The number of neutrons in an isotope or nucleon.

This attribute will return the number of neutrons in an isotope, or 1 for a neutron.

If this particle is not an isotope or neutron, then this attribute will raise an InvalidIsotopeError.

Examples

>>> alpha = Particle('He-4++')
>>> alpha.neutron_number
2
>>> Particle('n').neutron_number
1

nuclide_mass

The mass of the bare nucleus of an isotope or a neutron.

Raises

Examples

>>> deuterium = Particle('D')
>>> deuterium.nuclide_mass
<Quantity 3.34358372e-27 kg>

periodic_table

A namedtuple that provides access to category, period, group, and block information about an element.

Raises

InvalidElementError – If the particle is not an element, isotope, or ion.

Examples

>>> gold = Particle('Au')
>>> gold.periodic_table.category
'transition metal'
>>> gold.periodic_table.period
6
>>> gold.periodic_table.group
11
>>> gold.periodic_table.block
'd'

roman_symbol

The spectral name of the particle (i.e. the ionic symbol in Roman numeral notation).

If the particle is not an ion or neutral atom, return None. The roman numeral represents one plus the charge number. Raise ChargeError if no charge has been specified and OutOfRangeError if the charge is negative.

Examples

>>> proton = Particle('proton')
>>> proton.roman_symbol
'H-1 II'
>>> hydrogen_atom = Particle('H', Z=0)
>>> hydrogen_atom.roman_symbol
'H I'

spin

The intrinsic spin of the particle.

If the spin is unavailable, then a MissingParticleDataError will be raised.

Examples

>>> positron = Particle('e+')
>>> positron.spin
0.5

standard_atomic_weight

The element’s standard atomic weight in kg.

Raises

Examples

>>> oxygen = Particle('O')
>>> oxygen.standard_atomic_weight
<Quantity 2.656696...e-26 kg>

symbol

The symbol of the particle, atom, isotope, or ion.

This attribute will return the canonical symbol for special particles (e.g., "p+", "e-", or "n"), the atomic symbol for elements (e.g., "Fe"), the isotopic symbol for isotopes (e.g., "D" or "Fe-56"), and the ionic symbol for ions (e.g., "N 1+" or "He-4 1+").

Examples

>>> electron = Particle('positron')
>>> electron.symbol
'e+'
>>> deuteron = Particle('D 1+')
>>> deuteron.symbol
'D 1+'


Methods Documentation

ionize(n: Integral = 1, inplace: bool = False)

Create a new Particle instance corresponding to the current Particle after being ionized n times.

If inplace is False (default), then return the ionized Particle. If inplace is True, then replace the current Particle with the newly ionized Particle.

New in version 0.8: If the Particle instance has no charge information (e.g., Particle("Li")), this method assumes it to be electrically neutral.

Parameters
Returns

particle – A new Particle object that has been ionized n times relative to the original Particle. If inplace is False, instead return None.

Return type

Particle

Raises

Examples

>>> Particle("Fe 6+").ionize()
Particle("Fe 7+")
>>> helium_particle = Particle("He-4 0+")
>>> helium_particle.ionize(n=2, inplace=True)
>>> helium_particle
Particle("He-4 2+")
>>> Particle("Li").ionize(3)
Particle("Li 3+")

is_category(*category_tuple, require: Optional[Union[str, Iterable[str]]] = None, any_of: Optional[Union[str, Iterable[str]]] = None, exclude: Optional[Union[str, Iterable[str]]] = None) bool

Determine if the particle meets categorization criteria.

Return True if the particle is consistent with the provided categories, and False otherwise.

Parameters

valid_categories

A set containing all valid particle categories.

Notes

Valid particle categories are given in valid_categories and include: "actinide", "alkali metal", "alkaline earth metal", "antibaryon", "antilepton", "antimatter", "antineutrino", "baryon", "boson", "charged", "custom", "electron", "element", "fermion", "halogen", "ion", "isotope", "lanthanide", "lepton", "matter", "metal", "metalloid", "neutrino", "neutron", "noble gas", "nonmetal", "positron", "post-transition metal", "proton", "stable", "transition metal", "uncharged", and "unstable".

Examples

Required categories may be entered as positional arguments, including as a list, set, or tuple of required categories.

>>> electron = Particle("e-")
>>> electron.is_category("lepton")
True
>>> electron.is_category("lepton", "baryon")
False
>>> electron.is_category(["fermion", "matter"])
True


Required arguments may also be provided using the require keyword argument.

>>> electron.is_category(require="lepton")
True
>>> electron.is_category(require=["lepton", "baryon"])
False


This method will return False if the particle does not belong to at least one of the categories provided with the any_of keyword argument.

>>> electron.is_category(any_of=["lepton", "baryon"])
True
>>> electron.is_category(any_of=("noble gas", "lanthanide", "halogen"))
False


This method will return False if the particle belongs to any of the categories provided in the exclude keyword argument.

>>> electron.is_category(exclude="baryon")
True
>>> electron.is_category(exclude={"lepton", "baryon"})
False


The require, any_of, and exclude keywords may be combined. If the particle matches all of the provided criteria, then this method will return True.

>>> electron.is_category(
...     require="fermion", any_of={'lepton', 'baryon'}, exclude='charged',
... )
False

json_dump(fp, **kwargs)

Write the particle’s json_dict to the fp file object using json.dump.

Parameters
json_dumps(**kwargs) str

Serialize the particle’s json_dict into a JSON formatted str using json.dumps.

Parameters

**kwargs – Any keyword accepted by json.dumps.

Returns

JSON formatted str.

Return type

str

recombine(n: Integral = 1, inplace=False)

Create a new Particle instance corresponding to the current Particle after undergoing recombination n times.

If inplace is False (default), then return the Particle that just underwent recombination. If inplace is True, then replace the current Particle with the Particle that just underwent recombination.

Parameters
Returns

particle – A new Particle object that has undergone recombination n times relative to the original Particle. If inplace is False, instead return None.

Return type

Particle

Raises

Examples

>>> Particle("Fe 6+").recombine()
Particle("Fe 5+")
>>> helium_particle = Particle("He-4 2+")
>>> helium_particle.recombine(n=2, inplace=True)
>>> helium_particle
Particle("He-4 0+")