Metadata-Version: 2.0
Name: pyxray
Version: 1.3.3
Summary: Definitions and properties of X-ray transitions
Home-page: https://github.com/openmicroanalysis/pyxray
Author: Hendrix Demers and Philippe T. Pinard
Author-email: hendrix.demers@mail.mcgill.ca and philippe.pinard@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: tabulate
Provides-Extra: develop
Requires-Dist: requests; extra == 'develop'
Requires-Dist: requests-cache; extra == 'develop'
Requires-Dist: progressbar2; extra == 'develop'
Requires-Dist: nose; extra == 'develop'
Requires-Dist: coverage; extra == 'develop'

######
pyxray
######

.. image:: https://img.shields.io/pypi/v/pyxray.svg
   :target: https://pypi.python.org/pypi/pyxray

.. image:: https://img.shields.io/travis/openmicroanalysis/pyxray.svg
   :target: https://travis-ci.org/openmicroanalysis/pyxray

.. image:: https://img.shields.io/codecov/c/github/openmicroanalysis/pyxray.svg
   :target: https://codecov.io/github/openmicroanalysis/pyxray

*pyxray* is a Python library that defines basic object to specify atomic 
subshells and X-ray transitions. 
The objects also provide critical information as the energy, existence and 
different notations of the X-ray transitions.

*pyxray* supports 3.x (no Python 2.x support).

Installation
============

Easiest way to install using ``pip``::

    pip install pyxray

For development installation from the git repository::

    git clone git@github.com/openmicroanalysis/pyxray.git
    cd pyxray
    pip install -e .

See development section below

Methods
=======

All methods below are accessed by importing ``pyxray``:

.. code:: python

    import pyxray

Variables of the methods are defined as follows

* ``element``: 
    either

    * `Element <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ object
    * atomic number
    * symbol (case insensitive)
    * name (in any language, case insensitive)
    * object with attribute ``atomic_number`` or ``z``

* ``atomic_shell``: 
    either

    * `AtomicShell <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ object
    * principal quantum number
    * any notation (case insensitive)

* ``atomic_subshell``: 
    either

    * `AtomicSubshell <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ object
    * a ``tuple`` of principal quantum number, azimuthal quantum number 
      and total angular momentum nominator (e.g. ``(1, 0, 1)`` for the atomic 
      subshell ``1s^{0.5}``
    * any notation (case insensitive)

* ``xraytransition``: 
    either

    * `XrayTransition <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ object
    * a ``tuple`` of source and destination subshells
    * any notation (case insensitive)

* ``xraytransitionset``:
    either

    * `XrayTransitionSet <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ object
    * a ``tuple`` of transitions
    * any notation (case insensitive)

* ``language``: 
    language code (e.g. ``en``, ``fr``, ``de``)

* ``notation``: 
    name of a notation (case insensitive),
    ``iupac``, ``siegbahn`` and ``orbital`` are usually supported

* ``encoding``: 
    type of encoding, either ``ascii``, ``utf16``, ``html`` or ``latex``

* ``reference``: 
    reference to use to retrieve this value, either

    * `Reference <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ object
    * BibTeX key of a reference
    * ``None``, the default reference will be used or the first reference found

Element properties
------------------

Properties associated with an element, defined as the ground state of an atom 
where the number of protons equal the number of electrons.

* ``pyxray.element(element)``
    Returns element descriptor.

* ``pyxray.element_atomic_number(element)``
    Returns atomic number of an element.

    Examples:

    .. code:: python

        pyxray.element.atomic_number('fe') #=> 26
        pyxray.element.atomic_number('Fe') #=> 26
        pyxray.element.atomic_number('iron') #=> 26
        pyxray.element.atomic_number('eisen') #=> 26

* ``pyxray.element_symbol(element, reference=None)``
    Returns symbol of an element.

* ``pyxray.element_name(element, language='en', reference=None)``
    Returns full name of an element, in the language specified.

* ``pyxray.element_atomic_weight(element, reference=None)``
    Returns atomic weight of an element. 
    The atomic weight is defined by the CIAAW as it is the ratio of 
    the average atomic mass of an element over 1/12 of the mass of the 
    carbon-12 atom.

* ``pyxray.element_mass_density_kg_per_m3(element, reference=None)``
    Returns mass density (in kg/m3) of an element.

* ``pyxray.element_mass_density_g_per_cm3(element, reference=None)``
    Returns mass density (in g/cm3) of an element.

* ``pyxray.element_xray_transition(element, reference=None)``
    Returns X-ray transition descriptor if x-ray transition has a 
    probability greater than 0 for that element.

* ``pyxray.element_xray_transitions(element, xraytransitionset=None, reference=None)``
    Returns all X-ray transitions which have a probability greater than 0 
    for that element. If *xraytransitionset* is not ``None``, returns all 
    x-ray transitions for this x-ray transition set.

Atomic shell properties
-----------------------

Properties associated with an `atomic shell <https://en.wikipedia.org/wiki/Electron_shell>`_, 
defined by its principal quantum number.

* ``pyxray.atomic_shell(atomic_shell)``
    Returns atomic shell descriptor.

* ``pyxray.atomic_shell_notation(atomic_shell, notation, encoding='utf16', reference=None)``
    Returns notation of an atomic shell.

Atomic subshell properties
--------------------------

Properties associated with an `atomic subshell <https://en.wikipedia.org/wiki/Electron_shell#Subshells>`_,
a subdivision of atomic shells.

* ``pyxray.atomic_subshell(atomic_subshell)``
    Returns atomic subshell descriptor.

* ``pyxray.atomic_subshell_notation(atomic_subshell, notation, encoding='utf16', reference=None)``
    Returns notation of an atomic subshell.

    Examples:

    .. code:: python

        pyxray.atomic_subshell_notation('L3', 'iupac', 'latex') #=> 'L$_{3}$'
        pyxray.atomic_subshell_notation('L3', 'orbital') #-> '2p3/2'

* ``pyxray.atomic_subshell_binding_energy_eV(element, atomic_subshell, reference=None)``
    Returns binding energy of an element and atomic subshell (in eV).

* ``pyxray.atomic_subshell_radiative_width_eV(element, atomic_subshell, reference=None)``
    Returns radiative width of an element and atomic subshell (in eV).

* ``pyxray.atomic_subshell_nonradiative_width_eV(element, atomic_subshell, reference=None)``
    Returns nonradiative width of an element and atomic subshell (in eV).

* ``pyxray.atomic_subshell_occupancy(element, atomic_subshell, reference=None)``
    Returns occupancy of an element and atomic subshell.

X-ray transition properties
---------------------------

Properties associated with an electron transition, relaxation process of an 
electron between quantum states leading to X-rays emission.

* ``pyxray.xray_transition(xraytransition)``
    Returns X-ray transition descriptor.

* ``pyxray.xray_transition_notation(xraytransition, notation, encoding='utf16', reference=None)``
    Returns notation of an X-ray transition.

    Examples:

    .. code:: python

        pyxray.transition_notation('Ka1', 'iupac') #=> 'K-L3'
        pyxray.transition_notation('L3-M1', 'siegbahn', 'ascii') #=> 'Ll'

* ``pyxray.xray_transition_energy_eV(element, xraytransition, reference=None)``
    Returns energy of an element and X-ray transition (in eV).

    Examples:

    .. code:: python

        pyxray.xray_transition_energy_eV(14, 'Ka1') #=> 1740.0263764535946
        pyxray.xray_transition_energy_eV(14, 'Ma1') #=> NotFound exception

* ``pyxray.xray_transition_probability(element, xraytransition, reference=None)``
    Returns probability of an element and X-ray transition.

* ``pyxray.xray_transition_relative_weight(element, xraytransition, reference=None)``
    Returns relative weight of an element and X-ray transition.

X-ray transition set properties
-------------------------------

Properties associated with an X-ray transition set, an indistinguishable X-ray transition 
(e.g. Ka from Ka1/Ka2).

* ``pyxray.xray_transitionset(xraytransitionset)``
    Returns X-ray transition set descriptor.

* ``pyxray.xray_transitionset_notation(xraytransitionset, notation, encoding='utf16', reference=None)``
    Returns notation of an X-ray transition set.

* ``pyxray.xray_transitionset_energy_eV(element, xraytransitionset, reference=None)``
    Returns energy of an element and X-ray transition set (in eV).

* ``pyxray.xray_transitionset_relative_weight(element, xraytransitionset, reference=None)``
    Returns relative weight of an element and X-ray transition set.

X-ray line
----------

Object to represent an x-ray line, an x-ray line of an element.
The x-ray line can either be a 
`XrayTransition <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_ 
(a transition between two atomic subshells) or a 
`XrayTransitionSet <http://github.com/openmicroanalysis/pyxray/blob/master/pyxray/descriptor.py>`_
(a set of transitions, normally indistinguishable X-ray transitions).

* ``pyxray.xray_line(element, line, reference=None)``
    Returns X-ray line descriptor.

.. code:: python

   xrayline = pyxray.xray_line(14, 'Ka1')
   xrayline.atomic_number #=> 14
   xrayline.iupac #=> Si K–L3
   xrayline.siegbahn #=> Si Kα1
   xrayline.transitions #=> (XrayTransition([n=2, l=1, j=1.5] -> [n=1, l=0, j=0.5]),)
   xrayline.energy_eV #=> 1740.0263764535946

   xrayline = pyxray.xray_line(14, 'Ka')
   xrayline.atomic_number #=> 14
   xrayline.iupac #=> Si K–L(2,3)
   xrayline.siegbahn #=> Si Kα
   xrayline.transitions #=> (XrayTransition([n=2, l=1, j=0.5] -> [n=1, l=0, j=0.5]), XrayTransition([n=2, l=1, j=1.5] -> [n=1, l=0, j=0.5]))
   xrayline.energy_eV #=> 1739.826155631858

As any other descriptors, X-ray line objects are immutable and hashable so 
they can be used as keys of a dictionary.
It is also cached to prevent multiple instances of the same x-ray line.

.. code:: python

   xrayline1 = pyxray.xray_line(13, 'Ka1')
   xrayline2 = pyxray.xray_line('Al', 'Ka1')
   xrayline1 == xrayline2 #=> True
   xrayline1 is xrayline2 #=> True

Release notes
=============

1.3.3
-----

* Fix method `element_xray_transitions` not to return duplicates.

1.3.2
-----

* Add energy to XrayLine.
* Fix missing energy property for x-ray transition sets from JEOL database.
* Clean up of unit tests.

1.3.1
-----

* Make XrayLine a descriptor and add method to create it from database.

1.2.1
-----

* Fix in build process.

1.2.0
-----

* Add ``XrayLine`` class.

Development
===========

*pyxray* stores all data for the above functions in a *SQLite* database. 
The database is constructed during the build process of the Python package 
(i.e. ``python setup.py build``) using registered parsers. 
The provided parsers are located in the package ``pyxray.parser``, but external
parsers can be provided by registering to the entry point ``pyxray.parser``.
In short, the database is not provide in the source code, only in the 
distributed version. 
It is therefore necessary to build the *SQLite* database when running *pyxray*
in development mode.
Building the database will take several minutes.
In short,

.. code:: python

   python3 setup.py build

License
=======

The library is provided under the MIT license.

*pyxray* was partially developed as part of the doctorate thesis project of 
Philippe T. Pinard at RWTH Aachen University (Aachen, Germany) under the 
supervision of Dr. Silvia Richter.

Copyright (c) 2015-2016/06 Philippe Pinard and Silvia Richter

Copyright (c) 2016/06-2017 Philippe Pinard







