pyemaps 1.1.4

A Python Package for Transmission Electron Diffraction Simulations and Crystallographic Computing

1. What's in pyEMAPS

2. Build pyEMAPS

3. Installation

4. Testing

5. Development Guidelines

6. pyEMAPS Contributor License Agreement

7. Code of Conduct

What's in pyEMAPS ↩

pyEMAPS package is a collection of python modules and libraries designed

for transmission electron diffraction simulations and crystallographic calculations

for all crystal systems. The simulation is based on the theories of kinematical and

dynamical electron diffraction, as described by Spence and Zuo in the book of Electron Microdiffraction (Plenum, New York, 1992).

The base version is free for personal and commercial use, while additional licensed features in 4DSTEM are available for enhanced functionality.

Features:

Free base features:

• Crystallography

  • Crystal constructor

  • Loading from a built-in crystal library

  • CIF import

  • Crystallographic transformations

  • Real and reciprocal vector calculations

  • Stereodiagram plotting

  • Crystal Structure Factors Calculations

• Electron diffraction pattern, dynamical

  • Convergent beam electron diffraction

  • Electron scattering Matrix

  • Electron dispersion

• Electron diffraction pattern, kinematical

  • Selected area diffraction

  • Kikuchi and high order Laue zone line geometry

  • Convergent beam electron diffraction

  • Electron powder diffraction simulations

Extended features (requires license):

• Electron diffraction patterns database builder and explore

• Electron diffraction pattern indexing

• Annular bright and dark field

• Masked images

Check our full pyemaps documentation for details of pyEMAPS python classes designs and their interfaces.

We are looking for experts in electron microscope and crystallography, and/or python enthusiasts to join pyEMAPS project as contributors, please contact us at [e-mail] if you are interested.

We greatly appreciate your contributions to pyEMAPS and look forward to making it a tool for the communty to accelaerate microscopy and crystallography education and research. 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 software tools to the education and research communities.

See instructions below for contributor:

Build pyEMAPS ↩

Requirements and recommendations:

• Python: Version == 3.7

• Operating Systems: Windows

• VSCode: code editing (recommended, for contributors only)

• MSVC Community 2019: with build tools (for contributors only)

Current pyEMAPS only support Windows and python 3.7. We are also looking for contributors to extend it to other platforms and python versions.

Like many python development, a virtual python environment is recommended to isolate your pyEMAPS development environment from your other python development projects.

Below are steps to establish pyEMAPS build environment with python 3.7.9 as an example:

• Install python 3.7.9 with Windows PowerShell command line in Administrator mode in c:\python37 directory:

   Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.7.9/python-3.7.9-amd64.exe" -OutFile "python-3.7.9-amd64.exe"

• Run the "python-3.7.9-amd64.exe", choose the following in installer GUI:

  • Select Customize Installation

  • Check and select pip

  • Install for all users/specific users

• Create a virtual environment called "pyemaps_build" for the build

  • Create a dev directory:

    
    mkdir pyemaps-dev
    
    

    (or choose your own directory name)

  • Create pyemaps_build virtual environemnt:

    
    c:\python37\python.exe -m venv pyemaps_build
    
    

• Activate pyemaps_build vitual environment:

  
  .\pyemaps_build\Scripts\activate
  
  

• Update pip:

  
   C:\Python37\python.exe -m pip install pip --upgrade
  
  

• Install other python packages required for building pyemaps, using pip:

  
  pip install setuptool wheel numpy build
  
  

• Install Microsoft Visual Studio 2019 Community with build tools

  https://visualstudio.microsoft.com/vs/older-downloads/

  by selecting "Desktop development with C++" in the installer.

  (You may need a microsoft account to be able to download)

• Build directory structure:

📦pyemaps

  ┣━ 📂.git          <----Source repository configurations

  ┣━ 📂build         <----Intermediate build folder

  ┣━ 📂dist          <----Build package files

  ┣━ 📂cdata         <----Built-in crystal data in proprietory format

  ┣━ 📂CifFile       <----CIF crystal data reader

  ┣━ 📂diffract      <----Diffraction modules python interfaces

  ┣━ 📂docs          <----Documentation using Sphinx. Document your changes!

  ┣━ 📂samples       <----Sample code. Offical sample code for guiding pyemaps usages

  ┣━ 📂scattering    <----Scattering data module

  ┣━ 📂spg           <----Space group data module

  ┗━ 📂test          <----Test cases including sanity, unit and stree tests. Keep adding them!

where docs for creation of documents requires Sphinx python package:

• Sphinx for documentation can be installed:

       pip install Sphinx=5.3.0

• Build pyEMAPS package, run:

  
   python build_pyemaps -t -v 1.0.0
  
  

  Here the option "-t" indicates build is for local testing purposes.

  You can replace the version number '1.0.0' with the one you desire.

  When the option -v is not specified. The build script will figure out the version

  from pypi.org repository.

  Note: there will be two additional diretcories:

  • build. folder holding intermediate build files.

  • dist. folder for final package that includes .whl and .tgz. The former is the package file and the latter is the current source code used to build the pacage in compressed format.

Installation ↩

• Install the new pyEMAPS package:

  
   pip .\dist\pyemaps-1.0.0-cp37-cp37m-win_amd64.whl
  
  

  This will install new pyEMAPS just built in current python virtual environment

  along with all of its dependent packages.

  If you have a previous pyemaps with versiual or larger than current package version.

  In that case, you need to uninstall previous version before installing the new package:

  
  pip uninstall pyemaps
  
  

Testing ↩

Current pyEMAPS development comes with a set of basic testing suites, including

• sanity checks

• unit tests

• stress tests.

To run these test suites, call:

   .\test\sanity\sanity.bat

We are looking for your tests contributions to make the development to keep high quality standards for pyEMAPS.

Development Guidelines ↩

As any open source development project, we strongly recommend contributors to adhere to the following guidelines:

• Issues creation. Before making changes for bug fix or feature implementation, create an issue in the pyEMAPS' repository. Your concise description of the issue(s) serves well not only in laying good foundations for your design and implementations, but also in communicating to your fellow contributors.

• Development Branch. Create your own branch from 'main' where you work on your changes. The main branch is kept as production base.

• Backwards Compatibilities Tests. Existing test suites designed for testing most of the features are to ensure that no existing implementations are unintentionally broken after new changes are introduced.

• New Tests Additions. Writing new test cases for the new implementations are strongly encouraged.

• Pull Requests. Before merging your changes into production branch "main", a pull request is required. The request should also accompany a list of code reviewers from the contributors.

• Code Review. We took code review seriously, whether you are reviewing code or your code is being reviewed. This process provides important step of making sound implementations and preventing new bugs.

• Documentation. You are the author of the new implementations, so please take the pride by documenting them!

  We use sphinx tool for documentation generation. To install sphinx, run:

  
  pip install -U sphinx
  
  

  in your python build virtual environment (pyemaps_build in our example).

  Most of the documentations files are in "docs" directory. After making documentation changes to record your changes, compile them with sphinx:

  
  sphinx-build -b html source .
  
  

  The changes resulted from the above can be previewed by opening index.html with avaliable browser.

pyEMAPS Contributor License Agreement ↩

Please read and agree to our Contributor License Agreement before contributing to this project.

Code of Conduct ↩

pyEMAPS is committed to providing a welcoming and inclusive environment for all contributors. We follow the Contributor Covenant as our code of conduct. Please make sure to review it before contributing.

Read the Contributor Covenant

Any instances of unacceptable behavior can be reported to [e-mail].