pyxray contains three main types of data:

• element properties (atomic number, symbol, English name, atomic weight, mass density)
• atomic subshells (existence, energy and natural width)
• X-ray transitions (existence, energy, IUPAC and Siegbahn nomenclature)

As these data can come from different sources, especially for numerical values (e.g. X-ray transition energy), pyxray should be able to accommodate for this reality within its implementation. It should also be extendable to include other types of data in the future.

The current version of pyxray retrieves the data from hard coded values and CSV files. This has the following limitations:

• All data must be read and kept in memory
• Requires the specification of arbitrary indexes for the X-ray transition and subshells
• New sources requires a new file to be generated or modification of the existing tables

After looking at other file formats such as HDF5, the tasks required by pyxray can be addressed by a sqlite database and object relational mapping by the Python library SQLAlchemy. It has the following advantages:

• information is structured in well-defined table
• values can be retrieved using specific queries
• supports multiple entries for different sources
• all data to be kept in a single file
• sqlite is available in the Python standard library
• sqlite has implementations in other programming languages

The development of this refactoring is done in the branch sql.

I cannot build the database in developer mode after the commit 2d4f8f2 on a windows 10 computer with Python 3.6 (64-bit). This is the output I obtained

$ python setup.py build
running build
running build_py
No SQL database found
Building database: 0it [00:00, ?it/s]

I found "No SQL database found" in the data.py and it seem when this file is imported, it did not find the database and use the _EmptyDatabase and did not build the missing database later. I am not sure where to create the SQL database file (data/pyxray.db)

Thanks Hendrix

Referring to issue #2, this issue is to populate the SQL database with atomic weight. Ideally, this should be done automatically from an available online resource.

The most official tabulation of atomic weight appears to come from the CIAAW. Unfortunately, their website does not directly provide an ASCII table of the values. NIST has an online database of atomic weight and isotopes which can be generated as an ASCII file (website, results). The information appears to come from the CIAAW/IUPAC.

The goal would therefore to write a parser to extract the atomic weight from the NIST output. I would proceed as follows:

1. Use the Python library requests to download the NIST ASCII output
2. Parse each isotope, storing their Atomic Number, Relative Atomic Mass and Isotopic Composition
3. For each atomic number, multiply the relative atomic mass by the isotopic composition and sum over all isotopes.
4. Add values to the SQL database using the ElementAtomicWeightProperty model (see populate_element_symbol_table(engine) in pyxray/sql/default.py as an example)
5. Write some unit tests to compare the values with those appearing in the NIST periodic table

The code should go in a new function populate_element_atomic_weight_table_(engine) in pyxray/sql/default.py.

It would be practical to have a database of mass density for common minerals and alloys.

PyPika is a SQL command builder. It could replace the custom SQL command builder of pyxray.

For some functions and set of parameters, multiple references exist. The proposal is to add a all keyword parameter to the functions which if True (default is False) will return a list of properties, which may include properties for several references.

Building the database fails if requests package is not installed. Is it intended that it's not part of the requirements?

(env_auto) [vm-user@localhost pyxray]$ python setup.py build
running build
running build_py
Traceback (most recent call last):
  File "setup.py", line 89, in <module>
    entry_points=ENTRY_POINTS,
  File "/home/vm-user/Workspace/pymontecarlo_test/env_auto/lib64/python3.6/site-packages/setuptools/__init__.py", line 129, in setup
    return distutils.core.setup(**attrs)
  File "/usr/lib64/python3.6/distutils/core.py", line 148, in setup
    dist.run_commands()
  File "/usr/lib64/python3.6/distutils/dist.py", line 955, in run_commands
    self.run_command(cmd)
  File "/usr/lib64/python3.6/distutils/dist.py", line 974, in run_command
    cmd_obj.run()
  File "/usr/lib64/python3.6/distutils/command/build.py", line 135, in run
    self.run_command(cmd_name)
  File "/usr/lib64/python3.6/distutils/cmd.py", line 313, in run_command
    self.distribution.run_command(command)
  File "/usr/lib64/python3.6/distutils/dist.py", line 974, in run_command
    cmd_obj.run()
  File "setup.py", line 22, in run
    builder.build()
  File "/home/vm-user/Workspace/pymontecarlo_test/pyxray/pyxray/sql/build.py", line 98, in build
    parsers = self._find_parsers()
  File "/home/vm-user/Workspace/pymontecarlo_test/pyxray/pyxray/sql/build.py", line 74, in _find_parsers
    return find_parsers()
  File "/home/vm-user/Workspace/pymontecarlo_test/pyxray/pyxray/parser/parser.py", line 40, in find_parsers
    parser = entry_point.load()
  File "/home/vm-user/Workspace/pymontecarlo_test/env_auto/lib64/python3.6/site-packages/pkg_resources/__init__.py", line 2408, in load
    return self.resolve()
  File "/home/vm-user/Workspace/pymontecarlo_test/env_auto/lib64/python3.6/site-packages/pkg_resources/__init__.py", line 2414, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "/home/vm-user/Workspace/pymontecarlo_test/pyxray/pyxray/parser/nist.py", line 12, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

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)

@fingenerf wrote:

With the pyXRAY module it is possible to get a lot of information about elements, their subshells and transitions. To use these information for example for a digital periodic table it would probably be a good idea to create some kind of an element exchange class to parse all the information about one specific element in one object. This class could not just be used for the periodic table, it could be used in other modules as well.

This class would contain all the element information like the name, the weight and the density, all the information for each subshell of this element like the binding energy and radiative width and it would contain the information for each transition of this element like the transition
energy.

What we're looking for is a exchange format for pyXRAY and applications of any kind. We would like to introduce a class on element level that collects all information about an element (or at least all information from one source).

@ppinard: What do you think about that idea? Do you already plan something similar?

Much of the logic in pyxray/sql/data.py is performed using Python code. I think it could be simplified using SQL language directly and INNER JOIN.

The Livermore EADL provides fractional subshell occupancies for some elements. For example, Boron has L_2 and L_3 subshells with 0.33 and 0.67 electrons.

However, in pyxray only the integral part of the value is retained:

This results in e.g. Boron having empty L_2 and L_3 subshells. I'm assuming this is a bug?

The last build of the documentation is from more than a year ago: https://readthedocs.org/projects/pyxray/builds/. The release of latest version (1.7.0) should have triggered a new build

All pyxray functions currently only return the requested value. For example pyxray.xray_transition_energy_eV(...) returns the energy of a transition. A keyword argument should be added to each function to return the actual property which would include the reference.