-
-
Notifications
You must be signed in to change notification settings - Fork 55
Home
h1. Welcome to the xraylib wiki!
h2. Introduction
Quantitative estimate of elemental composition by spectroscopic and imaging techniques using X-ray fluorescence requires the availability of accurate data of X-ray interaction with matter. Although a wide number of computer codes and data sets are reported in literature, none of them is presented in the form of freely available library functions which can be easily included in software applications for X-ray fluorescence. This work presents a compilation of data sets from different published works and an xraylib interface in the form of callable functions. Although the target applications are on X-ray fluorescence, cross sections of interactions like photoionization, coherent scattering and Compton scattering, as well as form factors and anomalous scattering functions, are also available.
A paper was published concerning xraylib by A. Brunetti, M. Sanchez del Rio, B. Golosio, A. Simionovici and A. Somogyi, "A library for X-ray matter interaction cross sections for X-ray fluorescence applications", "Spectrochimica Acta B 59 (2004) 1725-1731":http://dx.doi.org/10.1016/j.sab.2004.03.014
You are kindly requested to include this paper in the reference list of your published work when you would decide to use xraylib for scientific purposes.
h2. Features
xraylib provides access to some of the most respected databases of physical data in the field of x-rays. The core of xraylib is a library, written in ANSI C, containing over 40 functions to be used to retrieve data from these databases. This C library can be directly linked with any program written in C, C++ or Objective-C. Furthermore, the xraylib package contains bindings to several popular programming languages: Fortran 2003, Perl, Python, Java, IDL and .NET, as well as a command-line utility which can be used as a pocket-calculator.
The source code is known to compile and run on the following platforms: Linux, Mac OS X, Solaris, FreeBSD and Windows. It is very likely that xraylib will also work on other platforms: we would be grateful if you would report your successes in this regard. Please note that not all of the bindings are currently working on all platforms.
h2. Installation instructions
You can download the latest version of xraylib by going to the "Downloads":http://github.com/tschoonj/xraylib/downloads tab. I would advise NOT to download the tagged version, since this version does not come with the configure file[1].
The main distribution channel of xraylib is through the source code. The user is expected to download the tarball and compile the software. This is accomplished in the following manner:
bq. @gunzip xraylib-version.tar.gz@
bq. @tar xvf xraylib-version.tar@
bq. @cd xraylib-version@
bq. @./configure@
bq. @make@
Optional, but recommended is to check if the compilation went well:
bq. @make check@
Depending on the requested install location, it may be necessary to perform the installation as a user with administrative privileges
bq. @make install@
configure and make will try to build as many bindings as possible. If some of these would be considered as redundant, it is possible to disable their compilation using --disable-binding options to configure. See ./configure --help for a list of all options. Keep in mind though that for the command-line utility to work, the python bindings are essential.
More information can be found in the README and INSTALL files that are included in the package.
h3. Linux
To facilitate the installation on linux systems, the package includes a spec file which can be used to produce RPM packages for linux distributions that support them (Fedora, Red Hat, Ubuntu etc). The developers have built 64-bit RPM packages of xraylib for the Fedora 10 through 16 and Redhat EL/CentOS/Scientific Linux 6 distributions. These can be downloaded from the RPM repository that is hosted by the X-ray Microspectroscopy and Imaging research group of Ghent University. Access to this repository can be obtained as follows for Fedora distros:
bq. @su -c 'rpm -Uvh http://lvserver.ugent.be/yum/xmi-repo-key-fedora.noarch.rpm'@
and for Red Hat EL based distributions:
bq. @su -c 'rpm -Uvh http://lvserver.ugent.be/yum/xmi-repo-key-redhat.noarch.rpm'@
The xraylib packages themselves can then be downloaded using yum:
bq. @su -c 'yum install xraylib xraylib-python xraylib-devel xraylib-fortran xraylib-idl'@
Updates can be installed in a similar way:
bq. @su -c 'yum update xraylib xraylib-python xraylib-devel xraylib-fortran xraylib-idl'@
h3. Mac OS X
The easiest way to install xraylib on Mac OS X is through Macports. Launch a Terminal and type in:
bq. @sudo port install xraylib@
which will install xraylib along with its python bindings. It is also possible to install the fortran, perl and java bindings in this manner. Check out the different possibilities by invoking the variants option:
bq. @sudo port variants xraylib@
h3. Windows SDK
We have created an xraylib SDK for the Windows operating system. To install, download the xraylib-{version}-win32.exe file from the Downloads section and click on it twice to activate the installation wizard. This will install the headers, examples, static libraries and the dynamic-link library (dll) into the appropriate folders. The SDK has been verified to work with several compilers: mingw32, Microsoft Visual C++, Intel C++ and Borland C++. For this last compiler use the libxrl-{version}-bcc.lib file to link.
The SDK also contains bindings for IDL and Python (versions 2.6, 2.7 and 3.1), as well as bindings for the .NET framework. The IDL_PATH and IDL_DLM_PATH environment variables will be set correctly during installation making the bindings immediately available to the user. This is not true however, for the Python bindings: the user is requested to set the PYTHONPATH manually. It should point to the xraylib Python folder as well as the xraylib Pythonx.y folder corresponding with the installed Python interpreter.
The README.TXT file in the Lib subdirectory of the xraylib SDK explains the steps we used to create this package, as well as some advice on how to use it. The Visual C++ 2008 and 2010 Redistributable libraries will be installed if necessary.
h3. Windows command-line utility
With the release of version 2.14.0, a special version of the xraylib command-line utility was created for the Windows platform. The installer xraylib-{version}-win32-cli.exe can be found in the Downloads section. It will install the executable xraylib.exe, as well as some auxiliary files and the Visual C++ 2008 Redistributable libraries (if necessary). This executable was constructed using py2exe and contains the xraylib dll, Python bindings and scripts as well as the Python interpreter version 2.7
After the installation, typing in: xraylib.exe at the command prompt will launch the application. The PATH environment variable should pick it up.
h2. Using the C library (*NIX only)
The source code contains a pkg-config file that will facilitate the use of xraylib in combination with your own software. For example, you can compile program.c as follows:
bq. @gcc pkg-config --cflags libxrl program.c pkg-config --libs libxrl@
This approach makes sure that the preprocessor finds the right headers and that the linker finds the library. Depending on the installation location of the library, it may be necessary to change the LD_LIBRARY_PATH and/or DYLD_LIBRARY_PATH environment variables. On linux systems it is also possible to add a file containing the xraylib library location to the /etc/ld.so.conf.d directory and running ldconfig (as administrator) if linking errors appear at runtime.
h2. Bindings to other languages
h3. Fortran (*NIX only)
In order to compile the xraylib Fortran bindings, it is necessary that the configure script finds a Fortran compiler on the system that supports the C interoperability features of the Fortran 2003 standard. Compilers known to do the job include: gfortran 4.3 (and newer), Intel Fortran (10.0 and newer) and Sun Studio 12 (and newer).
Similar to the C library, it is possible to link in the Fortran bindings using a pkg-config file. Use the following syntax:
bq. @gfortran pkg-config --cflags libxrlf03 program.f90 pkg-config --libs libxrlf03@
h3. Python
To include the xraylib python module in your own scripts add the following line:
bq. @import _xraylib@
Depending on the install location of xraylib, it may be necessary to adjust the PYTHONPATH environment variable.
h3. Perl (*NIX only)
To include the xraylib perl module in your own scripts add the following line:
bq. @use xraylib;@
Depending on the install location of xraylib, it may be necessary to adjust the PERL5LIB environment variable.
h3. IDL
To use the IDL bindings, update the IDL_PATH and IDL_DLM_PATH environment variables to include ${prefix}/pro and ${prefix}/dlm respectively. If you want to take advantage of the xraylib constants, add the line
bq. @@xraylib@
to your IDL scripts or your IDL startup script (recommended).
h3. Java (*NIX only)
To load the xraylib bindings at runtime, include the line
bq. @System.loadLibrary("xraylib");@
in your java code. You may have to update the CLASSPATH environment variable to make sure that it points to the location of the xraylib class variables at compile- and runtime.
h2. Command-line utility
The command-line utility called @xraylib@ will be installed in the bin subfolder of the requested installation path (default: /usr/local/bin). If your shell does not pick this up after the installation, update your PATH environment variable accordingly.
An example of usage (fluorescence line energy of Ca-Kalpha):
bq. @xraylib "LineEnergy(20,KA_LINE)"@
Help can be requested:
bq. @xraylib -h@
h2. Available routines
h3. Atomic weight
@float AtomicWeight(int Z)@
Given an element Z, returns its atomic weight
h3. Cross sections
@float CS_Total(int Z, float E)@ @float CS_Photo(int Z, float E)@ @float CS_Rayl(int Z, float E)@ @float CS_Compt(int Z, float E)@
Given an element Z and an energy E (expressed in keV), these functions will return respectively the total absorption cross section, the photoionization cross section, the Rayleigh scattering cross section and the Compton scattering cross section, expressed in cm2/g.
@float CSb_Total(int Z, float E)@ @float CSb_Photo(int Z, float E)@ @float CSb_Rayl(int Z, float E)@ @float CSb_Compt(int Z, float E)@
Identical to the last four functions, but the cross section is returned expressed in barn/atom.
@float CS_KN(float E)@
Given an energy E (expressed in keV), returns the Total Klein-Nishina cross section expressed in barn.
@float CS_Photo_Partial(int Z, int shell, float E)@
Given an element Z, shelltype shell (xraylib macro) and energy E (expressed in keV), returns the partial photoionization cross section expressed in cm2/g.
@float CSb_Photo_Partial(int Z, int shell, float E)@
Identical to the last function, but the cross section is returned in barn/electron.
@float CS_Total_Kissel(int Z, float E)@ @float CSb_Total_Kissel(int Z, float E)@
Identical to CS_Total and CSb_Total, but the photoionization contribution is calculated using the Kissel cross sections.
@float CS_Total_CP(const char compound[], float E)@ @float CS_Photo_CP(const char compound[], float E)@ @float CS_Rayl_CP(const char compound[], float E)@ @float CS_Compt_CP(const char compound[], float E)@ @float CSb_Total_CP(const char compound[], float E)@ @float CSb_Photo_CP(const char compound[], float E)@ @float CSb_Rayl_CP(const char compound[], float E)@ @float CSb_Compt_CP(const char compound[], float E)@ @float CS_Total_Kissel_CP(const char compound[], float E)@ @float CSb_Total_Kissel_CP(const char compound[], float E)@
Identical to the earlier mentioned functions, but require a chemical formula as first argument.
h3. Unpolarized differential scattering cross sections
@float DCS_Thoms(float theta)@
Given a scattering polar angle theta (expressed in rad), returns the Thomson differential cross section expressed in barn.
@float DCS_KN(float E, float theta)@
Given an energy E (expressed in keV) and a scattering polar angle theta (expressed in rad), returns the Klein-Nishina differential scattering cross section expressed in barn.
@float DCS_Rayl(int Z, float E, float theta)@ @float DCS_Compt(int Z, float E, float theta)@
Given an element Z, energy E (expressed in keV) and a scattering polar angle theta (expressed in rad), returns respectively the differential Rayleigh and the differential Compton scattering cross section expressed in cm2/g/sterad.
@float DCSb_Rayl(int Z, float E, float theta)@ @float DCSb_Compt(int Z, float E, float theta)@
Identical to the last two functions, but the cross section is returned expressed in barn/atom/sterad.
@float DCS_Rayl_CP(const char compound[], float E, float theta)@ @float DCS_Compt_CP(const char compound[], float E, float theta)@ @float DCSb_Rayl_CP(const char compound[], float E, float theta)@ @float DCSb_Compt_CP(const char compound[], float E, float theta)@
Identical to the earlier mentioned functions, but these require a chemical compound as first argument.
h3. Polarized differential scattering cross sections
@float DCSP_Thoms(float theta, float phi)@
Given a scattering polar angle theta (expressed in rad) and scattering azimuthal angle phi (expressed in rad), returns the Thomson differential cross section for a polarized beam expressed in barn.
@float DCSP_KN(float E, float theta, float phi)@
Given an energy E (expressed in keV), a scattering polar angle theta (expressed in rad) and scattering azimuthal angle phi (expressed in rad), returns the Klein-Nishina differential cross section for a polarized beam expressed in barn.
@float DCSP_Rayl(int Z, float E, float theta, float phi)@ @float DCSP_Compt(int Z, float E, float theta, float phi)@
Given an element E, an energy E (expressed in keV), a scattering polar angle theta (expressed in rad) and scattering azimuthal angle phi (expressed in rad), returns respectively the Rayleigh differential and Compton differential cross sections for a polarized beam expressed in cm2/g/sterad.
@float DCSPb_Rayl(int Z, float E, float theta, float phi)@ @float DCSPb_Compt(int Z, float E, float theta, float phi)@
Identical to the last two functions, but the cross section is returned expressed in barn/atom/sterad.
@float DCSP_Rayl_CP(const char compound[], float E, float theta, float phi)@ @float DCSP_Compt_CP(const char compound[], float E, float theta, float phi)@ @float DCSPb_Rayl_CP(const char compound[], float E, float theta, float phi)@ @float DCSPb_Compt_CP(const char compound[], float E, float theta, float phi)@
Identical to the earlier mentioned functions, but these require a chemical compound as first argument.
h3. Scattering factors
@float FF_Rayl(int Z, float q)@
Given an element Z and a momentum transfer q, returns the atomic form factor for Rayleigh scattering.
@float SF_Compt(int Z, float q)@
Given an element Z and a momentum transfer q, returns the incoherent scattering function for Compton scattering.
@float MomentTransf(float E, float theta)@
Given an energy E (expressed in keV) and a scattering polar angle theta (expressed in rad), returns the momentum transfer for X-ray photon scattering expressed in Angstrom-1.
@float Fi(int Z, float E)@ @float Fii(int Z, float E)@
Given an element Z and and energy E, returns respectively the anomalous scattering factors Fi and Fii.
h3. X-ray fluorescent line energy
@float LineEnergy(int Z, int line)@
Given an element Z and linetype line (xraylib macro), returns the line energy of the requested line expressed in keV.
h3. Fluorescence yield
@float FluorYield(int Z, int shell)@
Given an element Z and shelltype shell (xraylib macro), returns the corresponding fluorescence yield (dimensionless quantity).
h3. Coster-Kronig transition probability
@float CosKronTransProb(int Z, int trans)@
Given an element Z and transition type trans (xraylib macro), returns the corresponding Coster-Kronig transition probability.
h3. Absorption edge energy
@float EdgeEnergy(int Z, int shell)@
Given an element Z and shelltype shell (xraylib macro), returns the absorption edge energy expressed in keV.
h3. Jump factor
@float JumpFactor(int Z, int shell)@
Given an element Z and shelltype shell (xraylib macro), returns the jump factor.
h3. XRF cross sections
@float CS_FluorLine(int Z, int line, float E)@
Given an element Z, a linetype line (xraylib macro) and an energy E (expressed in keV), returns the XRF cross section expressed in cm2/g
@float CSb_FluorLine(int Z, int line, float E)@
Identical to the latter, but returns the cross section expressed in barn/atom. The last two functions calculate the XRF cross sections assuming the jump factor approximation. We offer also XRF cross sections calculated using the partial photoelectric effect cross sections calculated by Kissel et al. The corresponding functions are:
@float CS_FluorLine_Kissel(int Z, int line, float E)@ @float CSb_FluorLine_Kissel(int Z, int line, float E)@
Recently we also introduced XRF cross sections that take into account cascade effects, both those coming from radiative transitions and those from non-radiative transitions (Auger):
@float CS_FluorLine_Kissel_Cascade(int Z, int line, float E)@ @float CSb_FluorLine_Kissel_Cascade(int Z, int line, float E)@ @float CS_FluorLine_Kissel_Nonradiative_Cascade(int Z, int line, float E)@ @float CSb_FluorLine_Kissel_Nonradiative_Cascade(int Z, int line, float E)@ @float CS_FluorLine_Kissel_Radiative_Cascade(int Z, int line, float E)@ @float CSb_FluorLine_Kissel_Radiative_Cascade(int Z, int line, float E)@ @float CS_FluorLine_Kissel_no_Cascade(int Z, int line, float E)@ @float CSb_FluorLine_Kissel_no_Cascade(int Z, int line, float E)@
CS_FluorLine_Kissel and CbS_FluorLine_Kissel are mapped to resp. CS_FluorLine_Kissel_Cascade and CSb_FluorLine_Kissel_Cascade. Using these functions, it is possible to examine the influence of the two different cascade types separately, but keep in mind that in reality they will always be occuring simultaneously.
h3. Fractional radiative rate
@float RadRate(int Z, int line)@
Given an element Z and a linetype line (xraylib macro), returns the radiative rate.
h3. Fractional non-radiative rate
@float AugerRate(int Z, int auger)@
Given an element Z and an AUGER macro corresponding with the electons involved, returns the non-radiative rate.
h3. Atomic level width
@float AtomicLevelWidth(int Z, int shell)@
Given an element Z and a shell, returns the atomic level width in keV.
h3. Compton energy
@float ComptonEnergy(float E0, float theta)@
Given an initial photon energy E0 (expressed in keV) and a scattering polar angle theta (expressed in rad), returns the photon energy after Compton scattering.
h3. Refractive index
@float Refractive_Index_Re(const char compound[], float E, float density)@ @float Refractive_Index_Im(const char compound[], float E, float density)@
Given a chemical formula, energy E (expressed in keV) and a density (expressed in g/cm3), return respectively the real and imaginary parts of the refractive index.
h3. Compton profiles
@float ComptonProfile(int Z, float pz)@
Given an element Z and a momentum pz, returns the Compton scattering profile.
@float ComptonProfile_Partial(int Z, int shell, float pz)@
Given an element Z, a shelltype shell (xraylib macro) and a momentum pz, returns the subshell Compton scattering profile.
h3. Electronic configuration
@float ElectronConfig(int Z, int shell)@
Given an element Z and a shelltype shell (xraylib macro), returns the number of electrons the shell possesses.
h2. Examples
Examples demonstrating the usage of the C library and the bindings can be found in the example folder of the xraylib package. These examples will be compiled and executed when @make check@ is invoked after @make@ during the installation.
h2. References
h2. License information
The xraylib source code is distributed under the BSD license. A copy of this license can be found in the source tarball.
fn1. It is still possible though to compile the software based on this package, if you run @autoreconf -i@ after unpacking the tarball, and then following the rest of the steps outlined in the installation section. This requires a complete installation of the GNU build tools Autoconf, Automake and Libtool (at least version 2.0!!).