Metadata-Version: 2.1
Name: pyemaps
Version: 0.3.9
Summary: Python Modules for Transmission Electron Diffraction Simulations
Home-page: https://www.emlabsolutions.com
Author: EMLab Solutions, Inc.
Author-email: support@emlabsoftware.com
Keywords: Transmission,Electron,Diffraction,Simulation,Crystallography,Python
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: license.txt
License-File: COPYING

# Introducing __pyemaps__

1. <a id="contents"></a>[Overview](#overview)

2. <a id="contents"></a>[Requirements](#requirements)

3. <a id="contents"></a>[Installation](#installation)

4. <a id="contents"></a>[Basic Usage](#basic-usage)

5. <a id="contents"></a>[Getting Started](#getting-started)

6. <a id="contents"></a>[Visualisation](#visualisation)

7. <a id="contents"></a>[Licence](#licence)



## Overview [`↩`](#contents) <a id="overview"></a>

__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 V (volts)

>    * Electron Structure Factor in 1/&#8491;^2

>    * Electron Absorption Structure Factor in 1/&#8491;^2  



>**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](https://emlab-solutions.github.io/pyemaps/#release-notes) for details.



__pyemaps__ is based on the proprietary Fortran applications released as backend of [cloudEMAPS2.0](https://emaps.emlabsolutions.com). 



Future releases planned include:



>*Bloch* : dynamic Bloch wave simulation.



Check [EMlab Solution, Inc.](https://www.emlabsolutions.com) 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](https://www.emlabsolutions.com/contact/). 



If you benefit from __pyemaps__ in your microscopy and crystallography research and education, go to [PayPal](https://www.paypal.com/paypalme/pyemaps22) to donate. Your generous donations keep us in the business of providing free software to the communities.   



## Requirements [`↩`](#contents) <a id="requirements"></a>



* __Python__: Version >= 3.6

* __numpy__: Version >= 1.21.2

* __matplotlib__: Version >= 3.2.1

* __PyCifRW__ Version == 4.4.3

* __Operating Systems__: Windows



Linux support planned in future releases, stay tuned.



## Installation [`↩`](#contents) <a id="installation"></a>



```

(.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 [`↩`](#contents) <a id="basic-usage"></a>



```

from pyemaps import Crystal

from pyemaps import DP

```



## Getting Started [`↩`](#contents) <a id="getting-started"></a>



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



```

python sample.py

```



where sample.py is as follows:



```python

 #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 V

sample tilt: (0.0,0.0)

sample offset: (0.0,0.0)

spot size: 0.05 Å

```



![](https://github.com/emlab-solutions/imagepypy/raw/main/kdiff_si.png?raw=True "Kinematic diffraction for silicon")



To see all crystal names with builtin data, call:

```python

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_:

```python

si = cryst.from_builtin('Silicon')

```

with:

```python

si = cryst.from_xtl(fn)

```

CIF format has recently been added to sources where __pyemaps__ can import:

```python

si = cryst.from_cif(fn)

```

where _fn_ is a crystal data file name. See release notes for details how pyemaps imports .cif data



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 [`↩`](#contents) <a id="visualisation"></a>

Accessing diffraction patterns data is easy for pyemaps users to visualize the diffraction patterns in any programs other than pyemaps' builtin plot with python's _matplotlib_ library:



* Raw kinematic diffraction data (DP) in python dictionary:

```python

    dp.__dict__ #dp is a pyemaps DP class object generated from calling generateDP by a crystal object 

``` 

* Individual components (such as Kikuchi lines, Diffracted beams or HOLZ lines) as python lists:

```python

    dp.klines #Kikuchi lines list

    dp.nklines #number of Kikuchi lines, same as len(dp.klines)

    dp.disks #diffracted beams list

    dp.ndisks #number of diffracted beams, same as len(dp.disks)

    dp.hlines #HOLZ lines list

    dp.nklines #number of HOLZ lines, same as len(dp.hlines)

    dp.shift #deflection shifts of all of the above

    ...

```

<!-- 

In addition to the above and and pyemaps' built-in _matplotlib_ rendering of diffraction pattern, DigitalMicrography (referred as DM here) is another option with its line and circle annotations objects. Simply open and execute the python script in DM __dm_diff.py__ in _samples_ directory for example.





![](https://github.com/emlab-solutions/imagepypy/blob/main/kdiff_si_dm.png?raw=True "Kinematic diffraction for silicon python script dm_diff.py") -->



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 controls - 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 [`↩`](#contents) <a id="licence"></a>



 __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/>.



Additional copyright notices and license terms applicable to portions of pyemaps are set forth in the COPYING file.



Contact supprort@emlabsoftware.com for any questions regarding the licence terms.
