Ctrl+K

diffsims 0.6.dev0 documentation#

diffsims is an open-source Python library for simulating diffraction.

User guide#

See the demos for how to use diffsims.

Installation#

diffsims can be installed from Anaconda, the Python Package Index (pip), or from source, and supports Python >= 3.6.

With pip#

diffsims is availabe from the Python Package Index (PyPI), and can therefore be installed with pip. To install, run the following:

pip install diffsims

To update diffsims to the latest release:

pip install --upgrade diffsims

To install a specific version of diffsims (say version 0.5.1):

pip install diffsims==0.5.1

With Anaconda#

To install with Anaconda, we recommend you install it in a conda environment with the Miniconda distribution. To create an environment and activate it, run the following:

conda create --name diffsims-env python=3.10
conda activate diffsims-env

If you prefer a graphical interface to manage packages and environments, you can install the Anaconda distribution instead.

To install:

conda install diffsims --channel conda-forge

To update diffsims to the latest release:

conda update diffsims

To install a specific version of diffsims (say version 0.5.1):

conda install diffsims==0.5.1 -c conda-forge

From source#

The source code is hosted on GitHub. One way to install diffsims from source is to clone the repository from GitHub, and install with pip:

git clone https://github.com/pyxem/diffsims.git
cd diffsims
pip install --editable .

The source can also be downloaded as tarballs or zip archives via links like pyxem/diffsims, where the version <major.minor.patch> can be e.g. 0.5.1, and tar.gz can be exchanged with zip.

API reference#

Release:

Date: Apr 16, 2024

This reference manual describes the public functions, modules, and objects in diffsims. Some of the descriptions include brief examples. For learning how to use diffsims, see the demos.

Caution

diffsims is in continuous development, meaning that some breaking changes and changes to this reference are likely with each release.

Modules

crystallography

Generation of reciprocal lattice vectors (crystal plane, reflector, g, hkl) for a crystal structure.

generators

Generation of diffraction simulations and libraries, and lists of rotations.

libraries

Diffraction, structure and vector libraries.

pattern

Addition of noise to patterns.

sims

Diffraction simulations.

structure_factor

Calculation of scattering factors and structure factors.

utils

Diffraction utilities used by the other modules.

Contributing#

This guide is intended to get new developers started with contributing to diffsims.

Many potential contributors will be scientists with much expert knowledge but potentially little experience with open-source code development. This guide is primarily aimed at this audience, helping to reduce the barrier to contribution.

We have a Code of Conduct that must be honoured by contributors.

Start using diffsims#

The best way to start understanding how diffsims works is to use it.

For developing the code the home of diffsims is on GitHub and you’ll see that a lot of this guide boils down to using that platform well. so visit the following link and poke around the code, issues, and pull requests (PRs): diffsims on GitHub.

It’s probably also worth visiting the GitHub guides to get a feel for the terminology.

In brief, to give you a hint on the terminology to search for, the contribution pattern is:

  1. Setup git/GitHub if you don’t have it.

  2. Fork diffsims on GitHub.

  3. Checkout your fork on your local machine.

  4. Create a new branch locally where you will make your changes.

  5. Push the local changes to your own github fork.

  6. Create a PR to the official diffsims repository.

Note: You cannot mess up the main diffsims project. So when you’re starting out be confident to play, get it wrong, and if it all goes wrong you can always get a fresh install of diffsims!

PS: If you choose to develop in Windows/Mac you may find the Github Desktop useful.

Questions?#

Open source projects are all about community - we put in much effort to make good tools available to all and most people are happy to help others start out. Everyone had to start at some point and the philosophy of these projects centers around the fact that we can do better by working together.

Much of the conversation happens in ‘public’ using the ‘issues’ pages on GitHub – doing things in public can be scary but it ensures that issues are identified and logged until dealt with. This is also a good place to make a proposal for some new feature or tool that you want to work on.

Good coding practice#

The most important aspects of good coding practice are: (1) to work in manageable branches, (2) develop a good code style, (3) write tests for new functions, and (4) document what the code does. Tips on these points are provided below.

Use git to work in manageable branches#

Git is an open source “version control” system that enables you to can separate out your modifications to the code into many versions (called branches) and switch between them easily. Later you can choose which version you want to have integrated into diffsims.

You can learn all about Git here!

The most important thing is to separate your contributions so that each branch is a small advancement on the “master” code or on another branch.

Get the style right#

diffsims closely follows the Style Guide for Python Code - these are just some rules for consistency that you can read all about in the Python Style Guide.

Please run the latest version of black on your newly added and modified files prior to each PR.

If this doesn’t work for you, you can also use the Pre-commit CI to reformat your code on github by commenting “pre-commit autofix” on your PR.

Run and write tests#

All functionality in diffsims is tested via the pytest framework. The tests reside in the diffsims.tests module. Tests are short functions that call functions in diffsims and compare resulting output values with known answers. Good tests should depend on as few other features as possible so that when they break we know exactly what caused it.

Install necessary dependencies to run the tests:

pip install --editable .[tests]

Some useful fixtures are available in the conftest.py file.

To run the tests:

pytest --cov --pyargs diffsims

The --cov flag makes coverage.py print a nice report in the terminal. For an even nicer presentation, you can use coverage.py directly:

coverage html

Then, you can open the created htmlcov/index.html in the browser and inspect the coverage in more detail.

Useful hints on testing:

  • When comparing integers, it’s fine to use ==. When comparing floats use something like assert np.allclose(shifts, shifts_expected, atol=0.2).

  • @pytest.mark.parametrize() is a convenient decorator to test several parameters of the same function without having to write to much repetitive code, which is often error-prone. See pytest documentation for more details.

Build and write documentation#

Docstrings – written at the start of a function – give essential information about how it should be used, such as which arguments can be passed to it and what the syntax should be. The docstrings mostly follow the numpydoc standard.

We use Sphinx for documenting functionality. Install necessary dependencies to build the documentation:

pip install -e .[doc]

Then, build the documentation from the doc directory:

cd doc
make html

The documentation’s HTML pages are built in the doc/build/html directory from files in the reStructuredText (reST) plaintext markup language. They should be accessible in the browser by typing file:///your-absolute/path/to/diffsims/doc/build/html/index.html in the address bar.

Continuous integration (CI)#

We use GitHub Actions to ensure that diffsims can be installed on Windows, macOS and Linux. After a successful installation, the CI server runs the tests. After the tests return no errors, code coverage is reported to Coveralls.

Learn more#

  1. The Python programming language, for beginners.

Changelog#

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project tries its best to adhere to Semantic Versioning.

Unreleased#

Added#

  • Explicit support for Python 3.11.

  • Added Pre-Commit for code formatting.

Changed#

  • Documentation theme from Furo to the PyData-Sphinx-Theme.

  • Ran black formatting to update the code style.

Deprecated#

Removed#

  • Removed support for Python 3.6 and Python 3.7, leaving 3.8 as the oldest supported version.

Fixed#

2023-05-22 - version 0.5.2#

Fixed#

  • Always use no-python mode to silence Numba deprecation warnings.

2023-01-25 - version 0.5.1#

Fixed#

  • ReciprocalLatticeVector.allowed rounds indices (hkl) internally to ensure correct selection of which vectors are allowed or not given a lattice centering. Integer indices are assumed.

Deprecated#

  • Support for Python 3.6 is deprecated and will be removed in v0.6.

2022-06-10 - version 0.5.0#

Added#

  • Extra parameters in diffraction pattern’s plot method for drawing miller index labels next to the diffraction spots.

  • Option to use None for scattering_params which ignores atomic scattering.

  • Python 3.10 support.

  • Class ReciprocalLatticeVector for handling generation, handling and plotting of vectors. This class replaces ReciprocalLatticePoint, which is deprecated.

Changed#

  • Minimal version of dependencies orix >= 0.9, numpy >= 1.17 and tqdm >= 4.9.

  • The Laue group representing the rotation list sampling of “hexagonal” from 6/m to 6/mmm.

  • Loosened the angle tolerance in DiffractionLibrary.get_library_entry() from 1e-5 to 1e-2.

Deprecated#

  • Class ReciprocalLatticePoint is deprecated and will be removed in v0.6. Use ReciprocalLatticeVector instead.

2021-04-16 - version 0.4.2#

Added#

  • Simulations now have a .get_as_mask() method (#154, #158)

  • Python 3.9 testing (#161)

Changed#

  • Simulations now use a fractional (rather than absolute) min_intensity (#161)

Fixed#

  • Precession simulations (#161)

2021-03-15 - version 0.4.1#

Changed#

  • get_grid_beam_directions default meshing changed to “spherified_cube_edge” from “spherified_cube_corner”

Fixed#

  • get_grid_beam_directions now behaves correctly for the triclinic and monoclinic cases

2021-01-11 - version 0.4.0#

Added#

  • API reference documentation via Read The Docs: https://diffsims.readthedocs.io/en/latest/

  • New module: sphere_mesh_generators

  • New module: detector_functions

  • New module: ring_pattern_utils

  • beam precession is now supported in simulating electron diffraction patterns

  • plot method for DiffractionSimulation

  • more shape factor functions have been added

  • This project now keeps a Changelog

Changed#

  • get_grid_beam_directions, now works based off of meshes

  • the arguments in the DiffractionGenerator constructor and the DiffractionLibraryGenerator.get_diffraction_library function have been shuffled so that the former captures arguments related to “the instrument/physics” while the latter captures arguments relevant to “the sample/material”.

  • CI is now provided by github actions

Removed#

  • Python 3.6 testing

Fixed#

  • ReciprocalLatticePoint handles having only one point/vector

Installation#

diffsims can be installed with pip or conda:

pip install diffsims

conda install diffsims -c conda-forge

Further details are available in the installation guide.

Learning resources#

Tutorials

In-depth guides for using diffsims.

API reference

Descriptions of all functions, modules, and objects in diffsims.

Contributing

diffsims is a community project maintained for and by its users. There are many ways you can help!

Citing diffsims#

If you are using diffsims in your scientific research, please help our scientific visibility by citing the Zenodo DOI: https://doi.org/10.5281/zenodo.3337900.

diffsims is released under the GPL v3 license.

On this page