picometer

Picometer is a Python 3.10+ package which allows to define and calculate various metrics across multiple crystal structures in a clear and reproducible fashion. It is supposed to be used in tandem with a GUI program such as Mercury or Olex2 and applied on a series of cif files with consistent labelling.

This is a software for you if you have ever:

• Misclicked and lost your 250-atom selection,
• Tried to fit or calculate metrics for any plane or line,
• Spent a day measuring distances and angles in tens of similar structures,
• Had to redo measurements because of an offensively minor change,

Instead of relying on a graphical interface, picometer reads settings and instructions from an input .yaml file to probe one or many consistently-named structures concurrently. The results are output in a form of a .csv file, which can be then opened in a spreadsheet editor for further analysis. Because of that, picometer is a handy tool to save time on dumb repeatable labor and focus on what really matters.

Installation

If you are installing python solely to run picometer or are not concerned about introducing additional dependencies, installing picometer is as simple as running:

pip install picometer

However, it is advised to install picometer in a designated virtual environment. This is best achieved by following the linked instructions, but can be otherwise summarised as follows:

1. Make sure you have Python 3.10+ installed: python --version
2. Create a virtual environment using i.e. venv: python -m venv /path/to/virtual_environment
3. Activate your virtual environment:
   • Windows: \path\to\virtual_environment\Scripts\activate
   • Unix/macOS: source /path/to/virtual_environment/bin/activate
4. Install picometer and its dependencies: pip install picometer

The code is currently updated with an intention to be available for download directly from pip:

$ pip install picometer

Usage

Whenever you want to use picometer, first re-activate the virtual environment created during installation following instructions therein. Running the program with no arguments produces the help string.

python -m picometer

usage: picometer [-h] filename

Precisely define and measure across multiple crystal structures

positional arguments:
  filename    Path to yaml file with routine settings and instructions

options:
  -h, --help  show this help message and exit

Author: Daniel Tchoń, baharis @ GitHub

Picometer inputs its settings and instructions from an input .yaml file. The file can contain a dictionary of settings, as well as a list of instructions. The list of instructions, called also a "routine", must include only single-element maps in the - instruction: detail or - instruction: {details} format. Examples of instruction files are available in the tests directory. The easiest way to generate your file is to prepare it based on the example provided.

Instructions

The following instructions are currently supported by picometer:

• Input/output instructions
  • load model from a cif file, given filename or mapping syntax: {path: filename.cif, block: cif_block}.
  • write table with all evaluations to a csv file.
• Selection instructions
  • select atoms, groups, or shapes to be used; use raw element names or provide symmetry relation / recenter using mapping syntax, for example: {label: C(11), symm: x;-y;z+1/2, at: Fe(1)}. By default, selection is cleared after calling select with no arguments or calling an aggregating or evaluating instruction.
  • recenter selection around a new centroid; this action is applied to every selected item individually, so to recenter fixed group of atoms, group them first and recenter this group - otherwise you will recenter individual atoms instead.
• Aggregation instructions
  • group current selection into a new object with fixed elements.
  • fit centroid to the current atom / centroid selection;
  • fit line to the current atom / centroid selection;
  • fit plane to the currect atom / centroid selection;
• Evaluation instructions
  • write out fractional coordinates of currently selected centroids or atoms.
  • write out displacement parameters of currently selected centroids or atoms (note: currently does not correctly handle symmetry transformations).
  • measure distance between 2 selected objects; if the selection includes groups of atoms, measure closes distance to the group of atoms.
  • measure angle between 2–3 selected objects: planes, lines, or (ordered) atoms.
  • measure dihedral andle between 4 individually-selected ordered centroids/atoms.

Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

picometer was created by Daniel Tchoń. It is licensed under the terms of the MIT license.

Credits

This software has been written as a hobby project of Daniel Tchoń (email: dtchon at lbl dot gov, or other address currectly available on https://dtools.pl/about/). All contributions and suggestions are heartily welcome!

picometer was created with the help of cookiecutter and the py-pkgs-cookiecutter template. It is published with the help of poetry, Python Semantic Versioning, and Gitmoji.