def periodic_table_group(argument: Union[str, Integral]) -> Integral:
"""
Return the periodic table group.
Parameters
----------
argument: `str` or `int`
Atomic number (either integer or string), atomic symbol (e.g.,
``"H"``, string), or element name (e.g., ``"francium"``,
string).
Returns
-------
group: `int`
The periodic table group of the element.
Raises
------
`TypeError`
If the argument is not a `str` or `int`.
See Also
--------
`~plasmapy.particles.periodic_table_period` : returns periodic table
period of element.
`~plasmapy.particles.periodic_table_block` : returns periodic table
block of element.
`~plasmapy.particles.periodic_table_category` : returns periodic table
category of element.
Examples
--------
>>> periodic_table_group(18)
18
>>> periodic_table_group(24)
6
>>> periodic_table_group("Al")
13
>>> periodic_table_group("neon")
18
>>> periodic_table_group("barium")
2
"""
# TODO: Implement @particle_input
if not isinstance(argument, (str, Integral)):
raise TypeError(
"The argument to periodic_table_group must be "
"either a string representing the element or its "
"symbol, or an integer representing its atomic number.")
symbol = atomic_symbol(argument)
group = _Elements[symbol]["group"]
return group
def periodic_table_block(argument: Union[str, Integral]) -> str:
"""
Return the periodic table block.
Parameters
----------
argument: `str` or `int`
Atomic number (either integer or string), atomic symbol (e.g.,
``"H"``, string), or element name (e.g., ``"francium"``,
string).
Returns
-------
block: `str`
The periodic table block of the element.
Raises
------
`TypeError`
If the argument is not a `str` or `int`.
See Also
--------
`~plasmapy.particles.periodic_table_period` : returns periodic table
period of element.
`~plasmapy.particles.periodic_table_group` : returns periodic table
group of element.
`~plasmapy.particles.periodic_table_category` : returns periodic table
category of element.
Examples
--------
>>> periodic_table_block(66)
'f'
>>> periodic_table_block(72)
'd'
>>> periodic_table_block("Tl")
'p'
>>> periodic_table_block("thallium")
'p'
>>> periodic_table_block("francium")
's'
"""
# TODO: Implement @particle_input
if not isinstance(argument, (str, Integral)):
raise TypeError(
"The argument to periodic_table_block must be "
"either a string representing the element or its "
"symbol, or an integer representing its atomic number.")
symbol = atomic_symbol(argument)
block = _Elements[symbol]["block"]
return block
def periodic_table_category(argument: Union[str, Integral]) -> str:
"""
Return the periodic table category.
Parameters
----------
argument: `str` or `int`
Atomic number (either integer or string), atomic symbol (e.g.,
``"H"``, string), or element name (e.g., ``"francium"``,
string).
Returns
-------
category: `str`
The periodic table category of the element.
Raises
------
`TypeError`
If the argument is not a `str` or `int`.
See Also
--------
`~plasmapy.particles.periodic_table_period` : returns periodic table
period of element.
`~plasmapy.particles.periodic_table_group` : returns periodic table
group of element.
`~plasmapy.particles.periodic_table_block` : returns periodic table
block of element.
Examples
--------
>>> periodic_table_category(82)
'post-transition metal'
>>> periodic_table_category("85")
'halogen'
>>> periodic_table_category("Ra")
'alkaline earth metal'
>>> periodic_table_category("rhodium")
'transition metal'
"""
# TODO: Implement @particle_input
if not isinstance(argument, (str, Integral)):
raise TypeError(
"The argument to periodic_table_category must be "
"either a string representing the element or its "
"symbol, or an integer representing its atomic number.")
symbol = atomic_symbol(argument)
category = _Elements[symbol]["category"]
return category
def periodic_table_period(argument: Union[str, Integral]) -> Integral:
"""
Return the periodic table period.
Parameters
----------
argument: `str` or `int`
Atomic number (either integer or string), atomic symbol (e.g.,
``"H"``, string), or element name (e.g. ``"Francium"``, string).
Returns
-------
period: `int`
The periodic table period of the element.
Raises
------
`TypeError`
If the argument is not a `str` or `int`.
See Also
--------
`~plasmapy.particles.periodic_table_group` : returns periodic table
group of element.
`~plasmapy.particles.periodic_table_block` : returns periodic table
block of element.
Examples
--------
>>> periodic_table_period(5)
2
>>> periodic_table_period("5")
2
>>> periodic_table_period("Au")
6
>>> periodic_table_period("nitrogen")
2
"""
# TODO: Implement @particle_input
if not isinstance(argument, (str, Integral)):
raise TypeError(
"The argument to periodic_table_period must be either a "
"string representing the element or its symbol, or an "
"integer representing its atomic number.")
symbol = atomic_symbol(argument)
period = _Elements[symbol]["period"]
return period
def known_isotopes_for_element(argument):
element = atomic_symbol(argument)
isotopes = []
for isotope in _isotopes.keys():
if element + "-" in isotope and isotope[0:len(element)] == element:
isotopes.append(isotope)
if element == "H":
isotopes.insert(1, "D")
isotopes.insert(2, "T")
mass_numbers = [mass_number(isotope) for isotope in isotopes]
sorted_isotopes = [
mass_number
for (isotope, mass_number) in sorted(zip(mass_numbers, isotopes))
]
return sorted_isotopes
def known_isotopes_for_element(argument):
element = atomic_symbol(argument)
isotopes = [
isotope for isotope in _isotopes.data_about_isotopes
if f"{element}-" in isotope and isotope[:len(element)] == element
]
if element == "H":
isotopes.insert(1, "D")
isotopes.insert(2, "T")
mass_numbers = [mass_number(isotope) for isotope in isotopes]
return [
mass_number
for (isotope, mass_number) in sorted(zip(mass_numbers, isotopes))
]
def stable_isotopes(argument: Union[str, Integral] = None,
unstable: bool = False) -> List[str]:
"""
Return a list of all stable isotopes of an element, or if no input is
provided, a list of all such isotopes for every element.
Parameters
----------
argument: `int` or `str`
A string or integer representing an atomic number or element,
or a string representing an isotope.
unstable: `bool`
If set to `True`, this function will return a list of the
unstable isotopes instead of the stable isotopes.
Returns
-------
StableIsotopes: `list` of strings or empty list
List of all stable isotopes of an element, sorted from lowest
mass number. If an element has no stable isotopes, this
function returns an empty list.
Raises
------
`~plasmapy.particles.exceptions.InvalidElementError`
If the argument is a valid particle but not a valid element.
`~plasmapy.particles.exceptions.InvalidParticleError`
If the argument does not correspond to a valid particle.
`TypeError`
If the argument is not a string or integer.
Notes
-----
There are 254 isotopes for which no radioactive decay has been
observed. It is possible that some isotopes will be discovered to
be unstable but with extremely long half-lives. For example,
bismuth-209 was recently discovered to have a half-life of about
1.9e19 years. However, such isotopes can be regarded as virtually
stable for most applications.
See Also
--------
known_isotopes : returns a list of isotopes that have been discovered.
common_isotopes : returns isotopes with non-zero isotopic abundances.
Examples
--------
>>> stable_isotopes('H')
['H-1', 'D']
>>> stable_isotopes(44)
['Ru-96', 'Ru-98', 'Ru-99', 'Ru-100', 'Ru-101', 'Ru-102', 'Ru-104']
>>> stable_isotopes('beryllium')
['Be-9']
>>> stable_isotopes('Pb-209')
['Pb-204', 'Pb-206', 'Pb-207', 'Pb-208']
>>> stable_isotopes(118)
[]
Find unstable isotopes using the ``unstable`` keyword.
>>> stable_isotopes('U', unstable=True)[:5] # only first five
['U-217', 'U-218', 'U-219', 'U-220', 'U-221']
"""
# TODO: Allow Particle objects representing elements to be inputs
def stable_isotopes_for_element(argument: Union[str, int],
stable_only: Optional[bool]) -> List[str]:
KnownIsotopes = known_isotopes(argument)
StableIsotopes = [
isotope for isotope in KnownIsotopes
if _isotopes[isotope]["stable"] == stable_only
]
return StableIsotopes
if argument is not None:
try:
element = atomic_symbol(argument)
isotopes_list = stable_isotopes_for_element(element, not unstable)
except InvalidParticleError:
raise InvalidParticleError("Invalid particle in stable_isotopes")
except InvalidElementError:
raise InvalidElementError(
"stable_isotopes is unable to get isotopes "
f"from an input of: {argument}")
elif argument is None:
isotopes_list = []
for atomic_numb in range(1, 119):
isotopes_list += stable_isotopes_for_element(
atomic_numb, not unstable)
return isotopes_list
def common_isotopes(argument: Union[str, Integral] = None,
most_common_only: bool = False) -> List[str]:
"""
Return a list of isotopes of an element with an isotopic abundances
greater than zero, or if no input is provided, a list of all such
isotopes for every element.
Parameters
----------
argument: `int` or `str`, optional
A string or integer representing an atomic number or element,
or a string representing an isotope.
most_common_only: `bool`
If set to `True`, return only the most common isotope.
Returns
-------
isotopes_list: `list` of `str` or empty `list`
List of all isotopes of an element with isotopic abundances
greater than zero, sorted from most abundant to least
abundant. If no isotopes have isotopic abundances greater
than zero, this function will return an empty list. If no
arguments are provided, then a list of all common isotopes of
all elements will be provided that is sorted by atomic number,
with entries for each element sorted from most abundant to
least abundant.
Raises
------
`~plasmapy.particles.exceptions.InvalidElementError`
If the argument is a valid particle but not a valid element.
`~plasmapy.particles.exceptions.InvalidParticleError`
If the argument does not correspond to a valid particle.
`TypeError`
If the argument is not a string or integer.
Notes
-----
The isotopic abundances are based on the terrestrial environment
and may not be appropriate for space and astrophysical applications.
See Also
--------
known_isotopes : returns a list of isotopes that have been discovered.
stable_isotopes : returns isotopes that are stable against radioactive decay.
isotopic_abundance : returns the relative isotopic abundance.
Examples
--------
>>> common_isotopes('H')
['H-1', 'D']
>>> common_isotopes(44)
['Ru-102', 'Ru-104', 'Ru-101', 'Ru-99', 'Ru-100', 'Ru-96', 'Ru-98']
>>> common_isotopes('beryllium 2+')
['Be-9']
>>> common_isotopes('Fe')
['Fe-56', 'Fe-54', 'Fe-57', 'Fe-58']
>>> common_isotopes('Fe', most_common_only=True)
['Fe-56']
>>> common_isotopes()[0:7]
['H-1', 'D', 'He-4', 'He-3', 'Li-7', 'Li-6', 'Be-9']
"""
# TODO: Allow Particle objects representing elements to be inputs
def common_isotopes_for_element(
argument: Union[str, int],
most_common_only: Optional[bool]) -> List[str]:
isotopes = known_isotopes(argument)
CommonIsotopes = [
isotope for isotope in isotopes
if "abundance" in _isotopes[isotope].keys()
]
isotopic_abundances = [
_isotopes[isotope]["abundance"] for isotope in CommonIsotopes
]
sorted_isotopes = [
iso_comp
for (isotope,
iso_comp) in sorted(zip(isotopic_abundances, CommonIsotopes))
]
sorted_isotopes.reverse()
if most_common_only and len(sorted_isotopes) > 1:
sorted_isotopes = sorted_isotopes[0:1]
return sorted_isotopes
if argument is not None:
try:
element = atomic_symbol(argument)
isotopes_list = common_isotopes_for_element(
element, most_common_only)
except InvalidParticleError:
raise InvalidParticleError("Invalid particle")
except InvalidElementError:
raise InvalidElementError(
"common_isotopes is unable to get isotopes "
f"from an input of: {argument}")
elif argument is None:
isotopes_list = []
for atomic_numb in range(1, 119):
isotopes_list += common_isotopes_for_element(
atomic_numb, most_common_only)
return isotopes_list
def known_isotopes(argument: Union[str, Integral] = None) -> List[str]:
"""
Return a list of all known isotopes of an element, or a list of all
known isotopes of every element if no input is provided.
Parameters
----------
argument: `int` or `str`, optional
A string representing an element, isotope, or ion or an
integer representing an atomic number
Returns
-------
isotopes_list: `list` containing `str` items or an empty `list`
List of all of the isotopes of an element that have been
discovered, sorted from lowest mass number to highest mass
number. If no argument is provided, then a list of all known
isotopes of every element will be returned that is sorted by
atomic number, with entries for each element sorted by mass
number.
Raises
------
`~plasmapy.particles.exceptions.InvalidElementError`
If the argument is a valid particle but not a valid element.
`~plasmapy.particles.exceptions.InvalidParticleError`
If the argument does not correspond to a valid particle.
`TypeError`
If the argument is not a `str` or `int`.
Notes
-----
This list returns both natural and artificially produced isotopes.
See Also
--------
common_isotopes : returns isotopes with non-zero isotopic abundances.
stable_isotopes : returns isotopes that are stable against radioactive decay.
Examples
--------
>>> known_isotopes('H')
['H-1', 'D', 'T', 'H-4', 'H-5', 'H-6', 'H-7']
>>> known_isotopes('helium 1+')
['He-3', 'He-4', 'He-5', 'He-6', 'He-7', 'He-8', 'He-9', 'He-10']
>>> known_isotopes()[0:10]
['H-1', 'D', 'T', 'H-4', 'H-5', 'H-6', 'H-7', 'He-3', 'He-4', 'He-5']
>>> len(known_isotopes()) # the number of known isotopes
3352
"""
# TODO: Allow Particle objects representing elements to be inputs
def known_isotopes_for_element(argument):
element = atomic_symbol(argument)
isotopes = []
for isotope in _isotopes.keys():
if element + "-" in isotope and isotope[0:len(element)] == element:
isotopes.append(isotope)
if element == "H":
isotopes.insert(1, "D")
isotopes.insert(2, "T")
mass_numbers = [mass_number(isotope) for isotope in isotopes]
sorted_isotopes = [
mass_number
for (isotope, mass_number) in sorted(zip(mass_numbers, isotopes))
]
return sorted_isotopes
if argument is not None:
try:
element = atomic_symbol(argument)
isotopes_list = known_isotopes_for_element(element)
except InvalidElementError:
raise InvalidElementError("known_isotopes is unable to get "
f"isotopes from an input of: {argument}")
except InvalidParticleError:
raise InvalidParticleError("Invalid particle in known_isotopes.")
elif argument is None:
isotopes_list = []
for atomic_numb in range(1, len(_elements.keys()) + 1):
isotopes_list += known_isotopes_for_element(atomic_numb)
return isotopes_list