hexrd.material.crystallography module

hexrd.material.crystallography.LoadFormFactorData()

Script to read in a csv file containing information relating the magnitude of Q (sin(th)/lambda) to atomic form factor

Notes: Atomic form factor data gathered from the International Tables of Crystallography:

16. 10. Brown, A. G. Fox, E. N. Maslen, M. A. O’Keefec and B. T. M. Willis,

“Chapter 6.1. Intensity of diffracted intensities”, International Tables

for Crystallography (2006). Vol. C, ch. 6.1, pp. 554-595

class hexrd.material.crystallography.PlaneData(hkls, *args, **kwargs)

Bases: object

Careful with ordering: Outputs are ordered by the 2-theta for the hkl unless you get self.__hkls directly, and this order can change with changes in lattice parameters (lparms); setting and getting exclusions works on the current hkl ordering, not the original ordering (in self.__hkls), but exclusions are stored in the original ordering in case the hkl ordering does change with lattice parameters

if not None, tThWidth takes priority over strainMag in setting two-theta ranges; changing strainMag automatically turns off tThWidth

calcStructFactor(atominfo)

Calculates unit cell structure factors as a function of hkl

USAGE:

FSquared = calcStructFactor(atominfo,hkls,B)

INPUTS:

1) atominfo (m x 1 float ndarray) the first threee columns of the matrix contain fractional atom positions [uvw] of atoms in the unit cell. The last column contains the number of electrons for a given atom

2) hkls (3 x n float ndarray) is the array of Miller indices for the planes of interest. The vectors are assumed to be concatenated along the 1-axis (horizontal)

3) B (3 x 3 float ndarray) is a matrix of reciprocal lattice basis vectors,where each column contains a reciprocal lattice basis vector ({g}=[B]*{hkl})

OUTPUTS:

1) FSquared (n x 1 float ndarray) array of structure factors, one for each hkl passed into the function

exclude(dmin=None, dmax=None, tthmin=None, tthmax=None, sfacmin=None, sfacmax=None, pintmin=None, pintmax=None)

Set exclusions according to various parameters

Any hkl with a value below any min or above any max will be excluded. So to be included, an hkl needs to have values between the min and max for all of the conditions given.

Note that method resets the tThMax attribute to None.

PARAMETERS

dmin: float > 0

minimum lattice spacing (angstroms)

dmax: float > 0

maximum lattice spacing (angstroms)

tthmin: float > 0

minimum two theta (radians)

tthmax: float > 0

maximum two theta (radians)

sfacmin: float > 0

minimum structure factor as a proportion of maximum

sfacmax: float > 0

maximum structure factor as a proportion of maximum

pintmin: float > 0

minimum powder intensity as a proportion of maximum

pintmax: float > 0

maximum powder intensity as a proportion of maximum

property exclusions

getCentroSymHKLs()

getDD_tThs_lparms()

derivatives of tThs with respect to lattice parameters; have not yet done coding for analytic derivatives, just wimp out and finite difference

getHKLID(hkl, master=False)

Return the unique ID of a list of hkls.

Parameters

hklint | tuple | list | numpy.ndarray

The input hkl. If an int, or a list of ints, it just passes through (FIXME). If a tuple, treated as a single (h, k, l). If a list of lists/tuples, each is treated as an (h, k, l). If an numpy.ndarray, it is assumed to have shape (3, N) with the N (h, k, l) vectors stacked column-wise

masterbool, optional

If True, return the master hklID, else return the index from the external (sorted and reduced) list.

Returns

retvallist

The list of requested hklID values associate with the input.

Notes

TODO: revisit this weird API???

Changes:

2020-05-21 (JVB) – modified to handle all symmetric equavlent reprs.

getHKLs(*hkl_ids, **kwargs)

Returns the powder HKLs subject to specified options.

Parameters

*hkl_idsint

Optional list of specific master hklIDs.

**kwargsdict

One or more of the following keyword arguments:

asStrbool

If True, return a list of strings. The default is False.

thisTThscalar | None

If not None, only return hkls overlapping the specified 2-theta (in radians). The default is None.

allHKLsbool

If True, then ignore exlcusions. The default is False.

Raises

TypeError

If an unknown kwarg is passed.

RuntimeError

If an invalid hklID is passed.

Returns

retvallist | numpy.ndarray

Either a list of hkls as strings (if asStr=True) or a vstacked array of hkls.

Notes

!!! the shape of the return value when asStr=False is the _transpose_

of the typical return value for self.get_hkls() and self.hkls! This _may_ change to avoid confusion, but going to leave it for now so as not to break anything.

2022/08/05 JVB:

• Added functionality to handle optional hklID args

• Updated docstring

getLatticeType()

This is the lattice type

getLaueGroup()

This is the Schoenflies tag

getMergedRanges(cullDupl=False)

return indices and ranges for specified planeData, merging where there is overlap based on the tThWidth and line positions

getMultiplicity(allHKLs=False)

getNHKLs()

getNhklRef()

does not use exclusions or the like

getParams()

getPhaseID()

may return None if not set

getPlaneNormals()

gets both +(hkl) and -(hkl) normals

getPlaneSpacings()

gets plane spacings

getQSym()

getSymHKLs(asStr=False, withID=False, indices=None)

new function that returns all symmetric hkls

getTTh(lparms=None, allHKLs=False)

getTThRanges(strainMag=None, lparms=None)

Return 2-theta ranges for included hkls

return array is n x 2

get_exclusions()

get_hkls()

do not do return self.__hkls, as everywhere else hkls are returned in 2-theta order; transpose is to comply with lparm convention

get_lparms()

get_strainMag()

get_structFact()

get_tThMax()

get_wavelength()

property hedm_intensity

property hkls

do not do return self.__hkls, as everywhere else hkls are returned in 2-theta order; transpose is to comply with lparm convention

invalidate_structure_factor(unitcell)

property latVecOps

gets lattice vector operators as a new (deepcopy)

property laueGroup

This is the Schoenflies tag

property lparms

makeAllScatteringVectors(rMat, bMat=None, wavelength=None, chiTilt=None)

makeNew()

static makePlaneData(hkls, lparms, qsym, symmGroup, strainMag, wavelength)

hkls : need to work with crystallography.latticePlanes lparms : need to work with crystallography.latticePlanes laueGroup : see symmetry module wavelength : wavelength strainMag : swag of strian magnitudes

static makeScatteringVectors(hkls, rMat_c, bMat, wavelength, chiTilt=None)

Static method for calculating g-vectors and scattering vector angles for specified hkls, subject to the bragg conditions specified by lattice vectors, orientation matrix, and wavelength

FIXME: must do testing on strained bMat

makeTheseScatteringVectors(hklList, rMat, bMat=None, wavelength=None, chiTilt=None)

property powder_intensity

setLaueGroup(laueGroup)

set_exclusions(exclusions)

set_hkls(hkls)

set_laue_and_lparms(laueGroup, lparms)

Set the Laue group and lattice parameters simultaneously

When the Laue group changes, the lattice parameters may be incompatible, and cause an error in self.__calc(). This function allows us to update both the Laue group and lattice parameters simultaneously to avoid this issue.

set_lparms(lparms)

set_strainMag(strainMag)

set_structFact(structFact)

set_tThMax(tThMax)

set_wavelength(wavelength)

property strainMag

property structFact

property tThMax

property wavelength

hexrd.material.crystallography.RetrieveAtomicFormFactor(elecNum, magG, sinThOverLamdaList, ffDataList)

Interpolates between tabulated data to find the atomic form factor for an atom with elecNum electrons for a given magnitude of Q

USAGE:

ff = RetrieveAtomicFormFactor(elecNum,magG,sinThOverLamdaList,ffDataList)

INPUTS:

1. elecNum, (1 x 1 float) number of electrons for atom of interest

2. magG (1 x 1 float) magnitude of G

3. sinThOverLamdaList (n x 1 float ndarray) form factor data is tabulated in terms of sin(theta)/lambda (A^-1).

3. ffDataList (n x m float ndarray) form factor data is tabulated in terms of sin(theta)/lambda (A^-1). Each column corresponds to a different number of electrons

OUTPUTS:

1. ff (n x 1 float) atomic form factor for atom and hkl of interest

NOTES: Data should be calculated in terms of G at some point

hexrd.material.crystallography.convert_MillerBravias_direction_to_Miller(UVW)

Converts 4-index hexagonal Miller-Bravais direction indices to 3-index Miller direction indices.

Parameters

UVWarray_like

The (n, 3) array of non-redundant Miller-Bravais direction indices to convert.

Returns

numpy.ndarray

The (n, 3) array of Miller direction indices associated with the input Miller-Bravais indices.

Notes

• NOT for plane normals!!!

hexrd.material.crystallography.convert_Miller_direction_to_MillerBravias(uvw, suppress_redundant=True)

Converts 3-index hexagonal Miller direction indices to 4-index Miller-Bravais direction indices.

Parameters

uvwarray_like

The (n, 3) array of 3-index hexagonal Miller indices to convert.

suppress_redundantbool, optional

Flag to suppress the redundant 3rd index. The default is True.

Returns

numpy.ndarray

The (n, 3) or (n, 4) array – depending on kwarg – of Miller-Bravis components associated with the input Miller direction indices.

Notes

• NOT for plane normals!!!

hexrd.material.crystallography.convert_Miller_direction_to_cartesian(uvw, a=1.0, c=1.0, normalize=False)

Converts 3-index hexagonal Miller direction indices to components in the crystal reference frame.

Parameters

uvwarray_like

The (n, 3) array of 3-index hexagonal indices to convert.

ascalar, optional

The a lattice parameter. The default value is 1.

cscalar, optional

The c lattice parameter. The default value is 1.

normalizebool, optional

Flag for whether or not to normalize output vectors

Returns

numpy.ndarray

The (n, 3) array of cartesian components associated with the input direction indices.

Notes

1. The [uv.w] the Miller-Bravais convention is in the hexagonal basis {a1, a2, a3, c}. The basis for the output, {o1, o2, o3}, is chosen such that

   o1 || a1 o3 || c o2 = o3 ^ o1

hexrd.material.crystallography.cosineXform(a, b, c)

Spherical trig transform to take alpha, beta, gamma to expressions for cos(alpha*). See ref below.

[1] R. J. Neustadt, F. W. Cagle, Jr., and J. Waser, ``Vector algebra and

the relations between direct and reciprocal lattice quantities’’. Acta Cryst. (1968), A24, 247–248

hexrd.material.crystallography.getDparms(lp, lpTag, radians=True)

Utility routine for getting dparms, that is the lattice parameters without symmetry – ‘triclinic’

hexrd.material.crystallography.getFriedelPair(tth0, eta0, *ome0, **kwargs)

Get the diffractometer angular coordinates in degrees for the Friedel pair of a given reflection (min angular distance).

AUTHORS:

10. 22. Bernier – 10 Nov 2009

USAGE:

ome1, eta1 = getFriedelPair(tth0, eta0, *ome0,

display=False, units=’degrees’, convention=’hexrd’)

INPUTS:

1. tth0 is a list (or ndarray) of 1 or n the bragg angles (2theta) for the n reflections (tiled to match eta0 if only 1 is given).

2. eta0 is a list (or ndarray) of 1 or n azimuthal coordinates for the n reflections (tiled to match tth0 if only 1 is given).

3. ome0 is a list (or ndarray) of 1 or n reference oscillation angles for the n reflections (denoted omega in [1]). This argument is optional.

4. Keyword arguments may be one of the following:

Keyword Values|{default} Action ————– ————– ————– ‘display’ True|{False} toggles display to cmd line ‘units’ ‘radians’|{‘degrees’} sets units for input angles ‘convention’ ‘fable’|{‘hexrd’} sets conventions defining

the angles (see below)

‘chiTilt’ None the inclination (about Xlab) of

the oscillation axis

OUTPUTS:

1. ome1 contains the oscialltion angle coordinates of the Friedel pairs associated with the n input reflections, relative to ome0 (i.e. ome1 = <result> + ome0). Output is in DEGREES!

2. eta1 contains the azimuthal coordinates of the Friedel pairs associated with the n input reflections. Output units are controlled via the module variable ‘outputDegrees’

NOTES:

!!!: The ouputs ome1, eta1 are written using the selected convention, but

the units are alway degrees. May change this to work with Nathan’s global…

!!!: In the ‘fable’ convention [1], {XYZ} form a RHON basis where X is

downstream, Z is vertical, and eta is CCW with +Z defining eta = 0.

!!!: In the ‘hexrd’ convention [2], {XYZ} form a RHON basis where Z is

upstream, Y is vertical, and eta is CCW with +X defining eta = 0.

REFERENCES:

[1] E. M. Lauridsen, S. Schmidt, R. M. Suter, and H. F. Poulsen,

``Tracking: a method for structural characterization of grains in powders or polycrystals’’. J. Appl. Cryst. (2001). 34, 744–750

[2] J. V. Bernier, M. P. Miller, J. -S. Park, and U. Lienert,

``Quantitative Stress Analysis of Recrystallized OFHC Cu Subject to Deformed In Situ’’, J. Eng. Mater. Technol. (2008). 130. DOI:10.1115/1.2870234

hexrd.material.crystallography.hexagonalIndicesFromRhombohedral(hkl)

converts rhombohedral hkl to hexagonal indices

hexrd.material.crystallography.hklToStr(x)

hexrd.material.crystallography.latticeParameters(lvec)

Generates direct and reciprocal lattice vector components in a crystal-relative RHON basis, X. The convention for fixing X to the lattice is such that a || x1 and c* || x3, where a and c* are direct and reciprocal lattice vectors, respectively.

hexrd.material.crystallography.latticePlanes(hkls, lparms, ltype='cubic', wavelength=1.54059292, strainMag=None)

Generates lattice plane data in the direct lattice for a given set of Miller indices. Vector components are written in the crystal-relative RHON basis, X. The convention for fixing X to the lattice is such that a || x1 and c* || x3, where a and c* are direct and reciprocal lattice vectors, respectively.

USAGE:

planeInfo = latticePlanes(hkls, lparms, **kwargs)

INPUTS:

1. hkls (3 x n float ndarray) is the array of Miller indices for the planes of interest. The vectors are assumed to be concatenated along the 1-axis (horizontal).

2. lparms (1 x m float list) is the array of lattice parameters, where m depends on the symmetry group (see below).

3. The following optional keyword arguments are recognized:

   *) ltype=(string) is a string representing the symmetry type of

   the implied Laue group. The 11 available choices are shown below. The default value is ‘cubic’. Note that each group expects a lattice parameter array of the indicated length and order.

   latticeType lparms ———– ———— ‘cubic’ a ‘hexagonal’ a, c ‘trigonal’ a, c ‘rhombohedral’ a, alpha (in degrees) ‘tetragonal’ a, c ‘orthorhombic’ a, b, c ‘monoclinic’ a, b, c, beta (in degrees) ‘triclinic’ a, b, c, alpha, beta, gamma (in degrees)

   *) wavelength=<float> is a value represented the wavelength in

   Angstroms to calculate bragg angles for. The default value is for Cu K-alpha radiation (1.54059292 Angstrom)

   *) strainMag=None

OUTPUTS:

1. planeInfo is a dictionary containing the following keys/items:

   normals (3, n) double array array of the components to the

   unit normals for each {hkl} in X (horizontally concatenated)

   dspacings (n, ) double array array of the d-spacings for

   each {hkl}

   2thetas (n, ) double array array of the Bragg angles for

   each {hkl} relative to the specified wavelength

NOTES:

*) This function is effectively a wrapper to ‘latticeVectors’.

See ‘help(latticeVectors)’ for additional info.

*) Lattice plane d-spacings are calculated from the reciprocal

lattice vectors specified by {hkl} as shown in Appendix 1 of [1].

REFERENCES:

[1] B. D. Cullity, ``Elements of X-Ray Diffraction, 2

ed.’’. Addison-Wesley Publishing Company, Inc., 1978. ISBN 0-201-01174-3

hexrd.material.crystallography.latticeVectors(lparms, tag='cubic', radians=False, debug=False)

Generates direct and reciprocal lattice vector components in a crystal-relative RHON basis, X. The convention for fixing X to the lattice is such that a || x1 and c* || x3, where a and c* are direct and reciprocal lattice vectors, respectively.

USAGE:

lattice = LatticeVectors(lparms, <symmTag>)

INPUTS:

1. lparms (1 x n float list) is the array of lattice parameters, where n depends on the symmetry group (see below).

2. symTag (string) is a case-insensitive string representing the symmetry type of the implied Laue group. The 11 available choices are shown below. The default value is ‘cubic’. Note that each group expects a lattice parameter array of the indicated length and order.

   latticeType lparms ———– ———— ‘cubic’ a ‘hexagonal’ a, c ‘trigonal’ a, c ‘rhombohedral’ a, alpha (in degrees) ‘tetragonal’ a, c ‘orthorhombic’ a, b, c ‘monoclinic’ a, b, c, beta (in degrees) ‘triclinic’ a, b, c, alpha, beta, gamma (in degrees)

OUTPUTS:

1. lattice is a dictionary containing the following keys/items:

   F (3, 3) double array transformation matrix taking

   componenents in the direct lattice (i.e. {uvw}) to the reference, X

   B (3, 3) double array transformation matrix taking

   componenents in the reciprocal lattice (i.e. {hkl}) to X

   BR (3, 3) double array transformation matrix taking

   componenents in the reciprocal lattice to the Fable reference frame (see notes)

   U0 (3, 3) double array transformation matrix

   (orthogonal) taking componenents in the Fable reference frame to X

   vol double the unit cell volume

   dparms (6, ) double list the direct lattice parameters:

   [a b c alpha beta gamma]

   rparms (6, ) double list the reciprocal lattice

   parameters: [a* b* c* alpha* beta* gamma*]

NOTES:

*) The conventions used for assigning a RHON basis,

X -> {x1, x2, x3}, to each point group are consistent with those published in Appendix B of [1]. Namely: a || x1 and c* || x3. This differs from the convention chosen by the Fable group, where a* || x1 and c || x3 [2].

*) The unit cell angles are defined as follows:

alpha=acos(b’*c/|b||c|), beta=acos(c’*a/|c||a|), and gamma=acos(a’*b/|a||b|).

*) The reciprocal lattice vectors are calculated using the

crystallographic convention, where the prefactor of 2*pi is omitted. In this convention, the reciprocal lattice volume is 1/V.

*) Several relations from [3] were employed in the component

calculations.

REFERENCES:

[1] J. F. Nye, ``Physical Properties of Crystals: Their

Representation by Tensors and Matrices’’. Oxford University Press, 1985. ISBN 0198511655

[2] E. M. Lauridsen, S. Schmidt, R. M. Suter, and H. F. Poulsen,

``Tracking: a method for structural characterization of grains in powders or polycrystals’’. J. Appl. Cryst. (2001). 34, 744–750

[3] R. J. Neustadt, F. W. Cagle, Jr., and J. Waser, ``Vector

algebra and the relations between direct and reciprocal lattice quantities’’. Acta Cryst. (1968), A24, 247–248

hexrd.material.crystallography.lorentz_factor(tth)

05/26/2022 SS adding lorentz factor computation to the detector so that it can be compenstated for in the intensity correction

parameters: tth two theta of every pixel in radians

hexrd.material.crystallography.polarization_factor(tth, unpolarized=True, eta=None, f_hor=None, f_vert=None)

06/14/2021 SS adding lorentz polarization factor computation to the detector so that it can be compenstated for in the intensity correction

05/26/2022 decoupling lorentz factor from polarization factor

parameters: tth two theta of every pixel in radians

if unpolarized is True, all subsequent arguments are optional eta azimuthal angle of every pixel f_hor fraction of horizontal polarization (~1 for XFELs) f_vert fraction of vertical polarization (~0 for XFELs)

notice f_hor + f_vert = 1

hexrd.material.crystallography.processWavelength(arg)

Convert an energy value to a wavelength. If argument has units of length or energy, will convert to globally specified unit type for wavelength (dUnit). If argument is a scalar, assumed input units are keV.

hexrd.material.crystallography.revertOutputDegrees()

hexrd.material.crystallography.rhombohedralIndicesFromHexagonal(HKL)

converts hexagonal hkl to rhombohedral indices

hexrd.material.crystallography.rhombohedralParametersFromHexagonal(a_h, c_h)

converts hexagonal lattice parameters (a, c) to rhombohedral lattice parameters (a, alpha)

hexrd.material.crystallography.tempSetOutputDegrees(val)