pyemaps 0.3.8

Python Modules for Transmission Electron Diffraction Simulations

Introducing pyemaps

1. Overview

2. Requirements

3. Installation

4. Basic Usage

5. Getting Started

6. Visualisation

7. Licence

Overview ↩

pyemaps package is a collection of python modules and libraries designed for transmission electron diffraction simulations and related crystallographic calculations. Main features include:

Crystal : crystal data module, classes and methods for loading crystal data from various sources; for generating diffraction patterns with microscope and sample control parameters; for creating electron powder diffraction; for calculating the following crystal structure factors:

• X-Ray Structure Factors

• Electron Structure Factor in kV (kilo volts)

• Electron Structure Factor in 1/Å^2

• Electron Absorption Structure Factor in 1/Å^

EMC : electron microscope control module. Its class EMC makes it easy to handle simulation control parameters.

DP : kinematic diffraction python class. It encapsulates diffraction pattern data generated by Crystal class instance and diffraction pattern visualisation methods such as plotting Kikuchi and HOLZ lines, and diffraction spots or disks and their indices.

See sample code and latest release notes for details.

pyemaps is based on the proprietary Fortran applications released as backend of cloudEMAPS2.0.

Future releases planned include:

Bloch : dynamic Bloch wave simulation.

Check EMlab Solution, Inc. for updates and releases. We welcome comments and suggestions from our user community. For reporting any issues and requesting pyemaps improvements, or sharing scripts using pyemaps, please go to our support page.

If you benefit from pyemaps in your microscopy and crystallography research and education, go to PayPal to donate. Your generous donations keep us in the business of providing free software to the communities.

Requirements ↩

• Python: Version >= 3.6

• Operating Systems: Windows

Linux support planned in future releases, stay tuned.

Installation ↩

(.venv) $ pip install pyemaps

where .venv is the python virtual environment

PYEMAPS_CRYSTALS environment variable is optional. But setting it to a directory where all custom

crystal data files are located provides central location for organizing your own crystal data. pyemaps also searches this directory for your crystal data.

    PYEMAPS_CRYSTALS=<local directory>

Basic Usage ↩

from pyemaps import Crystal

from pyemaps import DP

Getting Started ↩

Run the following on command line, after above successful installation:

python sample.py

where sample.py is as follows:

 #import Crystal class from pyemaps as cryst

from pyemaps import Crystal as cryst

# create a crystal class instance and load it with builtin silicon data

si = cryst.from_builtin('silicon')



# generate diffraction on the crystal instance with all default controls

# parameters, default controls returned as the first output ignored



_, si_dp = si.generateDP()

#plot and show the diffraction pattern using pyemaps built-in plot function

si_dp.plot()

The alternative to run the above without creating sample.py:

python -m pyemaps --sample (-s)

The diffraction plot is generated with silicon crystal data built in the package:

crystal Silicon: dw = iso

cell 5.4307 5.4307 5.4307 90 90 90

atom si 0.125 0.125 0.125 0.4668 1.00

spg 227 2

and default electron microscope and sample control parameters:

zone axis: (0,0,1)

microscope mode: normal

microscope camera length : 1000 mm

microscope voltage: 200 kV

sample tilt: (0.0,0.0)

sample offset: (0.0,0.0)

spot size: 0.05 Å

To see all crystal names with builtin data, call:

cryst.list_all_builtin_crystals()

where cryst is imported pyemaps Crystal class

To use a crystal data not in built-in database in above format (as xtl format), replace the code in sample.py:

si = cryst.from_builtin('silicon')

with:

si = cryst.from_xtl(fn)

where fn is a crystal data file name.

Note: pyemaps searches for fn if the full path is provided. Otherwise, it will look up the file in current working directory or in the directory set by PYEMAPS_CRYSTALS environment variable. In latter cases, fn is the file name without path.

Checking pyemaps version and displaying copyright information:

python -m pyemaps -c (--copyright)

python -m pyemaps -v (--version)

Visualisation ↩

In addition to Python's matplotlib for displaying diffraction patterns generated by pyemaps as shown above, DigitalMicrography (referred as DM here) is another option. The python script support in DM can realise the diffraction patterns from pyemaps with its line and circle annotations as demonstrated below:

import numpy as np

import DigitalMicrograph as DM



from pyemaps import Crystal as cr

from pyemaps import XMAX, YMAX

#----diffraction patterns generated by these bounds

#   [-XMAX, XMAX, -YMAX, YMAX]



#    screen size multiplier of diff bounds

mult = 4



#simple diffraction mode lookup

DIFF_MODE = ('Normal', 'CBED')

#------Diffraction modes-------

#       1 - normal

#       2 - CBED



def addline( x1, y1, x2, y2): 

    '''

    reserved for later use

    '''

    xx1, yy1, xx2, yy2 = x1*2, y1*2, x2*2, y2*2

    dmline = DM.NewLineAnnotation(xx1, yy1, xx2, yy2)

    

    dmline.SetResizable(False)

    dmline.SetMovable(False)

    dmline.SetDeletable(False)

    dmline.SetForegroundColor(0,1,0)

    dmline.SetBackgroundColor(0.2,0.2,0.5)

    

    return dmline





def adddisk( x1, y1, r, indx): 

    '''

    reserved for later use

    '''

    xx1, yy1, rr = x1*2, y1*2, r*2

    dmdisk = DM.NewOvalAnnotation()

    dmdisk.SetCircle(xx1-r,yx1-r, xx1+rr,yy1+r)

    dmdisk.SetLabel(indx)



    return dmdisk



    

def SetCommonProp(comp):

    '''

    Setting common attributes of the line and circle annotation components

    '''

    comp.SetResizable(False)

    comp.SetMovable(False)

    comp.SetDeletable(False)

    

def show_diffract(dp, md=1, name = 'Diamond'):

    #transform the plotting area based on pyemaps diffraction dimensions:

    # XMAX

    # YMAX

    shape = (2*XMAX*mult,2*YMAX*mult)



    #A new image from numpy array and initilize it to black background

    dif_raw = np.ones((shape), dtype = np.float32)

    dif_raw[:,:] = 255.0



    #DM create the image

    dm_dif_img = DM.CreateImage(dif_raw)

    dif_img = dm_dif_img.ShowImage()

    dif_img_disp = dm_dif_img.GetImageDisplay(0)

    

    #validate diffraction mode

    if md <1 or md > 2:

        print(f'diffraction mode provided {md} not supported')

        return 1

    

    #set image title

    img_title = str(f'Kinematic Diffraction Simulation:  {name} in {DIFF_MODE[md-1]} Mode')

    dm_dif_img.SetName(img_title)

    

    #xs,ys = diff_dict['bounds'] # not used



    #plotting Kikuchi and HOLZ lines and spots as DM components

    num_klines = dp.nklines

    if num_klines > 0:

        klines = dp.klines

        for kl in klines:        

            x1, y1, x2, y2 = kl 

            

            xx1, yy1, = (x1 + XMAX)*mult,(y1 + YMAX)*mult 

            xx2, yy2  = (x2 + XMAX)*mult,(y2 + YMAX)*mult

            

            kline = dif_img_disp.AddNewComponent(2, xx1, yy1, xx2, yy2)

            

            SetCommonProp(kline)

            kline.SetForegroundColor(0.7, 0.7, 0.7) #grey

            kline.SetBackgroundColor(0.2,0.2,0.5)# dark blue



    num_disks = dp.ndisks

    

    if num_disks > 0:

        disks = dp.disks

        for d in disks:

            x1, y1, r, i1, i2, i3 = d

            xx, yy, rr = (x1 + XMAX)*mult, (y1 + YMAX)*mult, r*mult

                         

            idx = '{:d} {:d} {:d}'.format(i1,i2,i3)

            

            disk = dif_img_disp.AddNewComponent(6, xx-rr, yy-rr, xx+rr, yy+rr)

            

            SetCommonProp(disk)

            disk.SetForegroundColor(0.0,0.0,1.0) # blue

            disk.SetBackgroundColor(0.5,0.5,0.75)# dark blue

            if md == 1:

                disk.SetFillMode(1)

            else:

                disk.SetFillMode(2)

        

            # a bit tricky to figure out the index location, has to use

            # the proxy component indxannot0 first. 

            indxannot0 = DM.NewTextAnnotation(0, 0, idx, 10)

            

            t, l, b, r = indxannot0.GetRect()

            w = r-l

            h = b-t

            

            nl = xx - ( w / 2)

            # nr = xx + ( w / 2)

            nt = yy -rr - h if md ==1 else yy - (h / 2)

            # nb = yy + rr + h if md == 1 else yy + (h / 2)

            

            indxannot = DM.NewTextAnnotation(nl, nt, idx, 10)

            

            dif_img_disp.AddChildAtEnd(indxannot)

            SetCommonProp(indxannot)

            indxannot.SetForegroundColor(0.9,0,0) #light red

            indxannot.SetBackgroundColor(1,1,0.5)

            

    if md == 2:

        num_hlines = dp.nhlines

        if num_hlines > 0 :

            hlines = dp.hlines

            for hl in hlines:

                x1, y1, x2, y2 = hl

                xx1, yy1 = (x1 + XMAX)*mult, (y1 + YMAX)*mult 

                xx2, yy2 = (x2 + XMAX)*mult, (y2 + YMAX)*mult

                

                hline = dif_img_disp.AddNewComponent(2, xx1, yy1, xx2, yy2)

                SetCommonProp(hline)

                hline.SetForegroundColor(0,0,0.8)

                hline.SetBackgroundColor(0.2,0.2,0.5)# dark blue

                

    del dm_dif_img

    return 0        

      

      

def run_si_dm_sample():  

   

    #-----------load crystal data into a Crystal class object-----------------

    name = 'Silicon'

    si = cr.from_builtin(name)



    #-----------content of the crystal data-----------------------------------

    print(si)



    #-----------generate diffraction pattern in CBED mode---------------------

    _, si_dp_cbed = si.generateDP(mode = 2, dsize = 0.2)

    #print(si_dp_cbed)



    #-----------Plot the pattern in DM----------------------------------------

    show_diffract(si_dp_cbed, md = 2, name = name)



    #-----------generate diffraction pattern in normal mode-------------------

    _, si_dp = si.generateDP()

    #print(si_dp)



    #-----------content of the crystal data-----------------------------------

    show_diffract(si_dp, name = name)



run_si_dm_sample()

Other sample scripts designed for you to explore pyemaps are available in samples directory:

• si_tilt.py: spot diffraction patterns generated with silicon crystal data, plotted with matplotlib pyplot module. The code also shows how a list of diffraction patterns are generated and displayed as one of electron microscope and sample control - tilt in x direction changes.

• si_zone.py: same as above except the control that changes is zone axis.

• pyplot_dm_si_diff.py: DM python script which generate and plot diffraction pattern for silicon crystal using matplotlib pyplot module. The rendering of diffracttion patterns are in black for normal mode and CBED in color.

• si_csf.py: structure factors generation and output by CSF pyemaps module.

• powder.py: electron powder diffraction generation and intensity plot by POWDER pyemaps module.

More samples code will be added as more features and releases are available.

To copy all of the samples from pyemaps package to the current working directory, run the following:

python -m pyemaps -cp (--copysamples)

all of the samples will be copied from pyemaps install directory to a folder named pyemaps_samples in your current working directory.

Licence ↩

pyemaps is distributed for electron diffraction and microscopy research, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

• pyemaps is for non-commercial use.

• pyemaps is free software under the terms of the GNU General Public Licence as published by the Free Software Foundation, either version 3 of the Licence, or (at your option) any later version. You should have received a copy of the GNU General Public Licence along with pyemaps. If not, see https://www.gnu.org/licenses/.

Contact [e-mail] for any questions regarding the licence terms.