Restructuring

[ppinard]

As part of issue #2 and the definition of SQL tables, here is a draft how to restructure the pyxray library.

Build

• One should be able to build the SQL database directly from pyxray.
• This entails that the data required should either be available as part of the pyxray source code or be downloaded from the internet.
• pyxray package should be distributed (e.g. on PyPi) with the most recent version of the SQL database, ready to be used.
• Building the SQL database should involve
  1. Download data from internet (optional)
  2. Parse data
  3. Cache parsed data (optional)
  4. Create SQL table if it does not already exists
  5. Populate SQL table with new entries if they do not already exist
• Note that separating the parsing step from the SQL related steps would allow to store the data in a different file format in the future

  Structure

• A data source is defined as: values extracted from a reference representing one or more properties associated to one or more descriptors. Some examples:
  • The Evaluated Atomic Data Library (reference) gives X-ray energies (property) for elements and X-ray transitions (descriptors).
  • The Siegbahn notation (property) for X-ray transitions (descriptor) taken from Jenkins et al. (1991) (reference)
• There are therefore two main categories of object: descriptors (a reference is also a descriptor) and properties

  Descriptors

Here are the descriptors required by pyxray and their definition:

• Element: Ground state of an atom where the number of protons equal the number of electrons
  • Atomic number (z)
• Atomic shell: Defined by the principal quantum number
  • Principal quantum number (n)
• Atomic subshell: Subdivision of atomic shells
  • Atomic shell
  • Azimuthal quantum number (l)
  • Total angular momentum (j)
• Transition: Relaxation process of an electron between quantum states leading to X-rays emission, Auger electrons or Coster-Kronig transitions
  • Source subshell
  • Destination subshell
  • Second destination subshell (for Auger)
• Set of transitions: For indistinguishable transition (e.g. Ka from Ka1/Ka2)
  • transitions
• Reference: Bibliographic reference
  • authors
  • year
  • journal
  • ...

There is a finite set for each descriptors (e.g. 118 elements, 7 atomic shells, etc.). From a programming point of view, the descriptors should therefore be:

• immutable: cannot be modified once created
• unique: Element(z=6) == Element(z=6) and Element(z=6) is Element(z=6)

  Properties

There is no limit on the number of properties that can be defined by combining descriptors. Some examples

• Energy of a transition of an element
• Symbol of an element
• Atomic weight of an element
• Notation of a transition represented in LaTeX
• Natural width of an atomic subshell of an element

In all cases, a reference descriptor should be provided to identify the source of the values.

Implementation

• Classes for each descriptor, respecting the definition and requirements mentioned above
• Methods for each property, taking descriptors as arguments, e.g.

def get_transition_energy_eV(element, transition, reference=None):
    ...
def get_element_symbol(element, reference=None):
    ...

• The methods are responsible to retrieve the values from the SQL database
• A set of default references for each property (when reference is None)

[ppinard]

Definition of the parser (here) and a few implementations (here) including the use of request_cache library to cache download from Wikipedia.