<!-- # Open Source __pyEMAPS__ Development Guidelines -->
1. <a id="contents"></a>[What's in pyEMAPS](#overview)
2. <a id="contents"></a>[Build pyEMAPS](#build)
3. <a id="contents"></a>[Installation](#installation)
4. <a id="contents"></a>[Testing](#test)
5. <a id="contents"></a>[Development Guidelines](#process)
5. <a id="contents"></a>[pyEMAPS Contributor License Agreement](#CLA)
5. <a id="contents"></a>[Code of Conduct](#COC)
## What's in pyEMAPS [`↩`](#contents) <a id="overview"></a>
**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](https://emlab-solutions.github.io/pyemaps) 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 support@emlabsoftware.com 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](https://www.paypal.com/paypalme/pyemaps22) 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 [`↩`](#content) <a id="build"></a>
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:
<pre>
📦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!
</pre>
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 [`↩`](#contents) <a id="installation"></a>
* 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 [`↩`](#contents) <a id="test"></a>
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 [`↩`](#contents) <a id="process"></a>
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 [`↩`](#contents) <a id="CLA"></a>
Please read and agree to our [Contributor License Agreement](CONTRIBUTING.md) before contributing to this project.
## Code of Conduct [`↩`](#contents) <a id="COC"></a>
pyEMAPS is committed to providing a welcoming and inclusive environment for all contributors. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/) as our code of conduct. Please make sure to review it before contributing.
**[Read the Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)**
Any instances of unacceptable behavior can be reported to support@emlabsoftware.com.
Raw data
{
"_id": null,
"home_page": "https://www.emlabsolutions.com",
"name": "pyemaps",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "Transmission, Electron, Diffraction, Simulation, Crystallography, Python",
"author": "EMLab Solutions, Inc.",
"author_email": "support@emlabsoftware.com",
"download_url": "https://files.pythonhosted.org/packages/c8/a9/c658218e6484ec3e6b5cb22e9261ffacda5771e7d1cbce7f466f58dff69a/pyemaps-1.1.2.tar.gz",
"platform": null,
"description": "<!-- # Open Source __pyEMAPS__ Development Guidelines -->\r\n\r\n\r\n\r\n1. <a id=\"contents\"></a>[What's in pyEMAPS](#overview)\r\n\r\n2. <a id=\"contents\"></a>[Build pyEMAPS](#build)\r\n\r\n3. <a id=\"contents\"></a>[Installation](#installation)\r\n\r\n4. <a id=\"contents\"></a>[Testing](#test)\r\n\r\n5. <a id=\"contents\"></a>[Development Guidelines](#process)\r\n\r\n5. <a id=\"contents\"></a>[pyEMAPS Contributor License Agreement](#CLA)\r\n\r\n5. <a id=\"contents\"></a>[Code of Conduct](#COC)\r\n\r\n\r\n\r\n## What's in pyEMAPS [`\u21a9`](#contents) <a id=\"overview\"></a>\r\n\r\n**pyEMAPS** package is a collection of python modules and libraries designed \r\n\r\nfor transmission electron diffraction simulations and crystallographic calculations \r\n\r\nfor all crystal systems. The simulation is based on the theories of kinematical and \r\n\r\ndynamical electron diffraction, as described by Spence and Zuo in the book of Electron Microdiffraction (Plenum, New York, 1992).\r\n\r\n\r\n\r\nThe base version is free for personal and commercial use, while additional licensed features in 4DSTEM are available for enhanced functionality.\r\n\r\n\r\n\r\n### Features:\r\n\r\nFree base features:\r\n\r\n- Crystallography\r\n\r\n - Crystal constructor\r\n\r\n - Loading from a built-in crystal library\r\n\r\n - CIF import\r\n\r\n - Crystallographic transformations\r\n\r\n - Real and reciprocal vector calculations\r\n\r\n - Stereodiagram plotting\r\n\r\n - Crystal Structure Factors Calculations\r\n\r\n\r\n\r\n- Electron diffraction pattern, dynamical\r\n\r\n - Convergent beam electron diffraction\r\n\r\n - Electron scattering Matrix\r\n\r\n - Electron dispersion\r\n\r\n\r\n\r\n- Electron diffraction pattern, kinematical\r\n\r\n - Selected area diffraction\r\n\r\n - Kikuchi and high order Laue zone line geometry\r\n\r\n - Convergent beam electron diffraction\r\n\r\n - Electron powder diffraction simulations\r\n\r\n\r\n\r\n**Extended features** (requires license):\r\n\r\n- Electron diffraction patterns database builder and explore\r\n\r\n- Electron diffraction pattern indexing\r\n\r\n- Annular bright and dark field\r\n\r\n- Masked images \r\n\r\n\r\n\r\nCheck our full [pyemaps documentation](https://emlab-solutions.github.io/pyemaps) for details of __pyEMAPS__ python classes designs and their interfaces.\r\n\r\n\r\n\r\nWe are looking for experts in electron microscope and crystallography, and/or python enthusiasts to join pyEMAPS project as contributors, please contact us at support@emlabsoftware.com if you are interested.\r\n\r\n\r\n\r\nWe 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](https://www.paypal.com/paypalme/pyemaps22) to donate. Your generous donations keep us in the business of providing software tools to the education and research communities. \r\n\r\n\r\n\r\nSee instructions below for contributor:\r\n\r\n\r\n\r\n## Build pyEMAPS [`\u21a9`](#content) <a id=\"build\"></a>\r\n\r\n\r\n\r\nRequirements and recommendations:\r\n\r\n* __Python__: Version == 3.7\r\n\r\n* __Operating Systems__: Windows\r\n\r\n* __VSCode__: code editing (recommended, for contributors only)\r\n\r\n* __MSVC Community 2019__: with build tools (for contributors only)\r\n\r\n\r\n\r\nCurrent __pyEMAPS__ only support Windows and python 3.7. We are also looking for contributors to extend it to other platforms and python versions. \r\n\r\n\r\n\r\nLike many python development, a virtual python environment is recommended to isolate your pyEMAPS development environment from your other python development projects.\r\n\r\n\r\n\r\nBelow are steps to establish __pyEMAPS__ build environment with python 3.7.9 as an example:\r\n\r\n\r\n\r\n* Install python 3.7.9 with Windows PowerShell command line in Administrator mode in c:\\python37 directory:\r\n\r\n``` \r\n\r\n 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\"\r\n\r\n```\r\n\r\n* Run the \"python-3.7.9-amd64.exe\", choose the following in installer GUI:\r\n\r\n \r\n\r\n * Select Customize Installation\r\n\r\n * Check and select pip\r\n\r\n * Install for all users/specific users \r\n\r\n* Create a virtual environment called \"pyemaps_build\" for the build\r\n\r\n * Create a dev directory:\r\n\r\n ```\r\n\r\n mkdir pyemaps-dev\r\n\r\n ``` \r\n\r\n (or choose your own directory name)\r\n\r\n * Create pyemaps_build virtual environemnt:\r\n\r\n ```\r\n\r\n c:\\python37\\python.exe -m venv pyemaps_build\r\n\r\n ```\r\n\r\n* Activate pyemaps_build vitual environment:\r\n\r\n ```\r\n\r\n .\\pyemaps_build\\Scripts\\activate\r\n\r\n ```\r\n\r\n* Update pip:\r\n\r\n ```\r\n\r\n C:\\Python37\\python.exe -m pip install pip --upgrade\r\n\r\n ```\r\n\r\n* Install other python packages required for building pyemaps, using pip:\r\n\r\n ``` \r\n\r\n pip install setuptool wheel numpy build\r\n\r\n ```\r\n\r\n* Install Microsoft Visual Studio 2019 Community with build tools \r\n\r\n https://visualstudio.microsoft.com/vs/older-downloads/\r\n\r\n by selecting \"Desktop development with C++\" in the installer.\r\n\r\n (You may need a microsoft account to be able to download)\r\n\r\n* Build directory structure:\r\n\r\n\r\n\r\n<pre>\r\n\r\n\ud83d\udce6pyemaps\r\n\r\n \u2523\u2501 \ud83d\udcc2.git <----Source repository configurations\r\n\r\n \u2523\u2501 \ud83d\udcc2build <----Intermediate build folder\r\n\r\n \u2523\u2501 \ud83d\udcc2dist <----Build package files\r\n\r\n \u2523\u2501 \ud83d\udcc2cdata <----Built-in crystal data in proprietory format\r\n\r\n \u2523\u2501 \ud83d\udcc2CifFile <----CIF crystal data reader\r\n\r\n \u2523\u2501 \ud83d\udcc2diffract <----Diffraction modules python interfaces\r\n\r\n \u2523\u2501 \ud83d\udcc2docs <----Documentation using Sphinx. Document your changes!\r\n\r\n \u2523\u2501 \ud83d\udcc2samples <----Sample code. Offical sample code for guiding pyemaps usages\r\n\r\n \u2523\u2501 \ud83d\udcc2scattering <----Scattering data module\r\n\r\n \u2523\u2501 \ud83d\udcc2spg <----Space group data module\r\n\r\n \u2517\u2501 \ud83d\udcc2test <----Test cases including sanity, unit and stree tests. Keep adding them!\r\n\r\n</pre>\r\n\r\nwhere _docs_ for creation of documents requires Sphinx python package:\r\n\r\n- Sphinx for documentation can be installed:\r\n\r\n```\r\n\r\n pip install Sphinx=5.3.0\r\n\r\n```\r\n\r\n\r\n\r\n* Build pyEMAPS package, run:\r\n\r\n ```\r\n\r\n python build_pyemaps -t -v 1.0.0\r\n\r\n ```\r\n\r\n Here the option \"-t\" indicates build is for local testing purposes. \r\n\r\n You can replace the version number '1.0.0' with the one you desire.\r\n\r\n\r\n\r\n When the option _-v_ is not specified. The build script will figure out the version\r\n\r\n from pypi.org repository.\r\n\r\n\r\n\r\n Note: there will be two additional diretcories:\r\n\r\n - _build_. folder holding intermediate build files.\r\n\r\n - _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. \r\n\r\n\r\n\r\n## Installation [`\u21a9`](#contents) <a id=\"installation\"></a>\r\n\r\n\r\n\r\n* Install the new pyEMAPS package:\r\n\r\n ```\r\n\r\n pip .\\dist\\pyemaps-1.0.0-cp37-cp37m-win_amd64.whl\r\n\r\n ```\r\n\r\n This will install new pyEMAPS just built in current python virtual environment\r\n\r\n along with all of its dependent packages. \r\n\r\n \r\n\r\n If you have a previous _pyemaps_ with versiual or larger than current package version.\r\n\r\n In that case, you need to uninstall previous version before installing the new package:\r\n\r\n ```\r\n\r\n pip uninstall pyemaps\r\n\r\n ```\r\n\r\n\r\n\r\n## Testing [`\u21a9`](#contents) <a id=\"test\"></a>\r\n\r\n\r\n\r\n Current pyEMAPS development comes with a set of basic testing suites, including \r\n\r\n * sanity checks\r\n\r\n * unit tests\r\n\r\n * stress tests.\r\n\r\n\r\n\r\n To run these test suites, call:\r\n\r\n ```\r\n\r\n .\\test\\sanity\\sanity.bat\r\n\r\n ```\r\n\r\n We are looking for your tests contributions to make the development to keep high quality standards for _pyEMAPS_.\r\n\r\n\r\n\r\n## Development Guidelines [`\u21a9`](#contents) <a id=\"process\"></a>\r\n\r\n\r\n\r\nAs any open source development project, we strongly recommend contributors to adhere to the following guidelines:\r\n\r\n\r\n\r\n* __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.\r\n\r\n\r\n\r\n* __Development Branch__. Create your own branch from 'main' where you work on your changes. The main branch is kept as production base.\r\n\r\n \r\n\r\n* __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.\r\n\r\n\r\n\r\n* __New Tests Additions__. Writing new test cases for the new implementations are strongly encouraged. \r\n\r\n \r\n\r\n* __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. \r\n\r\n \r\n\r\n* __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. \r\n\r\n \r\n\r\n* __Documentation__. You are the author of the new implementations, so please take the pride by documenting them! \r\n\r\n We use sphinx tool for documentation generation. To install sphinx, run:\r\n\r\n ```\r\n\r\n pip install -U sphinx\r\n\r\n ```\r\n\r\n in your python build virtual environment (pyemaps_build in our example).\r\n\r\n\r\n\r\n Most of the documentations files are in \"docs\" directory. After making documentation changes to record your changes, compile them with sphinx:\r\n\r\n ```\r\n\r\n sphinx-build -b html source .\r\n\r\n ```\r\n\r\n The changes resulted from the above can be previewed by opening index.html with avaliable browser.\r\n\r\n \r\n\r\n## pyEMAPS Contributor License Agreement [`\u21a9`](#contents) <a id=\"CLA\"></a>\r\n\r\n\r\n\r\nPlease read and agree to our [Contributor License Agreement](CONTRIBUTING.md) before contributing to this project.\r\n\r\n\r\n\r\n## Code of Conduct [`\u21a9`](#contents) <a id=\"COC\"></a>\r\n\r\n\r\n\r\npyEMAPS is committed to providing a welcoming and inclusive environment for all contributors. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/) as our code of conduct. Please make sure to review it before contributing.\r\n\r\n\r\n\r\n**[Read the Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)**\r\n\r\n\r\n\r\nAny instances of unacceptable behavior can be reported to support@emlabsoftware.com.\r\n\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "Free for base features. License activation required for extended 4dstem features",
"summary": null,
"version": "1.1.2",
"project_urls": {
"Homepage": "https://www.emlabsolutions.com"
},
"split_keywords": [
"transmission",
" electron",
" diffraction",
" simulation",
" crystallography",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93b677b6f423070689d757317e3a691d1fffa92b14b373d33b34067298d42c1a",
"md5": "28a1101fd22512d66692d1540cb693d1",
"sha256": "37c2ace2eb8a8b107a6acb5bbc00f0044d2b61ed39131e3a9d48391dfecba871"
},
"downloads": -1,
"filename": "pyemaps-1.1.2-cp37-cp37m-win_amd64.whl",
"has_sig": false,
"md5_digest": "28a1101fd22512d66692d1540cb693d1",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 500950,
"upload_time": "2024-12-03T18:05:09",
"upload_time_iso_8601": "2024-12-03T18:05:09.096203Z",
"url": "https://files.pythonhosted.org/packages/93/b6/77b6f423070689d757317e3a691d1fffa92b14b373d33b34067298d42c1a/pyemaps-1.1.2-cp37-cp37m-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8a9c658218e6484ec3e6b5cb22e9261ffacda5771e7d1cbce7f466f58dff69a",
"md5": "82710f5e3c34c779e215ea2d51d69eef",
"sha256": "2d8c6766b55ce2459aa8b4c82b43a1027ba82638f3b4c7a57f85d1ad47f81236"
},
"downloads": -1,
"filename": "pyemaps-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "82710f5e3c34c779e215ea2d51d69eef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 425315,
"upload_time": "2024-12-03T18:05:10",
"upload_time_iso_8601": "2024-12-03T18:05:10.446998Z",
"url": "https://files.pythonhosted.org/packages/c8/a9/c658218e6484ec3e6b5cb22e9261ffacda5771e7d1cbce7f466f58dff69a/pyemaps-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-03 18:05:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyemaps"
}
JSON