Modules, Classes and Interfaces¶

pyEMAPS modules are built around its backend simulation and calculation libraries and are designed to make access to the core diffraction simulation libraries easy.

Crystals¶

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.

Microscope and Simulation Controls¶

This class is a helper for handling pyEMAPS microscope controls.

There are two controls classes this module defines: microscope controls and simulations controls.

Since the latter changes much less frequently than the former, simulation control is embedded as a member of a microscope controls class.

Simulation control constants and default values¶

pyemaps.emcontrols.DEF_EXCITATION = (0.3, 2.0)¶

pyemaps.emcontrols.DEF_GMAX = 3.5¶

pyemaps.emcontrols.DEF_BMIN = 0.1¶

pyemaps.emcontrols.DEF_INTENSITY = (0.0, 5)¶

pyemaps.emcontrols.DEF_GCTL = 6.0¶

pyemaps.emcontrols.DEF_ZCTL = 5.0¶

pyemaps.emcontrols.DEF_OMEGA = 10¶

pyemaps.emcontrols.DEF_SAMPLING = 8¶

pyemaps.emcontrols.SAMPLE_THICKNESS = (200, 200, 100)¶

Microscope control constants and default values¶

pyemaps.emcontrols.DEF_TILT = (0.0, 0.0)¶

pyemaps.emcontrols.DEF_ZONE = (0, 0, 1)¶

pyemaps.emcontrols.DEF_DEFL = (0.0, 0.0)¶

pyemaps.emcontrols.DEF_KV = 200.0¶

pyemaps.emcontrols.DEF_CL = 1000.0¶

pyemaps.emcontrols.DEF_APERTURE = 1.0¶

pyemaps.emcontrols.DEF_XAXIS = (0, 0, 0)¶

pyemaps.emcontrols.DEF_PIXSIZE = 25¶

pyemaps.emcontrols.DEF_DETSIZE = 512¶

pyemaps.emcontrols.DEF_MODE = 1¶

pyemaps.emcontrols.DEF_CBED_DSIZE = 0.16 ¶

exception pyemaps.emcontrols.EMCError(message='')¶

Bases: Exception

Microscope controls objects creation and validation errors.

__init__(message='')¶

pyemaps.emcontrols.doc_dec_simc(k)¶

class pyemaps.emcontrols.SIMControl(excitation=DEF_SIMC['excitation'], gmax=DEF_SIMC['gmax'], bmin=DEF_SIMC['bmin'], intensity=DEF_SIMC['intensity'], gctl=DEF_SIMC['gctl'], zctl=DEF_SIMC['zctl'])¶

Bases: object

Simulation controls, to be embedded in EMControl

__init__(excitation=DEF_SIMC['excitation'], gmax=DEF_SIMC['gmax'], bmin=DEF_SIMC['bmin'], intensity=DEF_SIMC['intensity'], gctl=DEF_SIMC['gctl'], zctl=DEF_SIMC['zctl'])¶

property excitation¶: Excitation error range in (min, max)

property gmax¶: Maximum recipricol vector length

property bmin¶: Beta perturbation cutoff

property intensity¶: Kinematic diffraction intensity cutoff level and scale in (level, scale)

property gctl¶: Maximum index number for g-list

property zctl¶: Maximum zone or Miller index number

property omega¶: Diagnization cutoff value

property sampling¶: Number of sampling points

property sth¶: Samples thickness

plot_format()¶: Format simulation controls in builtin display functions Only plot those parameter that are not defaults

classmethod from_random()¶: For backward compatibility only

pyemaps.emcontrols.doc_dec(k)¶

class pyemaps.emcontrols.EMControl(tilt=DEF_TILT, zone=DEF_ZONE, defl=DEF_DEFL, vt=DEF_KV, cl=DEF_CL, simc=SIMControl())¶

Bases: object

Microscope and sample property controls class. Its attributes include:

tilt: sample tilt in x and y directory (x,y)
zone: starting zone axis
defl: shifts in x and y direction (x, y)
cl: cameral length
vt: hight voltage in kilo-volts
**simc*: SIMControl object

Other optional emcontrol parameters:

aperture: Objective len aperture
pix_size: detector pixel size
det_size: detector size
xaxis: crystal horizontal axis in reciprical space
mode: simulation mode: 1- normal, 2-CBED
dsize: diffracted beam size

__init__(tilt=DEF_TILT, zone=DEF_ZONE, defl=DEF_DEFL, vt=DEF_KV, cl=DEF_CL, simc=SIMControl())¶

classmethod from_dict(emc_dict)¶

Create an EMControl object from a python dict object

Parameters:: emc_dict (dict, required) – Microscope control dict object
Raises:: EMCError, if validation fails

property zone¶: Starting zone axis

property tilt¶: Tilt in x and y directions (x,y)

property defl¶: Shifts in x and y directions (x, y)

property cl¶: Camera length

property vt¶: High voltage

property xaxis¶: Crystal horizontal axis in reciprical space

property simc¶: Simulation Controls

property aperture¶: Objective lense aperture

property pix_size¶: Detector pixel size in microns

property det_size¶: Detector size in microns

property mode¶: Simulation mode

property dsize¶: Diffracted beam size

plot_format()¶: Format simulation controls in builtin display functions Only plot those parameter that are not defaults

static def_dict()¶

Kinematic Diffractions¶

Kinematic diffraction module is designed to handle kinematic simulation data. It is composed of Point, Line and Disk class objects.

class pyemaps.kdiffs.Point(p=(0.0, 0.0))¶

Bases: object

Coordinates of kinematic diffraction pattern object.

__init__(p=(0.0, 0.0))¶

property x¶: X coordinate

property y¶: Y coordinate

class pyemaps.kdiffs.Line(pt1=Point(), pt2=Point(), intensity=0, type=1)¶

Bases: object

Kikuchi line representation in kinematic diffraction patterns.

__init__(pt1=Point(), pt2=Point(), intensity=0, type=1)¶

property pt1¶: The first end point of a Line

property pt2¶: The second end point of a Line

property type¶: The type of a Line: Kikuchi line or HOLZ line

property intensity¶: Line intensity

calOpacity(l, h)¶

Calculate the line opacity based on its intensity value

0.2 -> lowest intensity 0.35-> highest intensity

to_dict()¶

class pyemaps.kdiffs.Index(I0=(0, 0, 0))¶

Bases: object

Miller Indexes of a diffracted beam representation in kinematic diffraction pattern.

__init__(I0=(0, 0, 0))¶

property I1¶: The first element of Miller Index of a diffracted beam

property I2¶: The second element of Miller Index of a diffracted beam

property I3¶: The third element of Miller Index of a diffracted beam

class pyemaps.kdiffs.Disk(c=Point(), r=0.0, i=Index())¶

Bases: object

Diffracted beams representation in kinematic diffraction patterns

__init__(c=Point(), r=0.0, i=Index())¶

property c¶: The center point of a diffracted beam.

property r¶: The radius of a diffracted beam.

property idx¶: The Miller index of a diffracted beam.

to_dict()¶: Creates a diffracted beam object from a dict pyton object

class pyemaps.kdiffs.diffPattern(diff_dict)¶

Bases: object

Create a kinematic diffraction pattern based on the pyemaps kinematic simulation output in python dict object.

See :doc:Visualization for how to visualize kinematic diffraction patterns using this object.

__init__(diff_dict)¶

Parameters:: diff_dict (dict, required) – Only accepts output from pyemaps kinematic diffraction run.

property klines¶: Kikuchi lines array

property hlines¶: Holz lines array

property disks¶: Disks array

property name¶: Crystal name

property shift¶: Shifts of the diffraction pattern

property nklines¶: Number of Kikuchi lines

property nhlines¶: Number of HOLZ lines

property ndisks¶: Number of Disks

to_dict()¶

Dynamic Diffraction¶

pyemaps.ddiffs.EMC¶: alias of EMControl

exception pyemaps.ddiffs.BlochListError(message='')¶

Bases: Exception

List of yynamic diffraction patterns errors.

__init__(message='')¶

class pyemaps.ddiffs.BlochImgs(name)¶

Bases: object

list of Bloch image objects and its associated controls

__init__(name)¶

property name¶

property blochList¶

add(emc, b)¶

sort()¶: Sort the bloch simulation results by controls

Images Classes¶

exception pyemaps.stackimg.XDPImageError(message='')¶

Bases: Exception

Experimental diffraction pattern image object errors.

__init__(message='')¶

pyemaps.stackimg.normalizeImage(img)¶

pyemaps.stackimg.displayXImage(img, fsize=(0, 0), bColor=False, isMask=False, bIndexed=False, iShow=False, ds=None, suptitle='')¶

Internal stem4d helper function displaying image.

Returns:
Return type:: None

class pyemaps.stackimg.StackImage(imgfn, nformat=E_SH, ndtype=E_FLOAT, dim=(MIN_IMAGESIZE, MIN_IMAGESIZE, MIN_IMAGESTACK), noffset=8)¶

Bases: object

Simple wrapper class for experimental images used in pyemaps Stem4d analysis:

Diffraction pattern indexing
Annular Drak Field image generation
Masked images

All image files must be of raw bitmap format, or known as headered raw format:

Header: stores metadata about the image, often including three numbers
for dimensions (e.g. width, height, and number of bit depth, or stacks).
Data Offset: After the header, the actual image or pixel data starts.
Pixel Data: Stored in a row-major order, meaning pixels are arranged
row-byrow across columns.

The image can also be represented by a numpy array directly. In this case, the StackImage object created will ignore its file name member.

and more to come.

__init__(imgfn, nformat=E_SH, ndtype=E_FLOAT, dim=(MIN_IMAGESIZE, MIN_IMAGESIZE, MIN_IMAGESTACK), noffset=8)¶

property fname¶: Experimental diffraction pattern image input file full path. In case of numpy array, this field is ignored.

property nformat¶

The type of the image file

E_RAW: raw image files with image data at an noffset from the beginning of the file.
E_SH: small header (pyEMAPS propietory). Header is a tuple of three short integers and data type represented also by a short integer. Total bytes of the header or the offset is 8)
E_NPY: numpy array.

property ndtype¶

The type of the image data - int, float, double are supported. The constants to used to represent the types are:

E_INT and EM_INT: single and multiple stack integral image data type.
E_FLOAT and EM_FLOAT: single and multiple stack real image data type.
E_DOUBLE and EM_DOUBLE: single and multiple stack 8-byte real image data type.

property noffset¶: image data offset from start of the file. Normally, it is the size of the header in bytes.

property dim¶: image dimension, support 3 dimensional images with input of 3 integer tuple of integers (width, height, stack).

property data¶: Raw image data in numpy ndarray when it is read from a numpy array Otherwise, the data will be generated from Stem4d when the input image file is loaded.

loadImage(rmode=EL_ONE, stack=1)¶: Loads image into stem4d module for analysis.

viewExpImage(peakDP=False, iStack=1, title='', iShow=False)¶

Helper function in stem4d module to display experimental diffraction database diffraction pattern currently loaded.

Parameters:

peakDP (Boolean, optional) – kinematic diffraction with miller index. This parameter is only valid for EDIOM operations
Indexed (boolean, optional, default to False) – show the kinematic patterns after indexing is completed.
iStack (integer, optional, default to 1) – Image stack number to show. For single stack image, this parameter takes default value of 1
iShow (boolean, optional, default to False) – whether to show miller indexes

Returns:

Return type:

None

This function is typically used to display experimental image after diffraction patterns matched and indexed. It can also be used to display intermediate search results after peaks are found but before indexes are matched. The latter display is turned on only by bDebug flag in loadDPDB call.

static showMatchedDBDP()¶

Helper function in stem4d module to display diffraction database diffraction pattern that best matches that of the experimental diffraction image pattern.

This function is typically used to confirm its match with experimental diffraction pattern. See sample code al_ediom.py for usage of this function.

displayFitImage(nc)¶: Internal intermediate helper function for display fit images.

static displaySearchMask(nr, nc)¶

Internal stem4d helper function displaying image mask image generated in peak search.

Returns:
Return type:: None

static displaySearchKernel(nr, nc)¶

Internal stem4d helper function displaying image kernel image generated in peak search.

Returns:
Return type:: None

static showDPDBMMask(mr, mc)¶: Internal function to display loaded DP database stereo projection map as explained in the following

static loadDPDB(dbfn, bShowDBMap=False)¶

Loads the diffraction database file dbfn into stem4d for diffraction peak searching and indexing.

See sample code si_dpgen.py for how to generate a diffraction pattern database with pyemaps generateDPDB.

The database file can also be saved and reused.

Parameters:

dbfn (string, required) – DP database file name.
bShowDBMap (boolean, optional, default to False) – weather to display the stereodigram project map after successful loading of the database file

Returns:

status code, stereo projection map dimension - two integers tuple

Return type:

tuple

See the following for stereo projection map representing the DP database:

static showMatchingIndexMap(fr, fc)¶

Helper function in stem4d module to display matching indexes map. The colored heat map with the peak indicates the orientation in which experimental and database diffraction patterns best match.

Parameters:

fr (int, required) –
stereo projection map height. This number is obtained from loadDPDB call.
fc –
stereo projection map width. This number is obtained from loadDPDB call.

Type:

int, required

Returns:

status code

Return type:

int

indexImage(dpdbfn, cc=DEF_CC, sigma=DEF_SIGMA, img_center=DEF_ICENTER, rmin=DEF_RMIN, search_box=DEF_BOXSIZE, scaling_option=(DEF_XSCALE, DEF_TSCALE), filter_threshold=DEF_FILTER_THRESHOLD, peak_threshold=DEF_SEARCH_THRESHOLD, ssel=1, bDebug=False)¶

Searches and indexes an experimental diffraction image. The experimental diffraction image will be loaded with StackImage class constructor and its loadImage method before the search and indexes are performed.

In addition, a diffraction database also needs to be loaded preceeding this call with loadDPDB

Parameters:: dpdbfn – diffraction pattern database file name. The file is generated by pyemaps dp_gen module

or database file name saved from previous runs. :type dpdbfn: string, required

Parameters:

cc (float, optional) – Camera constant in 1/Angstrom/pixel.
sigma (float, optional.) – Diffraction peak width - estimated image peak width.
img_center (float tuple, optional) – diffraction pattern center in (col, row) coordinate.
rmin (float, optional) – low cutoff radius for excluding center beam and diffuse intensities.
search_box (float, optional) – Parameter in pixels used to define peak search. Recommended value of 3 to 4 times of sigma value for selected area diffraction.
filter_threshold (float, optional) – Diffraction pattern screening threshold. Between 0.0 and 1.0 use 0 to include all database patterns for search.
peak_threshold (float, optional) – Peak threshold. value between 0.0 and 1.0. used to remove noisy peaks.
ssel (integer, optional. Default value to 1, the first image layer in the input image stack.) – image stack selection. The value must be in range of the input image layers.
bDebug (Boolean, optional. Default value to False.) – debug option. This is for displaying intermediate searching and masking images used.

Returns:

status code, 0 for successful run

Return type:

integer

The image control parameters cc - rmin above are image meaurements controls. The accuraccies of these measurements can greatly affect the peak search and eventually indexing results.

The remaining input parameters directly control the search and indexing functions and its results. Use these parameters to tune your results.

The following is a typical sequence of displays during the execution:

1. Once the DP database is loaded successfully, the steoreo projection map associated with the DP database will be shown.

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

2. Successful experimental DP image importing will also show the image. This gives users the opportunity to verify the image:

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

3. Following the display of the experimental DP image and if bDebug is not set (by default), the indexing result will be displayed on top of the experimental image:

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

4. Once the indexing results are generated, users have the option to call more display STEM4D functions to show other results generated by this call. For examples, the matching database DP image and DP database matching index map as shown below:

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

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

The latter map presents the likely matching location (in red) between the DP in database, also considered the theoretical diffraction patterns, and the experimental DP image.

5. Finally, in addition to the above visual representation of the run and results, more verbose results are also shown in standard output:

Number of peaks found: 45

-----------------Diffraction Pattern(DP) Indexing Results--------------------
***** DP stack loaded and indexed: 1
***** Best matching database DP: 1715
***** DP rotation angle: 284.191 (degrees)
***** Number of diffraction peaks indexed: 11
***** Experimental and database DP correlation maximum: 0.988308
***** Beam direction: 0.0575418 0.0599394 0.232559
***** Reliability index (> 5.0): 30.5407


-----------------Indexed Diffraction Pattern Details------------------
DP #   Miller Index     Distance            DP Loc          Intensity
    1     2    -2     0   18.805359  114.912613  109.021492   14.05505
    2    -2     2     0   20.888754   81.346603   87.833191  100.00000
    3     3     1    -1   22.201900   95.978333  120.995316   28.63353
    4    -1    -3     1   22.830843  117.979164   86.309898    9.12775
    5    -3    -1     1   23.202806  101.336617   75.915146   17.33628
    6     1     3    -1   23.803307   78.843224  111.661034   97.01090
    7     5    -1    -1   36.265705  112.098000  132.817802    2.99402
    8    -5     1     1   36.616173   85.120682   65.116249    4.92946
    9    -1     5    -1   36.805595   62.239502  100.821404   33.52511
    10   -4     4     0   39.269745   66.114388   77.537254   18.77301
    11    4     4    -2   42.499973   76.063011  134.779076    2.83128

where Reliability index greater than 5.0 is considered successful run. DP stands for diffraction pattern. If your results do not fit in a run, adjusting search and indexing paramemers such as filter_threshold and peak threshold can also help stem4d module to search and match peaks.

Note

When bDebug flag is set (to ‘True’), users are offered to chance to display more information of stem4d’s intermediate execution steps. For example, peak discovery step will show results of all found peaks by image peak matching algorithms before indexing is done. These intermediate images are mainly for debugging purposes.

generateBDF(center=(0.0, 0.0), rads=(0.0, 0.0), scol=0.0, bShow=False)¶

This method generates an (Annular) Bright/Dark Field image from an experimental stack image. It is a wrapper for the function `getBDF`function in the new SEND module.

param center:

The center of detector.

type center:

tuple of floating point numbers

param rads:

a pair of radius for inner and outer field detectors. When the inner radius is set to zero, the resulting image will be either Bright Field(BF) or Dark Field(DF) depending on if the center is on the bright spot of the image or not. Otherwise, a positive inner radius will result in Annular Bright Field (ABF) or Annular Dark Field (ADF).

type rads:

tuple, optional.

param scol:

The size of the output image along column direction.

type scol:

floating point numbers, optional

param bShow:

whether to display the resulting image.

type bShow:

boolean, optional, default False

return:

(status code, image data), status code of 0 successful, otherwise failed

rtype:

tuple of a short integer and image data array.

Note

The experimental image loaded must have more than one stack.

generateMaskedImage(maskfn, scancol=0.0, bShow=False)¶

generates an Bright Field(ADF) image from an experimental stack image input. and a mask image.

Parameters:

maskfn (string, required) – mask image file name.
scancol (float) – The center of ADF detector. default value 0.0
bShow (boolean, optional, default False) – whether to display the resulting ADF image.

Returns:

status code, 0 successful, otherwise failed

Return type:

integer

static convertImage(imgfn, nformat=E_RAW, ndtype=E_FLOAT, dim=(MIN_IMAGESIZE, MIN_IMAGESIZE, MIN_IMAGESTACK), noffset=8)¶

converts any other suported image formats into pyEMAPS’ proprietory small header format.

This static method is very useful for all auxillary images to be used with stem4d module and are required to have the proprietory image format by the pyEMAPS simulation backend.

Parameters:

imgfn (string, required. Ignored when nformat is E_NPY) – input image file path
nformat (integer, optional, default to E_RAW) – format of the image file. Support all bitmap formatted image format
ndtype (integer, optional, default to E_INT) – image date types. It can be integer, float or double
dim (integer tuple, optional, default to (MIN_IMAGESIZE, MIN_IMAGESIZE, MIN_IMAGESTACK)) – three integer tuple for the dimension of the image data (width, height, stack/depth)
noffset (integer, optional, default to 8.) – header offset or starting byte of the image data.

Returns:

Return type:

None

Note

If the input raw image file name does not contain directory, this method will search the file in pyEMAPS data diretcory set by environment variable PYEMAPS_DATA or current working directory in that order.

If the input file contains the fully qualified file path, pyEMAPS will be using the folder that contains the file to place the output image file. So, please make sure that the input directory is writable.

The result pyEMAPS image file with small header will be saved in a folder name sh_converted in the dierctory that contains the original raw image file.

Display¶

pyemaps.display.showDif(dpl=None, cShow=True, kShow=True, iShow=True, layout='individual', bSave=False, bClose=False)¶

Render kinematic diffraction pattern generated by pyemaps.

Parameters:

dpl (DPList) – Kinematic difraction pattern object list DPList
cShow (bool, optional) – Plot control annotation. True (default): plot the control parameters on lower left corner; False do not plot.
kShow (bool) – Whether to display Kikuchi lines.
iShow (bool) – Whether to display Miller indexes.
layout (str, optional) – layout format. individual (default): plotting one by one, table: plotting in a table of 3 columns
bSave (bool) – Whether to save the diplay into a .png image file.
bClose (bool, optional) – Whether to close plotting window when finished. Default: False - users must close it.

pyemaps.display.showBloch(bimgs, cShow=True, bColor=False, layout='individual', bSave=False, bClose=False)¶

Render dynamic diffraction pattern generated by pyemaps.

Parameters:

bimgs (BlochImgs) –
Optional. Dynamic difraction pattern object list BImgList
cShow (bool, optional) – Plot control annotation. True (default): plot the control parameters on lower left corner; False do not plot.
bColor (bool) – Optional. Whether to display the image in predefined color map.
layout (str, optional) – layout format. individual (default): plotting one by one, table: plotting in a table of 3 columns
bSave (bool) – Optional. Whether to save the image into a .im3 image file.
bClose (bool, optional) – Whether to close plotting window when finished. Default: False - users must close it.

pyemaps.display.showStereo(slist, name, cShow=True, iShow=False, zLimit=2, layout='individual', bSave=False, bClose=False)¶

Render stereodiagram generated by pyemaps.

Parameters:

slist (list, required) – Stereodiagram output from generateStereo.
cShow (bool, optional) – Plot control annotation. True (default): plot the control parameters on lower left corner; False do not plot.
iShow (bool, optional) – Whether to display Miller indexes or not.
zLimit (int, optional) – Miller indexes cutoff number.
layout (str, optional) – layout format. individual (default): plotting one by one in sequence, table: plotting in a table of 3 columns
bSave (bool, optional) – Whether to save the image into a .png image file.
bClose (bool, optional) – Whether to close plotting window when finished. Default: False - users must close it.

Note

When zlimit is set at 2, it is applied to all elements of each Miller index. For example, (3, 1, 0) will not be rendered.

File Utilities¶

Fileutils is a helper module in assisting pyemaps file i/o functions. Its methods include reading crystal data files and writing simulation output files.

It also detects pyemaps data home environment variables and directs file i/o accoridng to the rule set in Environment Variables.

class pyemaps.fileutils.Path(*args, **kwargs)¶

Bases: PurePath

PurePath subclass that can make system calls.

Path represents a filesystem path but unlike PurePath, also offers methods to do system calls on path objects. Depending on your system, instantiating a Path will return either a PosixPath or a WindowsPath object. You can also instantiate a PosixPath or WindowsPath directly, but cannot instantiate a WindowsPath on a POSIX system or vice versa.

classmethod cwd()¶: Return a new path pointing to the current working directory (as returned by os.getcwd()).

classmethod home()¶: Return a new path pointing to the user’s home directory (as returned by os.path.expanduser(‘~’)).

samefile(other_path)¶: Return whether other_path is the same or not as this file (as returned by os.path.samefile()).

iterdir()¶: Iterate over the files in this directory. Does not yield any result for the special paths ‘.’ and ‘..’.

glob(pattern)¶: Iterate over this subtree and yield all existing files (of any kind, including directories) matching the given relative pattern.

rglob(pattern)¶: Recursively yield all existing files (of any kind, including directories) matching the given relative pattern, anywhere in this subtree.

absolute()¶

Return an absolute version of this path. This function works even if the path doesn’t point to anything.

No normalization is done, i.e. all ‘.’ and ‘..’ will be kept along. Use resolve() to get the canonical path to a file.

resolve(strict=False)¶: Make the path absolute, resolving all symlinks on the way and also normalizing it (for example turning slashes into backslashes under Windows).

stat()¶: Return the result of the stat() system call on this path, like os.stat() does.

owner()¶: Return the login name of the file owner.

group()¶: Return the group name of the file gid.

open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)¶: Open the file pointed by this path and return a file object, as the built-in open() function does.

read_bytes()¶: Open the file in bytes mode, read it, and close the file.

read_text(encoding=None, errors=None)¶: Open the file in text mode, read it, and close the file.

write_bytes(data)¶: Open the file in bytes mode, write to it, and close the file.

write_text(data, encoding=None, errors=None)¶: Open the file in text mode, write to it, and close the file.

touch(mode=438, exist_ok=True)¶: Create this file with the given access mode, if it doesn’t exist.

mkdir(mode=511, parents=False, exist_ok=False)¶: Create a new directory at this given path.

chmod(mode)¶: Change the permissions of the path, like os.chmod().

lchmod(mode)¶: Like chmod(), except if the path points to a symlink, the symlink’s permissions are changed, rather than its target’s.

unlink()¶: Remove this file or link. If the path is a directory, use rmdir() instead.

rmdir()¶: Remove this directory. The directory must be empty.

lstat()¶: Like stat(), except if the path points to a symlink, the symlink’s status information is returned, rather than its target’s.

rename(target)¶: Rename this path to the given path.

replace(target)¶: Rename this path to the given path, clobbering the existing destination if it exists.

symlink_to(target, target_is_directory=False)¶: Make this path a symlink pointing to the given path. Note the order of arguments (self, target) is the reverse of os.symlink’s.

exists()¶: Whether this path exists.

is_dir()¶: Whether this path is a directory.

is_file()¶: Whether this path is a regular file (also True for symlinks pointing to regular files).

is_mount()¶: Check if this path is a POSIX mount point

is_symlink()¶: Whether this path is a symbolic link.

is_block_device()¶: Whether this path is a block device.

is_char_device()¶: Whether this path is a character device.

is_fifo()¶: Whether this path is a FIFO.

is_socket()¶: Whether this path is a socket.

expanduser()¶: Return a new path with expanded ~ and ~user constructs (as returned by os.path.expanduser)

pyemaps.fileutils.find_datahome()¶

pyemaps.fileutils.auto_fn(cn)¶

Auto-generate file name based on crystal name and time stamp when file is generated from pyemaps simulations.

This can be modified to tune the output to any other specific needs.

Parameters:: cn (string, required) – A crystal name.
Returns:: file name composed of crytsal name and time stamp in yyyymmddmmss format

rtype: string

pyemaps.fileutils.find_pyemaps_datahome(home_type='crystals')¶

Detects enviroment variable set by PYEMAPS_DATA and return the diretcory set by the variable or return current working directory.

Parameters:: home_type (string, optional) – Type of home directory
Returns:: data home path.
Return type:: string

Folder names depending by home_type input:

crystals: all crystal data files.
bloch: all dynamic simulation output files.
mxtal: all .xyz files saved from crystal constructor.
stereo: all .png files saved from stereodiagram plotting methods

pyemaps.fileutils.compose_ofn(fn, name, ty='diffraction')¶: Compose output file name based file name and file type.

pyemaps.fileutils.farray()¶

asfortranarray(a, dtype=None, *, like=None)

Return an array (ndim >= 1) laid out in Fortran order in memory.

Parameters¶

aarray_like: Input array.
dtypestr or dtype object, optional: By default, the data-type is inferred from the input data.
likearray_like: Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.

New in version 1.20.0.

Returns¶

outndarray: The input a in Fortran, or column-major, order.

Examples¶

>>> x = np.arange(6).reshape(2,3)
>>> y = np.asfortranarray(x)
>>> x.flags['F_CONTIGUOUS']
False
>>> y.flags['F_CONTIGUOUS']
True

Note: This function returns an array with at least one-dimension (1-d) so it will not preserve 0-d arrays.

exception pyemaps.fileutils.XTLError(fn='', message='')¶

Bases: Exception

XTL crystal data import errors.

__init__(fn='', message='')¶

exception pyemaps.fileutils.SPGError(message)¶

Bases: Exception

Space group data validation errors.

__init__(message)¶

exception pyemaps.fileutils.CIFError(fn='', message='')¶

Bases: Exception

CIF crystal data import errors.

__init__(fn='', message='')¶

exception pyemaps.fileutils.SPGSettingNotInRangeError(setmax)¶

Bases: SPGError

Space group setting validation errors.

__init__(setmax)¶

exception pyemaps.fileutils.SPGITMumberNotInRangeError(nummax)¶

Bases: SPGError

Space group IT number validation errors.

__init__(nummax)¶

pyemaps.fileutils.loadCrystalCIFData(fn)¶

Reads a .cif file for crystal data.

Parameters:: fn – cif file name
Type:: string, required
Returns:: tuple of crystal name and crystal data as dict object
Return type:: dict

Note

This method is still in active development.

pyemaps.fileutils.loadCrystalData(fn, cn=None)¶

Reading built-in datbase or a .xtl file for crystal data.

Parameters:

fn – XTL formatted Crystal file name
cn – Crystal name

Type:

string, required

Type:

string, optional

Returns:

tuple of crystal name and crystal data as dict object

Return type:

dict

pyemaps.fileutils.get_settingmax(num)¶

pyemaps.fileutils.getsymmetryxyz(sp, coords)¶

pyemaps.fileutils.lookuphm(inum)¶

pyemaps.fileutils.validateSPG(num, iset)¶

Error Handling¶

Error module for handling various pyemaps data validation and calculation failures.

Note

This module is still in active development and improvements.

exception pyemaps.errors.pyemapsError¶: Bases: Exception

exception pyemaps.errors.CrystalClassError(message)¶

Bases: Exception

Crystal object creation, validation and loading errors.

__init__(message)¶

exception pyemaps.errors.XTLError(fn='', message='')¶

Bases: Exception

XTL crystal data import errors.

__init__(fn='', message='')¶

exception pyemaps.errors.CIFError(fn='', message='')¶

Bases: Exception

CIF crystal data import errors.

__init__(fn='', message='')¶

exception pyemaps.errors.CellError(message)¶

Bases: Exception

Cell constant data validation errors.

__init__(message)¶

exception pyemaps.errors.CellValueError(ty=0, cn='')¶

Bases: CellError

Details of cell constant data validation errors.

__init__(ty=0, cn='')¶

exception pyemaps.errors.CellDataError(message='invalid cell data')¶

Bases: CellError

Details of cell constant data validation errors.

__init__(message='invalid cell data')¶

exception pyemaps.errors.SPGError(message)¶

Bases: Exception

Space group data validation errors.

__init__(message)¶

exception pyemaps.errors.SPGITMumberNotInRangeError(nummax)¶

Bases: SPGError

Space group IT number validation errors.

__init__(nummax)¶

exception pyemaps.errors.SPGSettingNotInRangeError(setmax)¶

Bases: SPGError

Space group setting validation errors.

__init__(setmax)¶

exception pyemaps.errors.SPGInvalidDataInputError(message='Invalid Space group data entered')¶

Bases: SPGError

Space group setting validation errors. Duplicate of SPGError.

__init__(message='Invalid Space group data entered')¶

exception pyemaps.errors.UCError(message='')¶

Bases: Exception

Atomc data validation errors.

__init__(message='')¶

exception pyemaps.errors.DPError(message='')¶

Bases: Exception

Kinematic diffraction pattren object creation errors.

__init__(message='')¶

exception pyemaps.errors.PointError(message='')¶

Bases: DPError

Detailed kinematic diffraction pattren object creation errors on Point object creation.

__init__(message='')¶

exception pyemaps.errors.LineError(message='')¶

Bases: DPError

Detailed kinematic diffraction pattren object creation errors on Line (Kikuchi or HOLZ) object creation.

__init__(message='')¶

exception pyemaps.errors.PIndexError(message='')¶

Bases: DPError

Detailed kinematic diffraction pattren object creation errors on Dfffracted beams Miller index object creation.

__init__(message='')¶

exception pyemaps.errors.DiskError(message='')¶

Bases: DPError

Detailed kinematic diffraction pattren object creation errors on Dfffracted beams object creation.

__init__(message='')¶

exception pyemaps.errors.DPListError(message='')¶

Bases: Exception

List of diffraction patterns create errors.

__init__(message='')¶

exception pyemaps.errors.BlochError(message='')¶

Bases: Exception

Dynamic diffraction pattern generation, creation and validation errors.

__init__(message='')¶

exception pyemaps.errors.EMCError(message='')¶

Bases: Exception

Microscope controls objects creation and validation errors.

__init__(message='')¶

exception pyemaps.errors.BlochListError(message='')¶

Bases: Exception

List of yynamic diffraction patterns errors.

__init__(message='')¶

exception pyemaps.errors.StereodiagramError(message='')¶

Bases: Exception

Stereodiagram generation errors.

__init__(message='')¶

exception pyemaps.errors.MxtalError(message='')¶

Bases: Exception

Crystal construction simulation errors.

__init__(message='')¶

exception pyemaps.errors.XDPImageError(message='')¶

Bases: Exception

Experimental diffraction pattern image object errors.

__init__(message='')¶

Modules, Classes and Interfaces¶

Crystals¶

Microscope and Simulation Controls¶

Simulation control constants and default values¶

Microscope control constants and default values¶

Kinematic Diffractions¶

Dynamic Diffraction¶

Images Classes¶

Display¶

File Utilities¶

Parameters¶

Returns¶

See Also¶

Examples¶

Error Handling¶

Table of Contents

Previous topic