xrayutilities.materials package

Submodules

xrayutilities.materials.atom module

module containing the Atom class which handles the database access for atomic scattering factors and the atomic mass.

class xrayutilities.materials.atom.Atom(name, num)

Bases: object

__init__(name, num)

property color

f(q, en='config')

function to calculate the atomic structure factor F

Parameters:

qfloat, array-like

momentum transfer

enfloat or str, optional

energy for which F should be calculated, if omitted the value from the xrayutilities configuration is used

Returns:

float or array-like

value(s) of the atomic structure factor

f0(q)

f1(en='config')

f2(en='config')

get_cache(prop, key)

check if a cached value exists to speed up repeated database requests

Returns:

bool

True then result contains the cached otherwise False and result is None

resultdatabase value

max_cache_length = 1000

property radius

set_cache(prop, key, result)

set result to be cached to speed up future calls

property weight

xrayutilities.materials.atom.get_key(*args)

generate a hash key for several possible types of arguments

xrayutilities.materials.cif module

class xrayutilities.materials.cif.CIFDataset(fid, name, digits)

Bases: object

class for parsing CIF (Crystallographic Information File) files. The class aims to provide an additional way of creating material classes instead of manual entering of the information the lattice constants and unit cell structure are parsed from the CIF file

Parse(fid)

function to parse a CIF data set. The function reads the space group symmetry operations and the basic atom positions as well as the lattice constants and unit cell angles

SGLattice(use_p1=False)

create a SGLattice object with the structure from the CIF file

SymStruct()

function to obtain the list of different atom positions in the unit cell for the different types of atoms and determine the space group number and origin choice if available. The data are obtained from the data parsed from the CIF file.

__init__(fid, name, digits)

initialization of the CIFDataset class. This class parses one data block.

Parameters:

fidfilehandle

file handle set to the beginning of the data block to be parsed

namestr

identifier string of the dataset

digitsint

number of digits to check if position is unique

class xrayutilities.materials.cif.CIFFile(filestr, digits=4)

Bases: object

class for parsing CIF (Crystallographic Information File) files. The class aims to provide an additional way of creating material classes instead of manual entering of the information the lattice constants and unit cell structure are parsed from the CIF file.

If multiple datasets are present in the CIF file this class will attempt to parse all of them into the the data dictionary. By default all methods access the first data set found in the file.

Parse(fid)

function to parse a CIF file. The function reads all the included data sets and adds them to the data dictionary.

SGLattice(dataset=None, use_p1=False)

create a SGLattice object with the structure from the CIF dataset

Parameters:

datasetstr, optional

name of the dataset to use. if None the default one will be used.

use_p1bool, optional

force the use of P1 symmetry, default False

__init__(filestr, digits=4)

initialization of the CIFFile class

Parameters:

filestrstr, bytes

CIF filename or string representation of the CIF file

digitsint, optional

number of digits to check if position is unique

xrayutilities.materials.cif.cifexport(filename, mat)

function to export a Crystal instance to CIF file. This in particular includes the atomic coordinates, however, ignores for example the elastic parameters.

xrayutilities.materials.database module

module to handle the access to the optical parameters database

class xrayutilities.materials.database.DataBase(fname)

Bases: object

Close()

Close an opend database file.

Create(dbname, dbdesc)

Creates a new database. If the database file already exists its content is delete.

Parameters:

dbnamestr

name of the database

dbdescstr

a short description of the database

CreateMaterial(name, description)

This method creates a new material. If the material group already exists the procedure is aborted.

Parameters:

namestr

name of the material

descriptionstr

description of the material

GetF0(q, dset='default')

Obtain the f0 scattering factor component for a particular momentum transfer q.

Parameters:

qfloat or array-like

momentum transfer

dsetstr, optional

specifies which dataset (different oxidation states) should be used

GetF1(en)

Return the second, energy dependent, real part of the scattering factor for a certain energy en.

Parameters:

enfloat or array-like

energy

GetF2(en)

Return the imaginary part of the scattering factor for a certain energy en.

Parameters:

enfloat or array-like

energy

Open(mode='r')

Open an existing database file.

SetColor(color)

Save color of the element for visualization

Parameters:

colortuple, str

matplotlib color for the element

SetF0(parameters, subset='default')

Save f0 fit parameters for the set material. The fit parameters are stored in the following order: c, a1, b1,……., a4, b4

Parameters:

parameterslist or array-like

fit parameters

subsetstr, optional

name the f0 dataset

SetF1F2(en, f1, f2)

Set f1, f2 values for the active material.

Parameters:

enlist or array-like

energy in (eV)

f1list or array-like

f1 values

f2list or array-like

f2 values

SetMaterial(name)

Set a particular material in the database as the actual material. All operations like setting and getting optical constants are done for this particular material.

Parameters:

namestr

name of the material

SetRadius(radius)

Save atomic radius for visualization

Parameters:

radius: float

atomic radius in angstrom

SetWeight(weight)

Save weight of the element as float

Parameters:

weightfloat

atomic standard weight of the element

__init__(fname)

xrayutilities.materials.database.add_color_from_JMOL(db, cfile, verbose=False)

Read color from JMOL color table and save it to the database.

xrayutilities.materials.database.add_f0_from_intertab(db, itf, verbose=False)

Read f0 data from International Tables of Crystallography and add it to the database.

xrayutilities.materials.database.add_f0_from_xop(db, xop, verbose=False)

Read f0 data from f0_xop.dat and add it to the database.

xrayutilities.materials.database.add_f1f2_from_ascii_file(db, asciifile, element, verbose=False)

Read f1 and f2 data for specific element from ASCII file (3 columns) and save it to the database.

xrayutilities.materials.database.add_f1f2_from_henkedb(db, hf, verbose=False)

Read f1 and f2 data from Henke database and add it to the database.

xrayutilities.materials.database.add_f1f2_from_kissel(db, kf, verbose=False)

Read f1 and f2 data from Henke database and add it to the database.

xrayutilities.materials.database.add_mass_from_NIST(db, nistfile, verbose=False)

Read atoms standard mass and save it to the database. The mass of the natural isotope mixture is taken from the NIST data!

xrayutilities.materials.database.add_radius_from_WIKI(db, dfile, verbose=False)

Read radius from Wikipedia radius table and save it to the database.

xrayutilities.materials.database.createAndFillDatabase(fname, dpath=None, verbose=False)

function to create the database and fill it with values from the various source files.

Parameters:

fnamestr

Filename of the database to be created (including the path)

dpathstr, optional

directory where all the source data files are stored

verbosebool, optional

flag to determine the verbosity of the script (default: False)

xrayutilities.materials.database.init_material_db(db)

xrayutilities.materials.elements module

xrayutilities.materials.heuslerlib module

implement convenience functions to define Heusler materials.

xrayutilities.materials.heuslerlib.FullHeuslerCubic225(X, Y, Z, a, biso=(0, 0, 0), occ=(1, 1, 1))

Full Heusler structure with formula X2YZ. Strukturberichte symbol L2_1; space group Fm-3m (225)

Parameters:

X, Y, Zstr or Element

elements

afloat

cubic lattice parameter in angstrom

bisolist of floats, optional

Debye Waller factors for X, Y, Z elements

occlist of floats, optional

occupation numbers for the elements X, Y, Z

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.FullHeuslerCubic225_A2(X, Y, Z, a, a2dis, biso=(0, 0, 0), occ=(1, 1, 1))

Full Heusler structure with formula X2YZ. Strukturberichte symbol L2_1; space group Fm-3m (225) with A2-type (W) disorder

Parameters:

X, Y, Zstr or Element

elements

afloat

cubic lattice parameter in angstrom

a2disfloat

amount of A2-type disorder (0: fully ordered, 1: fully disordered)

bisolist of floats, optional

Debye Waller factors for X, Y, Z elements

occlist of floats, optional

occupation numbers for the elements X, Y, Z

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.FullHeuslerCubic225_B2(X, Y, Z, a, b2dis, biso=(0, 0, 0), occ=(1, 1, 1))

Full Heusler structure with formula X2YZ. Strukturberichte symbol L2_1; space group Fm-3m (225) with B2-type (CsCl) disorder

Parameters:

X, Y, Zstr or Element

elements

afloat

cubic lattice parameter in angstrom

b2disfloat

amount of B2-type disorder (0: fully ordered, 1: fully disordered)

bisolist of floats, optional

Debye Waller factors for X, Y, Z elements

occlist of floats, optional

occupation numbers for the elements X, Y, Z

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.FullHeuslerCubic225_DO3(X, Y, Z, a, do3disxy, do3disxz, biso=(0, 0, 0), occ=(1, 1, 1))

Full Heusler structure with formula X2YZ. Strukturberichte symbol L2_1; space group Fm-3m (225) with DO_3-type (BiF3) disorder, either between atoms X <-> Y or X <-> Z.

Parameters:

X, Y, Zstr or Element

elements

afloat

cubic lattice parameter in angstrom

do3disxyfloat

amount of DO_3-type disorder between X and Y atoms (0: fully ordered, 1: fully disordered)

do3disxzfloat

amount of DO_3-type disorder between X and Z atoms (0: fully ordered, 1: fully disordered)

bisolist of floats, optional

Debye Waller factors for X, Y, Z elements

occlist of floats, optional

occupation numbers for the elements X, Y, Z

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.HeuslerHexagonal194(X, Y, Z, a, c, biso=(0, 0, 0), occ=(1, 1, 1))

Hexagonal Heusler structure with formula XYZ space group P63/mmc (194)

Parameters:

X, Y, Zstr or Element

elements

a, cfloat

hexagonal lattice parameters in angstrom

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.HeuslerTetragonal119(X, Y, Z, a, c, biso=(0, 0, 0), occ=(1, 1, 1))

Tetragonal Heusler structure with formula X2YZ space group I-4m2 (119)

Parameters:

X, Y, Zstr or Element

elements

a, cfloat

tetragonal lattice parameters in angstrom

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.HeuslerTetragonal139(X, Y, Z, a, c, biso=(0, 0, 0), occ=(1, 1, 1))

Tetragonal Heusler structure with formula X2YZ space group I4/mmm (139)

Parameters:

X, Y, Zstr or Element

elements

a, cfloat

tetragonal lattice parameters in angstrom

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.heuslerlib.InverseHeuslerCubic216(X, Y, Z, a, biso=(0, 0, 0), occ=(1, 1, 1))

Full Heusler structure with formula (XY)X’Z structure; space group F-43m (216)

Parameters:

X, Y, Zstr or Element

elements

afloat

cubic lattice parameter in angstrom

Returns:

Crystal

Crystal describing the Heusler material

xrayutilities.materials.material module

Classes decribing materials. Materials are devided with respect to their crystalline state in either Amorphous or Crystal types. While for most materials their crystalline state is defined few materials are also included as amorphous which can be useful for calculation of their optical properties.

class xrayutilities.materials.material.Alloy(matA, matB, x)

Bases: Crystal

alloys two materials from the same crystal system. If the materials have the same space group the Wyckoff positions within the unit cell will also reflect the alloying.

RelaxationTriangle(hkl, sub, exp)

function which returns the relaxation triangle for a Alloy of given composition. Reciprocal space coordinates are calculated using the user-supplied experimental class

Parameters:

hkllist or array-like

Miller Indices

subCrystal, or float

substrate material or lattice constant

expExperiment

object from which the Transformation object and ndir are needed

Returns:

qy, qzfloat

reciprocal space coordinates of the corners of the relaxation triangle

__init__(matA, matB, x)

static check_compatibility(matA, matB)

static lattice_const_AB(latA, latB, x)

method to calculated the interpolation of lattice parameters and unit cell angles of the Alloy. By default linear interpolation between the value of material A and B is performed.

Parameters:

latA, latBfloat or vector

property (lattice parameter/angle) of material A and B. A property can be a scalar or vector.

xfloat

fraction of material B in the alloy.

property x

class xrayutilities.materials.material.Amorphous(name, density, atoms=None, cij=None)

Bases: Material

amorphous materials are described by this class

__init__(name, density, atoms=None, cij=None)

constructor of an amorphous material. The amorphous material is described by its density and atom composition.

Parameters:

namestr

name of the material. To allow automatic parsing of the chemical elements use the abbreviation of the chemical element from the periodic table. To specify alloys, use e.g. ‘Ir0.2Mn0.8’ or ‘H2O’.

densityfloat

mass density in kg/m^3

atomslist, optional

list of atoms together with their fractional content. When the name is a simply chemical formula then this can be None. To specify more complicated materials use [(‘Ir’, 0.2), (‘Mn’, 0.8), …]. Instead of the elements as string you can also use an Atom object. If the contents to not add up to 1 they will be normalized without notice.

cijarray-like, optional

elasticity matrix

chi0(en='config')

calculates the complex chi_0 values often needed in simulations. They are closely related to delta and beta (n = 1 + chi_r0/2 + i*chi_i0/2 vs. n = 1 - delta + i*beta)

delta(en='config')

function to calculate the real part of the deviation of the refractive index from 1 (n=1-delta+i*beta)

Parameters:

enfloat, array-like or str, optional

energy of the x-rays in eV

Returns:

float or array-like

ibeta(en='config')

function to calculate the imaginary part of the deviation of the refractive index from 1 (n=1-delta+i*beta)

Parameters:

enfloat, array-like or str, optional

energy of the x-rays in eV

Returns:

float or array-like

static parseChemForm(cstring)

Parse a string containing a simple chemical formula and transform it to a list of elements together with their relative atomic fraction. e.g. ‘H2O’ -> [(H, 2/3), (O, 1/3)], where H and O are the Element objects of Hydrogen and Oxygen. Note that every chemical element needs to start with a capital letter! Complicated formulas containing bracket are not supported!

Parameters:

cstringstr

string containing the chemical fomula

Returns:

list of tuples

chemical element and atomic fraction

xrayutilities.materials.material.Cij2Cijkl(cij)

Converts the elastic constants matrix (tensor of rank 2) to the full rank 4 cijkl tensor.

Parameters:

cijarray-like

(6, 6) cij matrix

Returns:

cijkl ndarray

(3, 3, 3, 3) cijkl tensor as numpy array

xrayutilities.materials.material.Cij2Sijkl(cij)

Converts the elastic constants matrix (tensor of rank 2) to the full rank 4 sijkl compliance tensor.

Parameters:

cijarray-like

(6, 6) cij matrix

Returns:

sijkl ndarray

(3, 3, 3, 3) sijkl tensor as numpy array

xrayutilities.materials.material.Cijkl2Cij(cijkl)

Converts the full rank 4 tensor of the elastic constants to the (6, 6) matrix of elastic constants.

Parameters:

cijkl ndarray

(3, 3, 3, 3) cijkl tensor as numpy array

Returns:

cijarray-like

(6, 6) cij matrix

class xrayutilities.materials.material.Crystal(name, lat, cij=None, thetaDebye=None)

Bases: Material

Crystalline materials are described by this class

ApplyStrain(strain)

Applies a certain strain on the lattice of the material. The result is a change in the base vectors of the real space as well as reciprocal space lattice. The full strain matrix (3x3) needs to be given, which can be GetStrain’s output.

Note

NO elastic response of the material will be considered!

property B

GetMismatch(mat)

Calculate the mismatch strain between the material and a second material

HKL(*q)

Return the HKL-coordinates for a certain Q-space position.

Parameters:

qlist or array-like

Q-position. its also possible to use HKL(qx, qy, qz).

Q(*hkl)

Return the Q-space position for a certain material.

Parameters:

hkllist or array-like

Miller indices (or Q(h, k, l) is also possible)

StructureFactor(q, en='config', temp=0)

calculates the structure factor of a material for a certain momentum transfer and energy at a certain temperature of the material

Parameters:

qlist, tuple or array-like

vectorial momentum transfer

enfloat or str, optional

x-ray energy eV, if omitted the value from the xrayutilities configuration is used

tempfloat

temperature used for Debye-Waller-factor calculation

Returns:

complex

the complex structure factor

StructureFactorForEnergy(q0, en, temp=0)

calculates the structure factor of a material for a certain momentum transfer and a bunch of energies

Parameters:

q0list, tuple or array-like

vectorial momentum transfer

enlist, tuple or array-like

energy values in eV

tempfloat

temperature used for Debye-Waller-factor calculation

Returns:

array-like

complex valued structure factor array

StructureFactorForQ(q, en0='config', temp=0)

calculates the structure factor of a material for a bunch of momentum transfers and a certain energy

Parameters:

qlist of vectors or array-like

vectorial momentum transfers; list of vectores (list, tuple or array) of length 3 e.g.: (Si.Q(0, 0, 4), Si.Q(0, 0, 4.1),…) or numpy.array([Si.Q(0, 0, 4), Si.Q(0, 0, 4.1)])

en0float or str, optional

x-ray energy eV, if omitted the value from the xrayutilities configuration is used

tempfloat

temperature used for Debye-Waller-factor calculation

Returns:

array-like

complex valued structure factor array

__init__(name, lat, cij=None, thetaDebye=None)

property a

property a1

property a2

property a3

property alpha

property b

property beta

property c

chemical_composition(natoms=None, with_spaces=False, ndigits=2)

determine chemical composition from occupancy of atomic positions.

Parameters:

matCrystal

instance of Crystal

natomsint, optional

number of atoms to normalize the formula, if None some automatic normalization is attempted using the greatest common divisor of the number of atoms per unit cell. If the number of atoms of any element is fractional natoms=1 is used.

with_spacesbool, optional

add spaces between the different entries in the output string for CIF combatibility

ndigitsint, optional

number of digits to which floating point numbers are rounded to

Returns:

str

representation of the chemical composition

chi0(en='config')

calculates the complex chi_0 values often needed in simulations. They are closely related to delta and beta (n = 1 + chi_r0/2 + i*chi_i0/2 vs. n = 1 - delta + i*beta)

chih(q, en='config', temp=0, polarization='S')

calculates the complex polarizability of a material for a certain momentum transfer and energy

Parameters:

qlist, tuple or array-like

momentum transfer vector in (1/A)

enfloat or str, optional

x-ray energy eV, if omitted the value from the xrayutilities configuration is used

tempfloat, optional

temperature used for Debye-Waller-factor calculation

polarization{‘S’, ‘P’}, optional

sigma or pi polarization

Returns:

tuple

(abs(chih_real), abs(chih_imag)) complex polarizability

dTheta(Q, en='config')

function to calculate the refractive peak shift

Parameters:

Qlist, tuple or array-like

momentum transfer vector (1/A)

enfloat or str, optional

x-ray energy eV, if omitted the value from the xrayutilities configuration is used

Returns:

float

peak shift in degree

delta(en='config')

function to calculate the real part of the deviation of the refractive index from 1 (n=1-delta+i*beta)

Parameters:

enfloat or str, optional

x-ray energy eV, if omitted the value from the xrayutilities configuration is used

Returns:

float

property density

calculates the mass density of an material from the mass of the atoms in the unit cell.

Returns:

float

mass density in kg/m^3

distances()

function to obtain distances of atoms in the crystal up to the unit cell size (largest value of a, b, c is the cut-off)

returns a list of tuples with distance d and number of occurence n [(d1, n1), (d2, n2),…]

Note

if the base of the material is empty the list will be empty

environment(*pos, **kwargs)

Returns a list of neighboring atoms for a given position within the unit cell. If the material does not contain any atoms a dummy atom will be placed on the unit cell corners.

Parameters:

poslist or array-like

fractional coordinate in the unit cell

maxdistfloat

maximum distance wanted in the list of neighbors (default: 7)

Returns:

list of tuples

(distance, atomType, multiplicity) giving distance sorted list of atoms

classmethod fromCIF(ciffilestr, **kwargs)

Create a Crystal from a CIF file. The default data-set from the cif file will be used to create the Crystal.

Parameters:

ciffilestrstr, bytes

filename of the CIF file or string representation of the CIF file

kwargsdict

keyword arguments are passed to the init-method of CIFFile

Returns:

Crystal

property gamma

ibeta(en='config')

function to calculate the imaginary part of the deviation of the refractive index from 1 (n=1-delta+i*beta)

Parameters:

enfloat or str, optional

x-ray energy eV, if omitted the value from the xrayutilities configuration is used

Returns:

float

loadLatticefromCIF(ciffilestr)

load the unit cell data (lattice) from the CIF file. Other material properties stay unchanged.

Parameters:

ciffilestrstr, bytes

filename of the CIF file or string representation of the CIF file

planeDistance(*hkl)

determines the lattice plane spacing for the planes specified by (hkl)

Parameters:

h, k, llist, tuple or floats

Miller indices of the lattice planes given either as list, tuple or seperate arguments

Returns:

float

the lattice plane spacing

Examples

>>> import xrayutilities as xu
>>> xu.materials.Si.planeDistance(0, 0, 4)
1.3577600000000003

or

>>> xu.materials.Si.planeDistance((1, 1, 1))
3.1356124059796264

show_unitcell(fig=None, subplot=111, scale=0.6, complexity=11, linewidth=1.5, mode='matplotlib')

visualization of the unit cell using either matplotlibs basic 3D functionality (expect rendering inaccuracies!) or the mayavi mlab package (accurate rendering -> recommended!)

Note

For more flexible visualization consider using the CIF-export feature and use a proper crystal structure viewer.

Parameters:

figmatplotlib Figure, Mayavi Scene, or None, optional

subplotint or list, optional

subplot to use for the visualization when using matplotlib. This argument of fowarded to the first argument of matplotlibs add_subplot function

scalefloat, optional

scale the size of the atoms by this additional factor. By default the size of the atoms corresponds to 60% of their atomic radius.

complexityint, optional

number of steps to approximate the atoms as spheres. Higher values make spheres more accurate, but cause slower plotting.

linewidthfloat, optional

line thickness of the unit cell outline

modestr, optional

defines the plot backend used, can be ‘matplotlib’ (default) or ‘mayavi’.

Returns:

figure object of either matplotlib or Mayavi

toCIF(ciffilename)

Export the Crystal to a CIF file.

Parameters:

ciffilenamestr

filename of the CIF file

class xrayutilities.materials.material.CubicAlloy(matA, matB, x)

Bases: Alloy

ContentBasym(q_inp, q_perp, hkl, sur)

function that determines the content of B in the alloy from the reciprocal space position of an asymmetric peak.

Parameters:

q_inpfloat

inplane peak position of reflection hkl of the alloy in reciprocal space

q_perpfloat

perpendicular peak position of the reflection hkl of the alloy in reciprocal space

hkllist

Miller indices of the measured asymmetric reflection

surlist

Miller indices of the surface (determines the perpendicular direction)

Returns:

contentfloat

content of B in the alloy determined from the input variables

list

[a_inplane a_perp, a_bulk_perp(x), eps_inplane, eps_perp]; lattice parameters calculated from the reciprocal space positions as well as the strain (eps) of the layer

ContentBsym(q_perp, hkl, inpr, asub, relax)

function that determines the content of B in the alloy from the reciprocal space position of a symetric peak. As an additional input the substrates lattice parameter and the degree of relaxation must be given

Parameters:

q_perpfloat

perpendicular peak position of the reflection hkl of the alloy in reciprocal space

hkllist

Miller indices of the measured symmetric reflection (also defines the surface normal

inprlist

Miller indices of a Bragg peak defining the inplane reference direction

asubfloat

substrate lattice parameter

relaxfloat

degree of relaxation (needed to obtain the content from symmetric reciprocal space position)

Returns:

contentfloat

the content of B in the alloy determined from the input variables

__init__(matA, matB, x)

xrayutilities.materials.material.CubicElasticTensor(c11, c12, c44)

Assemble the 6x6 matrix of elastic constants for a cubic material from the three independent components of a cubic crystal

Parameters:

c11, c12, c44float

independent components of the elastic tensor of cubic materials

Returns:

cijndarray

6x6 matrix with elastic constants

xrayutilities.materials.material.HexagonalElasticTensor(c11, c12, c13, c33, c44)

Assemble the 6x6 matrix of elastic constants for a hexagonal material from the five independent components of a hexagonal crystal

Parameters:

c11, c12, c13, c33, c44float

independent components of the elastic tensor of a hexagonal material

Returns:

cijndarray

6x6 matrix with elastic constants

class xrayutilities.materials.material.Material(name, cij=None)

Bases: ABC

base class for all Materials. common properties of amorphous and crystalline materials are described by this class from which Amorphous and Crystal are derived from.

GetStrain(sig)

Obtains the strain matrix (3x3) from an applied stress matrix (3x3) using a material’s full rank elastic tensor (3x3x3x3). The full stress matrix (3x3) needs to be given. The results can then be used as an input in ApplyStrain. Inverse operation of GetStress.

Parameters:

siglist, tuple or array-like

stress matrix (3x3) in N/m^2

GetStress(eps)

Obtains the strain matrix (3x3) from an applied stress matrix (3x3) using a material’s full rank elastic tensor (3x3x3x3). The full stress matrix (3x3) needs to be given. Inverse operation of GetStrain.

Parameters:

epslist, tuple or array-like

strain matrix (3x3)

__init__(name, cij=None)

absorption_length(en='config')

wavelength dependent x-ray absorption length defined as mu = lambda/(2*pi*2*beta) with lambda and beta as the x-ray wavelength and complex part of the refractive index respectively.

Parameters:

enfloat or str, optional

energy of the x-rays in eV

Returns:

float

the absorption length in um

chi0(en='config')

calculates the complex chi_0 values often needed in simulations. They are closely related to delta and beta (n = 1 + chi_r0/2 + i*chi_i0/2 vs. n = 1 - delta + i*beta)

critical_angle(en='config', deg=True)

calculate critical angle for total external reflection

Parameters:

enfloat or str, optional

energy of the x-rays in eV, if omitted the value from the xrayutilities configuration is used

degbool, optional

return angle in degree if True otherwise radians (default:True)

Returns:

float

Angle of total external reflection

abstract delta(en='config')

abstract method which every implementation of a Material has to override

property density

abstract ibeta(en='config')

abstract method which every implementation of a Material has to override

idx_refraction(en='config')

function to calculate the complex index of refraction of a material in the x-ray range

Parameters:

enenergy of the x-rays, if omitted the value from the

xrayutilities configuration is used

Returns:

n (complex)

property lam

property mu

property nu

poisson_ratio(direction, perpendicular)

Obtain the Poisson ratio for a certain extenstion direction and one perpendicular direction.

Parameters:

direction: vector (array of length 3)

Axial extension direction.

perpendicular: vector

Lateral contraction direction.

Returns:

Poisson ratio

youngs_modulus(direction, sijkl=None)

Obtain Youngs Modulus for a certain direction

Parameters:

direction: vector (array of length 3)

Vectorial direction for this the Youngs modulus should be obtained. This does not need to be normalized.

Returns:

Youngs modulus in Pa

xrayutilities.materials.material.MonoclinicElasticTensor(c11, c12, c13, c16, c22, c23, c26, c33, c36, c44, c45, c55, c66)

Assemble the 6x6 matrix of elastic constants for a monoclinic material from the thirteen independent components of a monoclinic crystal

Parameters:

c11, c12, c13, c16, c22, c23, c26, c33, c36, c44, c45, c55, c66float

independent components of the elastic tensor of monoclinic materials

Returns:

cijndarray

6x6 matrix with elastic constants

xrayutilities.materials.material.PseudomorphicMaterial(sub, layer, relaxation=0, trans=None)

This function returns a material whos lattice is pseudomorphic on a particular substrate material. The two materials must have similar unit cell definitions for the algorithm to work correctly, i.e. it does not work for combiniations of materials with different lattice symmetry. It is also crucial that the layer object includes values for the elastic tensor.

Parameters:

subCrystal

substrate material

layerCrystal

bulk material of the layer, including its elasticity tensor

relaxationfloat, optional

degree of relaxation 0: pseudomorphic, 1: relaxed (default: 0)

transTranform

Transformation which transforms lattice directions into a surface orientated coordinate frame (x, y inplane, z out of plane). If None a (001) surface geometry of a cubic material is assumed.

Returns:

An instance of Crystal holding the new pseudomorphically

strained material.

Raises:

InputError

If the layer material has no elastic parameters

xrayutilities.materials.material.TrigonalElasticTensor(c11, c12, c13, c14, c15, c33, c44)

Assemble the 6x6 matrix of elastic constants for a trigonal material from the seven independent components of a trigonal crystal

Parameters:

c11, c12, c13, c14, c15, c33, c44float

independent components of the elastic tensor of trigonal materials

Returns:

cijndarray

6x6 matrix with elastic constants

xrayutilities.materials.material.WZTensorFromCub(c11ZB, c12ZB, c44ZB)

Determines the hexagonal elastic tensor from the values of the cubic elastic tensor under the assumptions presented in Phys. Rev. B 6, 4546 (1972), which are valid for the WZ <-> ZB polymorphs.

Parameters:

c11, c12, c44float

independent components of the elastic tensor of cubic materials

Returns:

cijndarray

6x6 matrix with elastic constants

Implementation according to a patch submitted by Julian Stangl

xrayutilities.materials.material.check_symmetric(matrix)

xrayutilities.materials.material.index_map_ij2ijkl(ij)

xrayutilities.materials.material.index_map_ijkl2ij(i, j)

xrayutilities.materials.plot module

xrayutilities.materials.plot.show_reciprocal_space_plane(mat, exp, ttmax=None, maxqout=0.01, scalef=100, ax=None, color=None, show_Laue=True, show_legend=True, projection='perpendicular', label=None, **kwargs)

show a plot of the coplanar diffraction plane with peak positions for the respective material. the size of the spots is scaled with the strength of the structure factor

Parameters:

mat: Crystal

instance of Crystal for structure factor calculations

exp: Experiment

instance of Experiment (needs to be HXRD, or FourC for onclick action to work correctly). defines the inplane and out of plane direction as well as the sample azimuth

ttmax: float, optional

maximal 2Theta angle to consider, by default 180deg

maxqout: float, optional

maximal out of plane q for plotted Bragg peaks as fraction of exp.k0

scalef: float, or callable, optional

scale factor or function for the marker size. If this is a function it should take only one float argument and return another float which is used as ‘s’ parameter in matplotlib.pyplot.scatter

ax: matplotlib.Axes, optional

matplotlib Axes to use for the plot, useful if multiple materials should be plotted in one plot

color: matplotlib color, optional

show_Laue: bool, optional

flag to indicate if the Laue zones should be indicated

show_legend: bool, optional

flag to indiate if a legend should be shown

projection: ‘perpendicular’, ‘polar’, optional

type of projection for Bragg peaks which do not fall into the diffraction plane. ‘perpendicular’ (default) uses only the inplane component in the scattering plane, whereas ‘polar’ uses the vectorial absolute value of the two inplane components. See also the ‘maxqout’ option.

label: None or str, optional

label to be used for the legend. If ‘None’ the name of the material will be used.

kwargs: optional

kwargs are forwarded to matplotlib.pyplot.scatter and allow to change the appearance of the points.

Returns:

Axes, plot_handle

xrayutilities.materials.predefined_materials module

class xrayutilities.materials.predefined_materials.AlGaAs(x)

Bases: CubicAlloy

__init__(x)

Al_{1-x} Ga_x As cubic compound

class xrayutilities.materials.predefined_materials.SiGe(x)

Bases: CubicAlloy

__init__(x)

Si_{1-x} Ge_x cubic compound

static lattice_const_AB(latA, latB, x)

method to calculate the lattice parameter of the SiGe alloy with composition Si_{1-x}Ge_x

xrayutilities.materials.spacegrouplattice module

module handling crystal lattice structures. A SGLattice consists of a space group number and the position of atoms specified as Wyckoff positions along with their parameters. Depending on the space group symmetry only certain parameters of the resulting instance will be settable! A cubic lattice for example allows only to set its ‘a’ lattice parameter but none of the other unit cell shape parameters.

class xrayutilities.materials.spacegrouplattice.SGLattice(sgrp, *args, **kwargs)

Bases: object

lattice object created from the space group number and corresponding unit cell parameters. atoms in the unit cell are specified by their Wyckoff position and their free parameters.

ApplyStrain(eps)

Applies a certain strain on a lattice. The result is a change in the base vectors. The full strain matrix (3x3) needs to be given.

Note

Here you specify the strain and not the stress -> NO elastic response of the material will be considered!

Note

Although the symmetry of the crystal can be lowered by this operation the spacegroup remains unchanged! The ‘free_parameters’ attribute is, however, updated to mimic the possible reduction of the symmetry.

Parameters:

epsarray-like

a 3x3 matrix with all strain components

property B

GetHKL(*args)

determine the Miller indices of the given reciprocal lattice points

GetPoint(*args)

determine lattice points with indices given in the argument

Examples

>>> import xrayutilities as xu
>>> xu.materials.Si.lattice.GetPoint(0, 0, 4)
array([ 0.     ,  0.     , 21.72416])

or

>>> xu.materials.Si.lattice.GetPoint((1, 1, 1))
array([5.43104, 5.43104, 5.43104])

GetQ(*args)

determine the reciprocal lattice points with indices given in the argument

UnitCellVolume()

function to calculate the unit cell volume of a lattice (angstrom^3)

__init__(sgrp, *args, **kwargs)

initialize class with space group number and atom list

Parameters:

sgrpint or str

Space group number

*argsfloat

space group parameters. depending on the space group number this are 1 (cubic) to 6 (triclinic) parameters. cubic : a (lattice parameter). hexagonal : a, c. trigonal : a, c. tetragonal : a, c. orthorhombic : a, b, c. monoclinic : a, b, c, beta (in degree). triclinic : a, b, c, alpha, beta, gamma (in degree).

atomslist, optional

list of elements either as Element object or string with the element name. If you specify atoms you have to also give the same number of Wyckoff positions

poslist, optional

list of the atomic positions within the unit cell. This can be given as Wyckoff position along with its parameters or any position of an atom which will be used to identify the Wyckoff position. If a position has no free parameter the parameters can be omitted. Example: [(‘2i’, (0.1, 0.2, 0.3)), ‘1a’, (0, 0.5, 0)]

occlist, optional

site occupation for the atoms. This is optional and defaults to 1 if not given.

blist, optional

b-factor of the atom used as exp(-b*q**2/(4*pi)**2) to reduce the intensity of this atom (only used in case of temp=0 in StructureFactor and chi calculation)

property a

property ai

property alpha

property b

base()

generator of atomic position within the unit cell.

property beta

property c

convert_to_P1()

create a P1 equivalent of this SGLattice instance.

Returns:

SGLattice

instance with the same properties as the present lattice, however, in the P1 setting.

equivalent_hkls(hkl)

returns a list of equivalent hkl peaks depending on the crystal system

findsym()

method to return the highest symmetry description of the current material. This method does not consider to change the unit cell dimensions but only searches the highest symmetry spacegroup which with the current unit cell setting can be described. It is therefore not an implementation of FINDSYM [1].

Returns:

new SGLattice-instance

a new SGLattice instance is returned with the highest available symmetry description. (see restrictions above)

[1] https://stokes.byu.edu/iso/findsym.php

property gamma

get_allowed_hkl(qmax)

return a set of all allowed reflections up to a maximal specified momentum transfer.

Parameters:

qmaxfloat

maximal momentum transfer

Returns:

hklsetset

set of allowed hkl reflections

hkl_allowed(hkl, returnequivalents=False)

check if Bragg reflection with Miller indices hkl can exist according to the reflection conditions. If no reflection conditions are available this function returns True for all hkl values!

Parameters:

hkltuple or list

Miller indices of the reflection to check

returnequivalentsbool, optional

If True all the equivalent Miller indices of hkl are returned in a set as second return argument.

Returns:

allowedbool

True if reflection can have non-zero structure factor, false otherwise

equivalentsset, optional

set of equivalent Miller indices if returnequivalents is True

property iscentrosymmetric

returns a boolean to determine if the lattice has centrosymmetry.

isequivalent(hkl1, hkl2)

determining if hkl1 and hkl2 are two crystallographical equivalent pairs of Miller indices. Note that this function considers the effect of non-centrosymmetry!

Parameters:

hkl1, hkl2list

Miller indices to be checked for equivalence

Returns:

bool

reflection_conditions()

return string of reflection conditions, both general (from space group) and of Wyckoff positions

property symops

return the set of symmetry operations from the general Wyckoff position of the space group.

transform(mat, origin)

Transform the unit cell with the matrix and origin shift given in the parameters. This function returns a new instance of SGLattice which contains the highest possible symmetry description of the transformed unit cell. After the transformation (see [1]) the findsym method is used to create the new SGLattice instance.

Parameters:

mat(3, 3) list, or ndarray, optional

transformation matrix of the unit cell. The matrix definition aims to be consistent with what is used on the Bilbao Crystallographic Server [1]. This only defines the linear part, while the origin shift is given by origin.

origin(3, ) list, or ndarray

origin shift of the unit cell [1].

[1] https://www.cryst.ehu.es/cgi-bin/cryst/programs/nph-doc-trmat

class xrayutilities.materials.spacegrouplattice.SymOp(D, t, m=1)

Bases: object

Class descriping a symmetry operation in a crystal. The symmetry operation is characterized by a 3x3 transformation matrix as well as a 3-vector describing a translation. For magnetic symmetry operations also the time reversal symmetry can be specified (not used in xrayutilities)

property D

transformation matrix of the symmetry operation

__init__(D, t, m=1)

Initialize the symmetry operation

Parameters:

Darray-like

transformation matrix (3x3)

tarray-like

translation vector (3)

mint, optional

indicates time reversal in magnetic groups. +1 (default, no time reveral) or -1

apply(vec, foldback=True)

apply_axial(vec)

apply_rotation(vec)

combine(other)

static foldback(v)

classmethod from_xyz(xyz)

create a SymOp from the xyz notation typically used in CIF files.

Parameters:

xyzstr

string describing the symmetry operation (e.g. ‘-y, -x, z’)

property t

translation vector of the symmetry operation

xyz(showtimerev=False)

return the symmetry operation in xyz notation

class xrayutilities.materials.spacegrouplattice.WyckoffBase(*args, **kwargs)

Bases: list

The WyckoffBase class implements a container for a set of Wyckoff positions that form the base of a crystal lattice. An instance of this class can be treated as a simple container object.

__init__(*args, **kwargs)

append(atom, pos, occ=1.0, b=0.0)

add new Atom to the lattice base

Parameters:

atomAtom

object to be added

postuple or str

Wyckoff position of the atom, along with its parameters. Examples: (‘2i’, (0.1, 0.2, 0.3)), or ‘1a’

occfloat, optional

occupancy (default=1.0)

bfloat, optional

b-factor of the atom used as exp(-b*q**2/(4*pi)**2) to reduce the intensity of this atom (only used in case of temp=0 in StructureFactor and chi calculation)

static entry_eq(e1, e2)

compare two entries including all its properties to be equal

Parameters:

e1, e2: tuple

tuples with length 4 containing the entries of WyckoffBase which should be compared

index(item)

return the index of the atom (same element, position, and Debye Waller factor). The occupancy is not checked intentionally. If the item is not present a ValueError is raised.

Parameters:

itemtuple or list

WyckoffBase entry

Returns:

int

static pos_eq(pos1, pos2)

compare Wyckoff positions

Parameters:

pos1, pos2: tuple

tuples with Wyckoff label and optional parameters

xrayutilities.materials.spacegrouplattice.get_default_sgrp_suf(sgrp_nr)

determine default space group suffix

xrayutilities.materials.spacegrouplattice.get_possible_sgrp_suf(sgrp_nr)

determine possible space group suffix. Multiple suffixes might be possible for one space group due to different origin choice, unique axis, or choice of the unit cell shape.

Parameters:

sgrp_nrint

space group number

Returns:

str or list

either an empty string or a list of possible valid suffix strings

xrayutilities.materials.spacegrouplattice.get_wyckpos(sgrp, atompos)

test all Wyckoff positions on every atomic position

Parameters:

sgrpstr

space group name

atomposlist

list of atomic positions to identify. All atomic positions are expected to belong to one and the same Wyckoff position!

Returns:

position argument for WyckoffBase.append

xrayutilities.materials.spacegrouplattice.testwp(parint, wyckpos, cifpos, digits=8)

test if a Wyckoff position can describe the given position from a CIF file

Parameters:

parintint

telling which Parameters the given Wyckoff position has

wyckposstr or tuple

expression of the Wyckoff position

cifposlist, or tuple or array-like

(x, y, z) position of the atom in the CIF file

digitsint

number of digits for which for a comparison of floating point numbers will be rounded to. By default xu.config.DIGITS is used.

Returns:

foundflagbool

flag to tell if the positions match

parsarray-like or None

parameters associated with the position or None if no parameters are needed

xrayutilities.materials.wyckpos module

class xrayutilities.materials.wyckpos.RangeDict

Bases: dict

Dictionary type which uses range as keys

Module contents