Particle¶
-
class
plasmapy.particles.
Particle
(argument: Union[str, numbers.Integral], mass_numb: numbers.Integral = None, Z: numbers.Integral = None)¶ Bases:
plasmapy.particles.particle_class.AbstractParticle
A class for an individual particle or antiparticle.
Parameters: - argument (
str
,int
, orParticle
) – 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 thecharge
orinteger_charge
attributes is being accessed but the charge information for the particle is not available.AtomicError
– Raised for attempts at converting aParticle
object to abool
.
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
, andionic_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 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")
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'
.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, andFalse
otherwise.is_ion
Return True
if the particle is an ion, andFalse
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, and0
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 currentParticle
after being ionizedn
times.is_category
(*category_tuple, require, …)Determine if the particle meets categorization criteria. json_dump
(fp, **kwargs)Writes the particle’s json_dict
to thefp
file object usingjson.dump
.json_dumps
(**kwargs)Serialize the particle’s json_dict
into a JSON formattedstr
usingjson.dumps
.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
AtomicError
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
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 aMissingAtomicDataWarning
.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
MissingAtomicDataError
. 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
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 aMissingAtomicDataError
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. 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
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 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 theParticle
is not an element.ChargeError
– If no charge information for theParticle
object is specified.InvalidIonError
– If there are less thann
remaining bound electrons.ValueError
– Ifn
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, andFalse
the particle is not.Required categories may be entered as positional arguments, including as a
list
,set
, ortuple
of required categories. These may also be included using therequire
keyword argument. This method will returnFalse
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 returnFalse
if the particle is not of any of the categories inany_of
.If the
exclude
keyword is set, then this method will returnFalse
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 thefp
file object usingjson.dump
.Parameters: - fp (file object) – Destination file object to write the JSON serialized
json_dict
. - **kwargs – Any keyword accepted by
json.dump
.
- fp (file object) – Destination file object to write the JSON serialized
-
json_dumps
(**kwargs) → str¶ Serialize the particle’s
json_dict
into a JSON formattedstr
usingjson.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 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 theParticle
is not an element.ChargeError
– If no charge information for theParticle
object is specified.ValueError
– Ifn
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+")
- argument (