Particle¶
-
class
plasmapy.particles.particle_class.
Particle
(argument: Union[str, numbers.Integral, plasmapy.particles.particle_class.Particle, plasmapy.particles.particle_class.CustomParticle], mass_numb: Optional[numbers.Integral] = None, Z: Optional[numbers.Integral] = None)¶ Bases:
plasmapy.particles.particle_class.AbstractPhysicalParticle
A class for an individual particle or antiparticle.
- Parameters
argument (
ParticleLike
, excludingCustomParticle
instances) – A string representing a particle, element, isotope, or ion; an integer representing the atomic number of an element; or aParticle
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
orinteger_charge
attributes is being accessed but the charge information for the particle is not available.ParticleError – Raised for attempts at converting a
Particle
object to abool
.
See also
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
, andionic_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.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.
>>> ~positron Particle("e-")
A
Particle
instance may be used as the first argument toParticle
.>>> 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 theZ
andmass_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 withParticle
and/orParticleList
objects to return the nuclear reaction energy.>>> deuteron + triton > alpha + neutron <Quantity 2.81810898e-12 J>
The
categories
attribute andis_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'
.Instantiate a
Particle
object and set private attributes.Attributes Summary
Return the corresponding antiparticle, or raise an
ParticleError
if the particle is not an elementary particle.Return the number of protons in an element, isotope, or ion.
Return the number of baryons in a particle.
Return the nuclear binding energy in joules.
Return the particle’s categories.
Return the particle’s electron charge in coulombs.
Return the number of electrons in an ion.
Return the atomic symbol if the particle corresponds to an element, and
None
otherwise.Return the name of the element corresponding to this particle, or raise an
InvalidElementError
if the particle does not correspond to an element.Return the particle’s half-life in seconds, or a
str
with half-life information.Return the particle’s integer charge.
Return the ionic symbol if the particle corresponds to an ion or neutral atom, and
None
otherwise.Return
True
if the particle is an electron, andFalse
otherwise.Return the isotope symbol if the particle corresponds to an isotope, and
None
otherwise.Return the name of the element along with the isotope symbol if the particle corresponds to an isotope, and
None
otherwise.Return the isotopic abundance of an isotope.
A
json
friendly dictionary representation of the particle.Return
1
for leptons,-1
for antileptons, and0
otherwise.Return the mass of the particle in kilograms.
Return the mass energy of the particle in joules.
Return the number of nucleons in an isotope.
Return the number of neutrons in an isotope or nucleon.
Return the mass of the bare nucleus of an isotope or a neutron.
Return the symbol of the particle, atom, isotope, or ion.
Return a
namedtuple
to access category, period, group, and block information about an element.Return the spectral name of the particle (i.e.
Return the spin of the particle.
Return an element’s standard atomic weight in kg.
Return the symbol of the particle, atom, isotope, or ion.
Methods Summary
ionize
([n, inplace])Create a new
Particle
instance corresponding to the currentParticle
after being ionizedn
times.is_category
(*category_tuple[, require, …])Determine if the particle meets categorization criteria.
recombine
([n, inplace])Create a new
Particle
instance corresponding to the currentParticle
after undergoing recombinationn
times.Attributes Documentation
-
antiparticle
¶ Return the corresponding antiparticle, or raise an
ParticleError
if the particle is not an elementary particle.This attribute may be accessed by using the unary operator
~
acting on aParticle
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
MissingParticleDataError
.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 aMissingParticleDataWarning
.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, andFalse
otherwise.Examples
>>> Particle('e-').is_electron True >>> Particle('e+').is_electron False
-
is_ion
¶ Return
True
if the particle is an ion, andFalse
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 anInvalidIsotopeError
.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
MissingParticleDataError
. If the particle is not an isotope or is an ion of an isotope, then this attribute will raise anInvalidIsotopeError
.Examples
>>> D = Particle('deuterium') >>> D.isotopic_abundance 0.000115
-
json_dict
¶ A
json
friendly dictionary representation of the particle. (seeAbstractParticle.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, and0
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
MissingParticleDataError
.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
MissingParticleDataError
.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
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
¶ 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 aMissingParticleDataError
if the isotope mass is not available.Examples
>>> deuterium = Particle('D') >>> deuterium.nuclide_mass <Quantity 3.34358372e-27 kg>
-
particle
¶ Return the symbol of the particle, atom, isotope, or ion.
Deprecated since version 0.6.0:
Particle.particle
has been deprecated and will be removed in a subsequent release of PlasmaPy. UseParticle.symbol
instead.
-
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. RaiseChargeError
if no charge has been specified andOutOfRangeError
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
MissingParticleDataError
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
MissingParticleDataError
.Examples
>>> oxygen = Particle('O') >>> oxygen.standard_atomic_weight <Quantity 2.656696...e-26 kg>
-
symbol
¶ Return 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: numbers.Integral = 1, inplace: bool = False)¶ Create a new
Particle
instance corresponding to the currentParticle
after being ionizedn
times.If
inplace
isFalse
(default), then return the ionizedParticle
.If
inplace
isTrue
, then replace the currentParticle
with the newly ionizedParticle
.- Parameters
- Returns
particle – A new
Particle
object that has been ionizedn
times relative to the originalParticle
. Ifinplace
isFalse
, instead returnNone
.- Return type
- 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: 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, andFalse
otherwise.- Parameters
*category_tuple – Required categories in the form of one or more
str
objects or an iterable.require (
str
or iterable providingstr
objects, optional, keyword-only) – One or more categories. This method will returnFalse
if theParticle
does not belong to all of these categories.any_of (
str
or iterable providingstr
objects, optional, keyword-only) – One or more categories. This method will returnFalse
if theParticle
does not belong to at least one of these categories.exclude (
str
or iterable providingstr
objects, optional, keyword-only) – One or more categories. This method will returnFalse
if theParticle
belongs to any of these categories.
Notes
A
set
containing all valid categories may be accessed by thevalid_categories
attribute ofis_category
.Examples
Required categories may be entered as positional arguments, including as a
list
,set
, ortuple
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 theany_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 theexclude
keyword argument.>>> electron.is_category(exclude="baryon") True >>> electron.is_category(exclude={"lepton", "baryon"}) False
The
require
,any_of
, andexclude
keywords may be combined. If the particle matches all of the provided criteria, thenis_category
will returnTrue
.>>> electron.is_category( ... require="fermion", any_of={'lepton', 'baryon'}, exclude='charged', ... ) False
-
recombine
(n: numbers.Integral = 1, inplace=False)¶ Create a new
Particle
instance corresponding to the currentParticle
after undergoing recombinationn
times.If
inplace
isFalse
(default), then return theParticle
that just underwent recombination.If
inplace
isTrue
, then replace the currentParticle
with theParticle
that just underwent recombination.- Parameters
- Returns
particle – A new
Particle
object that has undergone recombinationn
times relative to the originalParticle
. Ifinplace
isFalse
, instead returnNone
.- Return type
- 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+")