pyemaps.crystals module¶

class pyemaps.crystals.DW(value)¶

Bases: Enum

Enumerated thermal property of crystal supported by pyemaps

iso: Isotropic Debye-Waller Factor B (short for Isotropic)
bij: Anisotropic Temperature Factor
uij: Anisotropic Displacement Factor

iso = 1¶

bij = 2¶

uij = 3¶

class pyemaps.crystals.Cell(data=None)¶

Bases: object

Cell constant data class create and validate crystal unit cell lengths (a, b, c) and angles (alpha, beta, gamma).

To create a Cell object using the following python dict object:

{
    "a": "5.4307",
    "b": "5.4307",
    "c": "5.4307",
    "alpha": "90.0",
    "beta": "90.0",
    "gamma": "90.0"
}

from pyemaps import Cell

si_cell = Cell(data = data_dict)

To create a Cell object using the following python list:

from pyemaps import Cell

data_list = ["5.4307", "5.4307", "5.4307", "90.0", "90.0", "90.0"]
# or
data_list = [5.4307, 5.4307, 5.4307, 90.0, 90.0, 90.0]

si_cell = Cell(data = data_list)

To create a Cell class object by setting individual attributes:

from pyemaps import Cell

# create a Cell object with all defaults values (0.0).
si_cell = Cell()

si_cell.a = 5.4307
si_cell.b = 5.4307
si_cell.c = 5.4307
si_cell.alpha = 90.0
si_cell.beta = 90.0
si_cell.gamma = 90.0

Validation of a Cell object data fails if input value for each arribute is:

not numberal or numberal string.
length of input data is less than 6.

__init__(data=None)¶

This Cell constructor allows Cell construction with python dict and list object, as well as customization.

Parameters:: data (dict or list, optional) – Cell constant python dictionary or list
Raises:: CellValueError – if cell data validations fail.

property a¶: a cell length

property b¶: b cell length

property c¶: c cell length

property alpha¶: alpha cell angle

property beta¶: beta cell angle

property gamma¶: gamma cell angle

property session_controls¶

prepare()¶: Prepare cell constant data for loading into backend simulation modules

class pyemaps.crystals.Atom(a_type=iso.value, sym='', data=None)¶

Bases: object

Crystal atom descriptor class. Depending on the thermal types, its data include atom symbol, positional data (x, y, z) and thermal coefficients as well as its occupancy.

To create an isotropic Atom object with a python dict object:

{
    "symb": "Si",
    "x": "0.125",
    "y": "0.125",
    "z": "0.125",
    "d-w": "0.4668",
    "occ": "1.00" 
}

from pyemaps import Atom

data_dict = {
    "symb": "Si",
    "x": "0.125",
    "y": "0.125",
    "z": "0.125",
    "d-w": "0.4668",
    "occ": "1.00" 
}
si_atom = Atom(data = data_dict)

To create an isotropic Atom object with a python list object:

from pyemaps import Atom
data_list = ["0.125", "0.125", "0.125", "0.4668", "1.00"]
# or
data_list = [0.125, 0.125, 0.125, 0.4668, 1.00]

si_atom = Atom(data = data_list)

Warning

When atom positional data is entered as a python list object the order of the elements must match their corresponding keys:

['x','y','z','d-w','occ']       # for isotropic atom type
['x','y','z','b11','b22','b33','b12','b13','b23','occ']   #for anisotropic atome types

Note

The list input for atom positional data can have ‘occ’ data missing. In which case pyemaps will default its occupancy data to 1.0

To create an Atom class object by setting individual attributes:

from pyemaps import Atom
# create an Atom object with all defaults to its data members.

si_at = Atom()

si_at.symb = 'Si'
si_at.loc = [0.125, 0.125, 0.125, 0.4668, 1.00]

__init__(a_type=iso.value, sym='', data=None)¶

Internal representation of single atom in a crystal object.

Parameters:

a_type (int, optional) – Atom thermal factor type.
data (dict or list, optional) – Atoms positional and other data input.

Raises:

UCError – if data validation fails.

property atype¶: Atom symbol

property symb¶: Atom symbol

property loc¶: atomic position, thermal factor or coefficients, occupacy information

isISO()¶: Check to see if this Atom thermal type is isotropic

prepare()¶: Format Atom data and prepare it for loading into backend simulation module.

class pyemaps.crystals.SPG(data=None)¶

Bases: object

Space Group class. This class includes:

Symmetry International Tables Number, and
Symmetry Space Group Setting

It is part of Crystal objects.

To create a space group object with a python dictionary object:

from pyemaps import SPG

spg_dict = {
    "number": "227", #<---Symmetry International Tables Number
    "setting": "2"   #<---Symmetry Space Group Setting  
}

si_spg = SPG(data = spg_dict)

To create a space group object with a python integer list:

from pyemaps import SPG

spg_list = ["227", "2"] 
# or
spg_list = [227, 2]

si_spg = SPG(data = spg_list)

To create a space group object with custom data:

from pyemaps import SPG
si_spg = SPG()
si_spg.number = 227
si_spg.setting = 2

__init__(data=None)¶

SPG object constructor.

Parameters:: data (dict or list, optional) – Space group data input.
Raises:: SPGInvalidDataInputError – if cell data validations fail.

property number¶: Symmetry International Tables Number

property setting¶: Symmetry Space Group Setting

prepare()¶

class pyemaps.crystals.Crystal(name='Diamond', data=None)¶

Bases: object

This class is defined to capture and to validate crystal data. It is composed of the following data:

cell: Cell object
atoms: list of Atom objects
spg: Space Group SPG object
dw: Debye-waller factor type
name: Crystal name

Crystal class constructors include:

Crystal(name, data): python dictionary object (default)
From pyemaps built-in crystal database: from_builtin;
From a pyemaps proprietory crystal data file: from_xtl;
From Crystallographic Information File (CIF): from_cif;
From .JSON File: from_json;
From a python dict object: from_dict;
Custom from individual components such as Cell, Atom objects

To create a Crystal object using a python dictionary object:

from pyemaps import Crystal

c_dict = {'cell':                                           #Cell constants
                {
                    'a': '5.4307',
                    'b': '5.4307',
                    'c': '5.4307',
                    'alpha': '90.0',
                    'beta': '90.0',
                    'gamma': '90.0'
                },
            'atoms':                                        #atomic info.
                [
                    {'symb': 'si',                          #atom symbol
                    'x': '0.125',                           #atom coordinates
                    'y': '0.125',  
                    'z': '0.125',
                    'd-w': '0.4668',                        #Debye-waller factor
                    'occ': 1.00},                           #occupancy
                ],
            'spg':                                          #space group info
                {'number': '227'                            #symmetry international table(IT) number
                'setting': '2'                              #symmetry space group setting
                },
            'dw': 
                'iso'                                       #Debye-waller factor
            'name', 
                'Silicon'                                   #crystal name
        }

si = Crystal(name='Silicon', data = c_dict)

To create a Crystal object using pyemaps builtin crystal database:

from pyemaps import Crystal
si = Crystal.from('Silicon') 

Note

For a list of builtin crystal names, call:

Crystal.list_all_builtin_crystals()

To create a Crystal object with custom Cell, SPG and Atom objects:

from pyemaps import Cell, Atom, SPG, Crystal
cell = Cell(data = [5.4307, 5.4307, 5.4307, 90.0, 90.0, 90.0])
atom = Atom(data = [0.125, 0.125, 0.125, 0.4668, 1.00])
spg = SPG(data = [227, 2])
si = Crystal()

si.cell = cell
si.atoms = [atom,]
si.spg = spg
si.dw = iso.value
si.name = 'Silicon' 

Note

All atoms in a crystal must have the same thermal type.

__init__(name='Diamond', data=None)¶

Default constructor for crystal object

Parameters:

name (string, optional) – Name of the crystal or default to ‘Diamond’
data (dict, optional) – Other data of the crystal.

Raises:

CrystalClassError – If data validations fail.

The dictionary object example for Silicon:

{'cell':                                       
    {'a': '5.4307',
    'b': '5.4307',
    'c': '5.4307',
    'alpha': '90.0',
    'beta': '90.0',
    'gamma': '90.0'},
'atoms':                                        
    [
        {'symb': 'si',                          
        'x': '0.125',                           
        'y': '0.125',  
        'z': '0.125',
        'd-w': '0.4668',                        
        'occ': 1.00},                           
    ],
'spg':                                          
    {'number': '227'                            
    'setting': '2'                              
    },
'dw': 'iso'                                     

}

angle(v1=(1.0, 0.0, 0.0), v2=(0.0, 0.0, 1.0), ty=0)¶

Calculates angle between two real space vectors or two reciprocal space vectors

Parameters:

v1 (tuple, optional) – A vector of float coordinates
v2 (tuple, optional) – A vector of float coordinates
ty (int, optional) – 0 real space, 1 reciprocal space

Returns:

an angle between v1 and v2.

Return type:

float

beginBloch(aperture=DEF_APERTURE, omega=DEF_OMEGA, sampling=DEF_SAMPLING, dbsize=DEF_CBED_DSIZE, em_controls=EMC(cl=200, simc=SIMC(gmax=1.0, excitation=(0.3, 1.0))))¶

Begins a dynamic diffraction (Bloch) simulation session. The simulation results are retained in the session between this and endBloch call.

Parameters:

aperture (float) – Optional. Objective aperture
omega (float) – Optional. Diagnization cutoff value
sampling (int) – Optional. Number of sampling points
dbsize (float, optional) – Diffracted beams size.
em_controls (pyemaps.EMC) – Optional. electron microscope control object.

Returns:

a tuple (n, ns) where ns is a list of sampling points; n is the number of sampling points

Return type:

tuple

Default values:

DEF_APERTURE = 1.0
DEF_OMEGA = 10
DEF_SAMPLING = 8
DEF_CBED_DSIZE - 0.16
DEF_DSIZE_LIMITS =(0.01, 0.5)

Note

During the simulation session, results are retained in pyemaps bloch module. The following methods are used to retrieve the result before the end of session:

getBlochimages. Retrieve a list of bloch images
getSCMatrix. Retrieve a scattering matrix at a sampling point

Note

Other information available during the session:

List of sampling points, diffraction beams tilts etc with printIBDetails;
getEigen function is folded into getSCMatrix call starting from Stable verion 1.0.3
Diagnization Miller indexes at each sampling point: getBeams;

cleanCSF()¶: Cleans up memories used by structure factor calculation. This also includes the crystal data loaded into pyemaps’ backend simulation module.

d2r(v=(0.0, 0.0, 0.0))¶

Transform vector from real to recriprocal space

Parameters:: v (tuple, optional) – A vector of float coordinates
Returns:: a transformed vector
Return type:: tuple

endBloch()¶

Clean up Bloch module. This function follows: beginBloch

to mark the end of a dynamic simulation session.

generateBloch(aperture=DEF_APERTURE, omega=DEF_OMEGA, sampling=DEF_SAMPLING, pix_size=DEF_PIXSIZE, det_size=DEF_DETSIZE, disk_size=DEF_CBED_DSIZE, sample_thickness=DEF_THICKNESS, em_controls=EMC(cl=200, simc=SIMC(gmax=1.0, excitation=(0.3, 1.0))), nType=TY_NORMAL, bSave=False)¶

Generates dynamic diffraction (Bloch) image(s). This function is equivalent to calling :

Parameters:

aperture (float, optional) – Objective aperture.
omega (float, optional) – Diagnization cutoff value, defaults to 10.
sampling (int, optional) – Number of sampling points
pix_size (int, optional) – Detector pixel size in microns
det_size (int, optional) – Detector size or output image size
disk_size (float, optional) – Diffracted beams size in range
sample_thickness (tuple of int, optional) – Sample thickness in (start, end, step) tuple
nType (int, optional. defaults to 0) – type of bloch images generated. 0 for normal or 1 for large angle CBED images
em_controls – Microscope controls object
bSave (bool, optional) – True - save the output to a raw image file (ext: im3)

Returns:

BImgList object

Return type:

BImgList

Default values:

DEF_APERTURE = 1.0
DEF_OMEGA = 10
DEF_SAMPLING = 8
DEF_CBED_DSIZE = 0.16
DEF_DSIZE_LIMITS =(0.01, 0.5)
DEF_PIXSIZE = 25
DEF_DETSIZE = 512
DEF_THICKNESS = (200, 200, 100)

Note

There will be one slice of image generated for each sample thickness specified by sample_thickness = (start, end, step) arguement:

start, start+step … start+N*step, end

Warning

Dynamic diffraction pattern generation or Bloch has an extensive memory requirement for regular image generation:

nType = TY_NORMAL

Even more so for a large angle CBED generation when nType = TY_LACBED.

To reduce the memory needed, it is recommended to lower input parameters, particularly:

The detector size det_size. A reduction of the default value of 512 to 218 for example can reduce memory usage in pyemaps without losing accuracies of the results.
The number of sampling points in sampling. With less available memory on the system where pyemaps is running, decreased sampling points in sampling parameter can make a big difference in pyemaps performance.

generateCSF(kv=100, smax=0.5, sftype=1, aptype=0)¶

Calculates structure factors.

:param kv:Accelaration Voltage in Kilo-Volts, default value 100 :type kv: int or float, optional

Parameters:

smax (int or float, optional) – Limit of Sin(theta)/Wave length, default value 0.5
sftype (, int, optional) – Structure factor types to be generated, default value 1 - x-ray
aptype (, int, optional) – Output format type, default value 0 - amplitude and phase

Returns:

a dict object with structure factor data

Return type:

dict

Note

sftype has the following value representing:

x-ray structure factor (default)
electron structure factor in volts (KV)
electron structure factor in 1/angstrom^2 in (KV)
electron absorption structure factor in 1/angstrom^2 (KV)

Note

aptype has the following value representing structure factor format:

0: amplitude and phase 1: real and imaginary

The return of an array of structure factors in the following python dictionary format:

{
    'hkl': (h,k,l),         # Miller Indices 
    'sw': s,                # Sin(theta)/Wave length
    'ds': d,                # d-spacing value
    'amp_re': ar            # amplitude or real part 
    'phase_im': ph          # phase or imaginary part
}

generateDP(mode=None, dsize=None, em_controls=None)¶

Kinematic diffraction simulation.

Parameters:

mode (int, optional) – Mode of kinemetic diffraction - normal(1) or CBED(2).
dsize (float, optional) – diffractted beam size, only applied to CBED mode.
em_controls (pyemaps.EMC, optional) –
Microscope control object.

Returns:

A tuple (emc, dp) where emc is the microscope control and dp is a diffPattern object .

Return type:

tuple.

generateDPDB(emc=EMC(), xa=DEF_XAXIS, res=LOW_RES, vertices=DEF_VERTMAT)¶

Generate a list diffraction patterns and save them in proprietory binary formatted database file with extension .bin.

The database created will be used for diffraction pattern indexing and matchig functions in pyemaps STEM4D module.

The generated database file is saved to directory pointed by environment variable PYEMAPS_DATA or in current working directory if PYEMAPS_DATA is not set.

Parameters:

emc (EMControls, optional) – Control parameters
xa (three integer tuple.) – x-axis, optional
res (integer, defaults to 100, optional.) – resolution of stereo projection map, ranging from *LOW_RES*=100 to *HIGH_RES*=300 that is the number of sampling points along the radius. The higher the resolution, the more diffraction patterns are generated in the database file.
vertices (three integer tuple, optional) – an array of 3 or 4 zone axis indexes that form an enclosed orientation surface area within which the diffraction patterns are generated. See the following graphic illustration of the vertices input.

Returns:

a tuple of a status code and database file name

Return type:

tuple of an integer and a string

Input zone axis indexes define the vertices of the stereo projection map. The default for a cubic crystal is DEF_VERTMAT = [[0,0,1],[1,1,1],[0,1,1]].

https://github.com/emlab-solutions/imagepypy/raw/main/stereoprojectionmap.png

The diffraction patterns database file produced will be consumed by pyemaps stem4d module for experimental diffraction pattern serach and indexing.

generateDif(mode=None, dsize=None, em_controls=None)¶

Another kinematic diffraction simulation method to be deprecated in stabel production soon. Its replacement is: generateDP.

Parameters:

mode (int) – mode of kinemetic diffraction - normal(1) or CBED(2).
dsize (float) – diffractted beam size, only applied to CBED mode.
em_controls (pyemaps.EMC) – electron microscope controls object.

Returns:

myDif.

Return type:

pyemaps.DPList.

generateMxtal(trMatrix=ID_MATRIX, trShift=DEF_TRSHIFT, cellbox=DEF_CELLBOX, xz=DEF_XZ, orShift=DEF_ORSHIFT, locASpace=DEF_LOCASPACE, bound=None)¶

Generate the crystal atomic structure data in .xyz format.

Parameters:

trMatrix (array, optional) – Transformation matrix
trShift (array, optional) – Transformation shift
cellbox (array, optional) – Locate atoms inside a box defined.
xz (array, optional) – X and Z orientations in real space.
orShift (float, optional) – Origin shift.
locASpace (array, optional) – Locate atoms inside a box defined.
bound (float, optional) – Location in A Space.

Returns:

a python dictionary object of cell constants and 3D coordinates of atoms

Return type:

dict

Example of the .xyz data in python dictionary object:

{
    xyz: [(x1, y1, z1)...(xn, yn, zn)]
    cell: [...] #transformed cell constants
}

generatePowder(kv=100, t2max=0.05, smax=1.0, eta=1.0, gamma=0.001, absp=0, bg=False, bamp=0.35, bgamma=0.001, bmfact=0.02)¶

Generates powder diffraction.

Parameters:

kv (int or float, optional) – Accelaration voltage in kilo-volts.
t2max (float, optional) – Maximum scattering angle.
smax (float, optional) – Maximum Sin(theta)/Wavelength.
smax – Maximum Sin(theta)/Wavelength.
eta (float, optional) – the mixing coefficient between gaussian and lorentzian in a pseudo-Voight peak function.
gamma (float, optional) – Diffraction peaks half maximum half width.
absp (int, optional) – With Absoption structure factor (1 -default) or not (0).
isbgdon (int, optional) – Background on or not (default no background).
bamp (float, optional) – Background amplitude.
bgamma (float, optional) – Background width.
bmfact (float, optional) – Background exponential damping factor.

Returns:

an array of 2 x 1000 with the first row representing the scattering angle 2theta and the second the intensity

Return type:

array

generateStereo(xa=(0, 2, 0), tilt=(0.0, 0.0), zone=(0, 0, 1))¶

Generate stereodiagram.

Parameters:

xa (tuple of 3 integers, optional) – Crystal horizontal axis in reciprical space
tilt (tuple, optional) – Sample tilts in (x,y)
zone (tuple, optional) – Zone axis

Returns:

A list of stereodiagram elements represented by dict object

Return type:

list of dict object

Example of the stereodiagram output:

[
    {
        "c": (x,y),              # center
        "r": 1.0,                # radius
        "idx": (h, k, l),        # Miller Index
    }
]    

To display the resulting stereodiagram, use showStereo.

getBlochImages(sample_thickness=DEF_THICKNESS, pix_size=DEF_PIXSIZE, det_size=DEF_DETSIZE, nType=TY_NORMAL, bSave=False)¶

Retrieves a set of dynamic diffraction image from the simulation sessiom marked by:

beginBloch. and endBloch.

Parameters:

thickness (int, optional) – sample thickness range and step in tuple of three integers (th_start, th_end, th_step)
pix_size (int, optional) – Detector pixel size in microns
det_size (int, optional) – Detector size or output image size
nType (int, optional. defaults to 0) – type of bloch images generated. 0 for normal or 1 for large angle CBED images
bSave (bool, optional) – True - save the output to a raw image file with extension of ‘im3’

Returns:

BImgList object

Return type:

BImgList

Default values:

DEF_PIXSIZE = 25
DEF_DETSIZE = 512
DEF_THICKNESS = (200, 200, 100)

Warning

Dynamic diffraction pattern generation or Bloch has an extensive memory requirement for regular image generation:

nType = TY_NORMAL

Even more so for a large angle CBED generation when nType = TY_LACBED.

To reduce the memory needed, it is recommended to lower input parameters, particularly:

The detector size det_size. A reduction of the default value of 512 to 218 for example can reduce memory usage in pyemaps without losing accuracies of the results.
The number of sampling points in sampling. With less available memory on the system where pyemaps is running, decreased sampling points in sampling parameter can make a big difference in pyemaps performance.

getCalculatedBeams(bPrint=False)¶

Retieves and/or prints calculated beams for current dynamic diffraction simulation session marked by beginBloch and endBloch.

This information is available right after beginBloch call.

Parameters:: bPrint (bool, optional, default False) – whether to print selected diffracted beams info on standard output
Returns:: The number of selected beams and the selected beams list in Miller indexes.
Return type:: a python tuple.

getSCMatrix(ib_coords=(0, 0), sample_thickness=DEF_THICKNESS[0], rvec=(0.0, 0.0, 0.0))¶

Obtains scattering matrix at a given sampling point. To get a list of sampling points used in this dynamic simulation session, call printIBDetails after beginBloch. In addition to the scattering matrix, it also generates associated eigen values and diffracted beams.

This call must be made during a dynamic simulation session marked by beginBloch and endBloch.

Parameters:

ib_coords (tuple, optional, defaults to (0, 0)) – Sampling point coordinates tuple.
thickness (int, optional, defaults to 200) – Sample thickness.
rvec (tuple of 3 floats, optional, defaults to (0.0,0.0,0.0)) – R vector shifting atom coordinates in crystal, each value between 0.0 and 1.0.

Returns:

scattering matrix size; scattering matrix; eigen values; diffracted beams.

Return type:

a tuple.

Default values for sample_thickness:

DEF_THICKNESS[0] = 200

Example of the eigen vales:

Eigen values at: (0, 0):
[ 0.04684002-0.00218389j -0.2064669 -0.00147516j -0.30446348+0.00055009j
-0.27657617+0.00023512j -0.2765751 +0.00023515j  0.00539041-0.00382443j
-0.535879  -0.00023585j -0.5612881 +0.00045343j -0.55369247+0.00026236j
-0.55368818+0.00026249j -0.19093572+0.00066419j -0.1550311 +0.00045471j
-0.15503166+0.00045471j -0.58842399-0.00202841j -0.67850191+0.00042728j
-0.72713566+0.00060655j -0.70972681+0.00052279j -0.72092338+0.0005903j
-0.72093237+0.00059052j -0.64608335-0.0001983j  -0.64607544-0.00019853j]

load(cty=0)¶

Prepare and load crystal data into backend simulation module.

Once loaded into simulation modules, the crystal data will be in backend module’s memory until unload() method is called or another crystal object calls this method.

Since all crystal objects use this method to load its data into the shared silmulation modules, data races need to be avoided.

One way to prevent data races is to guard all simulations for one crystal object between its load() and unload() methods.

Parameters:: cty (int, optional) – 0 - normal crystal loading, 1 - loading for crystal constructor

Note

This routine is designed to minimize trips to the backend simulation modules and therefore miximizing the performance. Users do not need to handle this calls directly.

plotPowder(pw)¶

Show powder diffraction created from generatePowder.

Parameters:: pw (array, required) – Powder diffraction data

printCSF(sfs)¶

Formats and prints structure factors to standard output.

Parameters:: sfs (dict, required) – structure factor data generated from generateCSF.

Example of the output for a X-Ray Structure Factor for Silicon:

    -----X-ray Structure Factors----- 
crystal            : Silicon
h k l              : Miller Index
s-w                : Sin(ϴ)/Wavelength <= 1.0
d-s                : D-Spacing

h   k   l        s-w             d-s          amplitude         phase

1   1   1    0.1594684670    3.1354161069    58.89618        180.000000
0   0   2    0.1841383247    2.7153500000    6.565563e-31    0.000000
0   2   2    0.2604109162    1.9200423983    67.56880        180.000000
1   1   3    0.3053588663    1.6374176590    44.24472        180.000000
2   2   2    0.3189369340    1.5677080534    8.151511e-14    180.000000
...

printIBDetails()¶

Prints a dynamic diffraction simulation details during a session marked by beginBloch. and endBloch.

Information regarding the simulation session include sampling points and their associated diffracted beam directions etc.

The information is available right after beginBloch call.

printXYZ(xyzdict)¶

Print mxtal data in .xyz format in standard output. Refer to XYZ format for its definition and usage.

Parameters:: xyzdict (dict, required) – Crystal structure data.

Note

An example of Silicon atomic structure by pyemaps:

216
    50.0 50.0 50.0 90.0 90.0 90.0
SI           0.6788375000   0.6788375000   0.6788375000 
SI           3.3941875000   3.3941875000   0.6788375000 
SI           4.7518625000   2.0365125000   2.0365125000 
SI           2.0365125000   4.7518625000   2.0365125000 
SI           3.3941875000   0.6788375000   3.3941875000 
...

r2d(v=(0.0, 0.0, 0.0))¶

Transform vector from recriprocal to real space

Parameters:: v (tuple, optional) – A vector of float coordinates
Returns:: Tranformed vector
Return type:: tuple of floats

set_sim_controls(simc=None)¶

Sets simulation controls in the backend.

This method also tries to minimize the trip to the backend simulation module by skipping the call to the backend if default values are given.

Parameters:: simc (pyemaps.SIMC, optional) – Simulation control objects

Note

*pyemaps” assumes that attributes in sim_control class are rarely changed.

unload()¶: Remove crystal data from the memory in the backend simulation modules.

vlen(v=(1.0, 0.0, 0.0), ty=0)¶

Calculates vector length real space vectors or in reciprocal space vectors.

Parameters:

v (tuple, optional) – A vector of float coordinates
ty (int, optional) – 0 real space, 1 reciprocal space

Returns:

vector length in reciprical space or in reciprocal space

Return type:

float

static wavelength(kv=100)¶

Calculates electron wavelength.

Parameters:: kv (float or int, optional) – High voltage

return: wave length rtype: float

writeXYZ(xyzdict, fn=None)¶

Save mxtal data generated by pyemaps to a .xyz file <fn> File path is composed by pyemaps depending on whether PYEMAP_DATA environment variable is set. For details how pyemaps compose the file name see Environment Variables for details.

The file can be imported into external tool such as Jmole to view its content.

property cell¶: Cell constants

property dw¶: Debye-Waller factor or thermal factor

property name¶: crystal name

property atoms¶: atom list

property spg¶: Space group

isISO()¶: Check if crystal thermal type is Isotropic or not

loaded()¶

Check to see if crystal data is loaded into simulation module or not.

Returns:: True - loaded; otherwise False
Return type:: bool

classmethod from_builtin(cn='Diamond')¶

Create a crystal by importing data from pyemaps build-in crystal database

Parameters:: cn (string, optional) – Name of the crystal in pyemaps’s builtin database.
Raises:: CrystalClassError – If reading database fails or any of its components fail to validate.

Note

For a list of pyemaps builtin crystal names, call: Crystal.list_all_builtin_crystals() method

classmethod from_xtl(fn)¶

To create a crystal object by importing data from xtl formtted file.

Parameters:: fn (string, required) – Crystal data file name in pyemaps propietory format.
Raises:: CrystalClassError – file reading fails or any of its components fail to validate.

XTL Format Example:

crystal Aluminium: dw = iso
cell 4.0493 4.0493 4.0493 90.0000 90.0000 90.0000
atom al 0.000000 0.000000 0.000000 0.7806 1.000000
spg 225 1

Required Fields:

dw = iso by default, other values: uij, bij
name: crystal name.
cell constants: six floating point values defining crystal cell.
atoms: one or two lines of atoms positions along with element symbol
spg: space group data. Two positive digits: [number, setting]

Validation:

if dw == iso, atoms line must have at least 4 floating numbers in of (x,y,x,d-w,occ) where occ defaults to 1.00 if not provided.
if dw == uij,bij, each atom data must have at least 9 floating points like (x,y,z,b11,b22,b33,b12,b13,b23,occ)

Input File Name Search:

Full path and exists.
Current working directory.
PYEMAPSHOME/crystals directory, where PYEMAPSHOME is an environment variable pointing to pyemaps data home directory.

For detals how pyemaps look for crystal files, See Environment Variables.

classmethod from_cif(fn)¶

import crystal data from a cif (Crystallographic Information File).

Parameters:: fn (string, required) – Crystal data file name in JSON format.
Raises:: CrystalClassError – If file reading fails or any of its components (cell, atoms, spg) fail to validate.

classmethod from_json(jfn)¶

Import crystal data from a .json file.

Parameters:: jfn (string, required) – Crystal data file name in JSON format.
Raises:: CrystalClassError – If file reading fails or any of its components fail to validate.

An example of a json file content:

{
    "cell": 
        {"a": "5.4307",
        "b": "5.4307",
        "c": "5.4307",
        "alpha": "90.0",
        "beta": "90.0",
        "gamma": "90.0"
        },
    "atoms":
        [
            {"symb": "si",
            "x": "0.125",  
            "y": "0.125", 
            "z": "0.125",
            "d-w": "0.4668", 
            "occ": "1.00"
            } 
        ],
    "spg":
        {"number": "227",
        "setting": "2" 
        },
    "dw": "iso",
    "name": "Silicon"
}

classmethod from_dict(cdict)¶

Import crystal data from a python dictionary object.

Parameters:: cdict (dict, required) – Crystal data file name in as a python dictionary object.
Raises:: CrystalClassError – If any of its components import fails.

An example of a json file content:

{
    "cell": 
        {"a": "5.4307",
        "b": "5.4307",
        "c": "5.4307",
        "alpha": "90.0",
        "beta": "90.0",
        "gamma": "90.0"
        },
    "atoms":
        [
            {"symb": "si",
            "x": "0.125",  
            "y": "0.125", 
            "z": "0.125",
            "d-w": "0.4668", 
            "occ": "1.00"
            } 
        ],
    "spg":
        {"number": "227",
        "setting": "2" 
        },
    "dw": "iso",
    "name": "Silicon"
}

static list_all_builtin_crystals()¶: To list all builtin crystals available in pyemaps built-in crystal database, use this routine to determine the name of the crystal to load using from_builtin.