\(\renewcommand\AA{\text{Å}}\)

# Core table

## `periodictable.core`

Core classes for the periodic table.

- `PeriodicTable`

    The periodic table with attributes for each element.

    Note

    PeriodicTable is not a singleton class. Use `periodictable.element` to access the common table.

- `Element`

    Element properties such as name, symbol, mass, density, etc.

- `Isotope`

    Isotope properties such as mass, density and neutron scattering factors.

- `Ion`

    Ion properties such as charge.

Elements are accessed from a periodic table using `table[number]`, `table.name` or `table.symbol` where symbol is the two letter symbol. Individual isotopes are accessed using `element[isotope]`. Individual ions are references using `element.ion[charge]`. Note that `element[isotope].ion[charge].mass` will depend on the particular charge since we subtract the charge times the rest mass of the electron from the overall mass.

Helper functions:

- `delayed_load()`

    Delay loading the element attributes until they are needed.

- `get_data_path()`

    Return the path to the periodic table data files.

- `define_elements()`

    Define external variables for each element in namespace.

- `isatom()`, `iselement()`, `isisotope()`, `ision()`

    Tests for different types of structure components.

- `default_table()`

    Returns the common periodic table.

- `change_table()`

    Return the same item from a different table.

See also

Adding properties for details on extending the periodic table with your own attributes.

Custom tables for details on managing your own periodic table with custom values for the attributes.

class periodictable.core.Element(name, symbol, Z, ions, table)

  Bases: `object`

  Periodic table entry for an element.

  An element is a name, symbol and number, plus a set of properties. Individual isotopes can be referenced as element[isotope_number]. Individual ionization states can be referenced by element.ion[charge].

  add_isotope(number)

    Add an isotope for the element.

    Parameters:
      number integer

        Isotope number, which is the number protons plus neutrons.

    Returns:

      None

  property K_alpha

    X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

  property K_alpha_units

    X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

  property K_beta1

    X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

  property K_beta1_units

    X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

  abundance_units = '%'
  charge = 0
  property covalent_radius

    covalent radius: average atomic radius when bonded to C, N or O.

  property covalent_radius_uncertainty

    covalent radius: average atomic radius when bonded to C, N or O.

  property covalent_radius_units

    covalent radius: average atomic radius when bonded to C, N or O.

  property crystal_structure

    Add crystal_structure property to the elements.

    Reference:

      Ashcroft and Mermin.

  property density

    Element density for natural abundance. For isotopes, return the equivalent density assuming identical inter-atomic spacing as the naturally occuring material.

    Parameters:
      iso_el isotope or element

        Name of the element or isotope.

    Returns:

      density : float | g·cm-3

    Reference:

      ILL Neutron Data Booklet, original values from CRC Handbook of Chemistry and Physics, 80th ed. (1999).

  density_units = 'g/cm^3'
  property interatomic_distance

    Estimated interatomic distance from atomic weight and density. The distance between isotopes is assumed to match that between atoms in the natural abundance.

    Parameters:
      element Element

        The element whose interatomic distance is to be calculated.

    Returns:
      distance float | Å

        Estimated interatomic distance.

    Interatomic distance is computed using:

    \[d = (m/(\rho_m N_A 10^{-24}))^{1/3}\]

    with units:

    \[(\rm (g\cdot mol^{-1}) / ( (g\cdot cm^{-3}) (atoms\cdot mol^{-1}) (10^{-8} cm\cdot \AA^{-1})^3))^{1/3} = \AA\]
  interatomic_distance_units = 'angstrom'
  property isotopes

    List of all isotopes

  property magnetic_ff

    Magnetic Form Fators. These values are directly from CrysFML.

    Reference:

      Brown. P. J.(Section 4.4.5) International Tables for Crystallography Volume C, Wilson. A.J.C.(ed).

  property mass

    Atomic weight.

    Parameters:

      isotope : Isotope

    Returns:
      mass float | u

        Atomic weight of the element.

    Reference:

      Coursey. J. S., Schwab. D. J, and Dragoset. R. A., NIST Atomic Weights and Isotopic Composition Database.

  mass_units = 'u'
  property neutron

    Neutron scattering factors, nuclear_spin and abundance properties for elements and isotopes.

    Reference:

      Rauch. H. and Waschkowski. W., ILL Nuetron Data Booklet.

  property number_density

    Estimate the number density from atomic weight and density. The density for isotopes is assumed to match that of between atoms in natural abundance.

    Parameters:
      element element

        Name of the element whose number density needs to be calculated.

    Returns:
      Nb float | cm-3

        Number density of a element.

    Number density is computed using:

    \[d = N_A \frac{\rho}{m}\]

    with units:

    \[\rm (atoms\cdot mol^{-1}) (g\cdot cm^{-3}) / (g\cdot mol^{-1}) = atoms\cdot cm^{-3}\]
  number_density_units = '1/cm^3'
  table = 'public'
  property xray

    X-ray scattering properties for the elements.

    Reference:

      Center for X-Ray optics. Henke. L., Gullikson. E. M., and Davis. J. C.

class periodictable.core.Ion(element, charge)

  Bases: `object`

  Periodic table entry for an individual ion.

  An ion is associated with an element. In addition to the element properties (symbol, name, atomic number), it has specific ion properties (charge). Properties not specific to the ion (i.e., charge) are retrieved from the associated element.

  property mass
  property xray

    X-ray scattering properties for the elements.

    Reference:

      Center for X-Ray optics. Henke. L., Gullikson. E. M., and Davis. J. C.

class periodictable.core.Isotope(element, isotope_number)

  Bases: `object`

  Periodic table entry for an individual isotope.

  An isotope is associated with an element. In addition to the element properties (symbol, name, atomic number), it has specific isotope properties (isotope number, nuclear spin, relative abundance). Properties not specific to the isotope (e.g., x-ray scattering factors) are retrieved from the associated element.

  property abundance

    Natural abundance.

    Parameters:

      isotope : Isotope

    Returns:

      abundance : float | %

    Reference:

      Coursey. J. S., Schwab. D. J, and Dragoset. R. A., NIST Atomic Weights and Isotopic Composition Database.

  property density

    Element density for natural abundance. For isotopes, return the equivalent density assuming identical inter-atomic spacing as the naturally occuring material.

    Parameters:
      iso_el isotope or element

        Name of the element or isotope.

    Returns:

      density : float | g·cm-3

    Reference:

      ILL Neutron Data Booklet, original values from CRC Handbook of Chemistry and Physics, 80th ed. (1999).

  property mass

    Atomic weight.

    Parameters:

      isotope : Isotope

    Returns:
      mass float | u

        Atomic weight of the element.

    Reference:

      Coursey. J. S., Schwab. D. J, and Dragoset. R. A., NIST Atomic Weights and Isotopic Composition Database.

  property neutron

    Neutron scattering factors, nuclear_spin and abundance properties for elements and isotopes.

    Reference:

      Rauch. H. and Waschkowski. W., ILL Nuetron Data Booklet.

  property neutron_activation

    Neutron activation calculations for isotopes and formulas.

    Reference:

      IAEA 273: Handbook on Nuclear Activation Data. NBSIR 85-3151: Compendium of Benchmark Neutron Field.

class periodictable.core.PeriodicTable(table: str)

  Bases: `object`

  Defines the periodic table of the elements with isotopes. Individidual elements are accessed by name, symbol or atomic number. Individual isotopes are addressable by `element[mass_number]` or `elements.isotope(element name)`, `elements.isotope(element symbol)`.

  For example, the following all retrieve iron:

      >>> from periodictable import *
      >>> print(elements[26])
      Fe
      >>> print(elements.Fe)
      Fe
      >>> print(elements.symbol('Fe'))
      Fe
      >>> print(elements.name('iron'))
      Fe
      >>> print(elements.isotope('Fe'))
      Fe

  To get iron-56, use:

      >>> print(elements[26][56])
      56-Fe
      >>> print(elements.Fe[56])
      56-Fe
      >>> print(elements.isotope('56-Fe'))
      56-Fe

  Deuterium and tritium are defined as ‘D’ and ‘T’. Some neutron properties are available in `elements[0]`.

  To show all the elements in the table, use the iterator:

      >>> from periodictable import *
      >>> for el in elements:  # lists the element symbols
      ...     print("%s %s"%(el.symbol, el.name))
      n neutron
      H hydrogen
      He helium
      ...
      Og oganesson

  Note

  Properties can be added to the elements as needed, including mass, nuclear and X-ray scattering cross sections. See section Adding properties for details.

  isotope(input)

    Lookup the element or isotope in the periodic table. Elements are assumed to be given by the standard element symbols. Isotopes are given by number-symbol, or ‘D’ and ‘T’ for 2-H and 3-H.

    Parameters:
      input string

        Element name or isotope to be looked up in periodictable.

    Returns:

      Element

    Raises:

      ValueError if element or isotope is not defined.

    For example, print the element corresponding to ‘58-Ni’.

        >>> import periodictable
        >>> print(periodictable.elements.isotope('58-Ni'))
        58-Ni

  list(*props, **kw)

    Print a list of elements with the given set of properties.

    Parameters:
      prop1, prop2, …string

        Name of the properties to print

      format: string

        Template for displaying the element properties, with one % for each property.

    Returns:

      None

    For example, print a table of mass and density.

        >>> from periodictable import elements
        >>> elements.list('symbol', 'mass', 'density',
        ...     format="%-2s: %6.2f u %5.2f g/cm^3")
        H :   1.01 u   0.07 g/cm^3
        He:   4.00 u   0.12 g/cm^3
        Li:   6.94 u   0.53 g/cm^3
        ...
        Bk: 247.00 u  14.00 g/cm^3

  name(input)

    Lookup an element given its name.

    Parameters:
      input string

        Element name to be looked up in periodictable.

    Returns:

      Element

    Raises:

      ValueError if element does not exist.

    For example, print the element corresponding to ‘iron’:

        >>> import periodictable
        >>> print(periodictable.elements.name('iron'))
        Fe

  symbol(input)

    Lookup the an element in the periodic table using its symbol. Symbols are included for ‘D’ and ‘T’, deuterium and tritium.

    Parameters:
      input string

        Element symbol to be looked up in periodictable.

    Returns:

      Element

    Raises:

      ValueError if the element symbol is not defined.

    For example, print the element corresponding to ‘Fe’:

        >>> import periodictable
        >>> print(periodictable.elements.symbol('Fe'))
        Fe

periodictable.core.change_table(atom, table)

  Search for the same element, isotope or ion from a different table

periodictable.core.default_table(table=None)

  Return the default table unless a specific table has been requested.

  This is to be used in a context like:

      def summary(table=None):
          table = core.default_table(table)
          ...

periodictable.core.define_elements(table, namespace)

  Define external variables for each element in namespace. Elements are defined both by name and by symbol.

  This is called from __init__ as:

      elements = core.default_table()
      __all__  += core.define_elements(elements, globals())

  Parameters:
    table PeriodicTable

      Set of elements

    namespace dict

      Namespace in which to add the symbols.

  Returns:

    [string, …] A sequence listing the names defined.

  Note

  This will only work for namespace globals(), not locals()!

periodictable.core.delayed_load(all_props, loader, element=True, isotope=False, ion=False)

  Delayed loading of an element property table. When any of property is first accessed the loader will be called to load the associated data. The help string starts out as the help string for the loader function. The attribute may be associated with any of `Isotope`, `Ion`, or `Element`. Some properties, such as `mass`, have both an isotope property for the mass of specific isotopes, as well as an element property for the mass of the collection of isotopes at natural abundance. Set the keyword flags element, isotope and/or ion to specify which of these classes will be assigned specific information on load.

periodictable.core.get_data_path(data)

  Locate the directory for the tables for the named extension.

  Parameters:
    data string

      Name of the extension data directory. For example, the xsf extension has data in the ‘xsf’ data directory.

  Returns:

    string Path to the data.

periodictable.core.isatom(val)

  Return true if value is an element, isotope or ion

periodictable.core.iselement(val)

  Return true if value is an element or ion in natural abundance

periodictable.core.ision(val)

  Return true if value is a specific ion of an element or isotope

periodictable.core.isisotope(val)

  Return true if value is an isotope or isotope ion.