Particle¶

class plasmapy.particles.Particle(argument: Union[str, numbers.Integral], mass_numb: numbers.Integral = None, Z: numbers.Integral = None)¶

Bases: plasmapy.particles.AbstractParticle

A class for an individual particle or antiparticle.

Parameters:

argument (str, int, or Particle) – A string representing a particle, element, isotope, or ion; an integer representing the atomic number of an element; or a Particle instance.
mass_numb (int, optional) – The mass number of an isotope or nuclide.
Z (int, optional) – The integer charge of the particle.

Raises:

TypeError – For when any of the arguments or keywords is not of the required type.
InvalidParticleError – Raised when the particle input does not correspond to a valid particle or is contradictory.
InvalidElementError – For when an attribute is being accessed that requires information about an element, but the particle is not an element, isotope, or ion.
InvalidIsotopeError – For when an attribute is being accessed that requires information about an isotope or nuclide, but the particle is not an isotope (or an ion of an isotope).
ChargeError – For when either the charge or integer_charge attributes is being accessed but the charge information for the particle is not available.
AtomicError – Raised for attempts at converting a Particle object to a bool.

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)
>>> alpha = Particle('He', mass_numb=4, Z=2)
>>> positron = Particle('positron')
>>> hydrogen = Particle(1)  # atomic number

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

>>> positron.particle
'e+'

The element, isotope, and ionic_symbol attributes return 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 return 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 return physical properties of a particle.

>>> electron.integer_charge
-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.

>>> ~electron
Particle("e+")
>>> ~proton
Particle("p-")
>>> ~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")

The categories attribute and is_category method may be used to find and test particle membership in categories.

Valid particle categories include: 'actinide', 'alkali metal', 'alkaline earth metal', 'antibaryon', 'antilepton', 'antimatter', 'antineutrino', 'baryon', 'boson', 'charged', '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'.

Attributes Summary

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

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)	Writes 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¶

Return the corresponding antiparticle, or raise an AtomicError if the particle is not an elementary particle.

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

Examples

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

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

atomic_number¶

Return the number of protons in an element, isotope, or ion.

If the particle is not an element, then this attribute will raise an InvalidElementError.

Examples

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

baryon_number¶

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

If the baryon number is unavailable, then this attribute will raise a MissingAtomicDataError.

Examples

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

binding_energy¶

Return the nuclear binding energy in joules.

This attribute will raise an 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¶

Return the particle’s categories.

Examples

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

charge¶

Return the particle’s electron charge in coulombs.

This attribute will raise a ChargeError if the charge has not been specified.

Examples

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

electron_number¶

Return the number of electrons in an ion.

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

If this particle is not an ion or electron, then this attribute will raise an InvalidIonError.

Examples

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

element¶

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

Examples

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

element_name¶

Return the name of the element corresponding to this particle, or raise an InvalidElementError if the particle does not correspond to an element.

Examples

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

half_life¶

Return 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 MissingAtomicDataWarning.

Examples

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

integer_charge¶

Return the particle’s integer charge.

This attribute will raise a ChargeError if the charge has not been specified.

Examples

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

ionic_symbol¶

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

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

Examples

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

is_ion¶

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

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

Examples

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

isotope_name¶

Return the name of the element along with the isotope symbol if the particle corresponds to an isotope, and None otherwise.

If the particle is not a valid element, then this attribute will raise an InvalidElementError. If it is not an isotope, then this attribute will raise an InvalidIsotopeError.

Examples

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

isotopic_abundance¶

Return the isotopic abundance of an isotope.

If the isotopic abundance is not available, this attribute will raise a MissingAtomicDataError. If the particle is not an isotope or is an ion of an isotope, then this attribute will raise an InvalidIsotopeError.

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')
>>> lead.json_dict
{'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¶

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

If the lepton number is unavailable, then this attribute will raise a MissingAtomicDataError.

Examples

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

mass¶

Return 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 integer charge and the electron mass.

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

If the mass is unavailable (e.g., for neutrinos or elements with no standard atomic weight), then this attribute will raise a MissingAtomicDataError.

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¶

Return 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 MissingAtomicDataError.

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¶

Return the number of nucleons in an isotope.

This attribute will return the number of protons plus the number of neutrons in an isotope or nuclide.

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

Examples

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

neutron_number¶

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

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

This attribute will raise a InvalidIsotopeError if the particle is not an isotope or neutron, or a MissingAtomicDataError if the isotope mass is not available.

Examples

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

particle¶

Return the particle’s symbol.

Examples

>>> electron = Particle('electron')
>>> electron.particle
'e-'

periodic_table¶

Return a namedtuple to access category, period, group, and block information about an element.

If the particle is not an element, isotope, or ion, then this attribute will raise an InvalidElementError.

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¶

Return 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 integer charge. 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¶

Return the spin of the particle.

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

Examples

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

standard_atomic_weight¶

Return an element’s standard atomic weight in kg.

If the particle is isotope or ion or not an element, this attribute will raise an InvalidElementError.

If the element does not have a defined standard atomic weight, this attribute will raise a MissingAtomicDataError.

Examples

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

Methods Documentation

ionize(n: numbers.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.

Parameters:	n (positive integer) – The number of bound electrons to remove from the `Particle` object. Defaults to `1`. inplace (bool, optional) – If `True`, then replace the current `Particle` instance with the newly ionized `Particle`.
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:	`InvalidElementError` – If the `Particle` is not an element. `ChargeError` – If no charge information for the `Particle` object is specified. `InvalidIonError` – If there are less than `n` remaining bound electrons. `ValueError` – If `n` is not positive.

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+")

is_category(*category_tuple, require: Union[str, Set[T], Tuple, List[T]] = None, any_of: Union[str, Set[T], Tuple, List[T]] = None, exclude: Union[str, Set[T], Tuple, List[T]] = None) → bool¶

Determine if the particle meets categorization criteria.

Return True if the particle is in all of the inputted categories, and False the particle is not.

Required categories may be entered as positional arguments, including as a list, set, or tuple of required categories. These may also be included using the require keyword argument. This method will return False if the particle is not in all of the required categories.

If categories are inputted using the any_of keyword argument, then this method will return False if the particle is not of any of the categories in any_of.

If the exclude keyword is set, then this method will return False if the particle is in any of the excluded categories, whether or not the particle matches the other criteria.

Examples

>>> Particle('e-').is_category('lepton')
True
>>> Particle('p+').is_category('baryon', exclude='charged')
False
>>> Particle('n').is_category({'matter', 'baryon'}, exclude={'charged'})
True
>>> Particle('mu+').is_category('antilepton', exclude='baryon')
True

json_dump(fp, **kwargs)¶

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

Parameters:	fp (file object) – Destination file object to write the JSON serialized `json_dict`. **kwargs – Any keyword accepted by `json.dump`.

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: numbers.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:	n (positive integer) – The number of electrons to recombine into the `Particle` object. inplace (bool, optional) – If `True`, then replace the current `Particle` instance with the `Particle` that just underwent recombination.
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:	`InvalidElementError` – If the `Particle` is not an element. `ChargeError` – If no charge information for the `Particle` object is specified. `ValueError` – If `n` is not positive.

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+")