hikari.scripts.compare_adps
===========================

.. py:module:: hikari.scripts.compare_adps


Attributes
----------

.. autoapisummary::

   hikari.scripts.compare_adps.t1


Functions
---------

.. autoapisummary::

   hikari.scripts.compare_adps.calculate_similarity_indices
   hikari.scripts.compare_adps.animate_similarity_index


Module Contents
---------------

.. py:function:: calculate_similarity_indices(cif1_path, cif2_path = None, cif1_block = None, cif2_block = None, output_path = None, normalize = False, uncertainties = True)

   Compare Anisotropic Displacement Parameters of all atoms in two cif blocks
   and return a Similarity Index (SI) for these pairs of atoms that exist
   and are defined anisotropic (via "_atom_site_aniso_U_**") in both files.

   This script requires two independent cif blocks to run,
   but the location of both blocks can be specified in multiple ways:

   - If only `cif1_path` is given, the first and second data block from
     cif1 file will be used in SI evaluation;
   - If `cif1_path` and `cif2_path` are given, the first data block from
     each cif file will be used instead;
   - If `cif1_path`, `cif2_path`, and `cif1_block` are given,
     `cif1_block` from each `cif1_path` and `cif2_path` cif files will be used.
   - If `cif1_path`, `cif2_path`, `cif1_block`, and `cif2_block` are given,
     `cif1_block` in `cif1_path` and `cif2_block` in `cif2_path` will be used.

   For a single cif file 'glycine.cif' with two data blocks named '100K' and
   'RT', the three following commands will have the same effect:

   :Example:

   >>> calculate_similarity_indices('glycine.cif')
   >>> calculate_similarity_indices('glycine.cif', 'glycine.cif')
   >>> calculate_similarity_indices('glycine.cif', 'glycine.cif', '100K', 'RT')

   For two cif files 'X-rays.cif' and 'neutrons.cif' with data block named 'RT'
   and '100K' (one each), the two following commands will have the same effect:

   :Example:

   >>> calculate_similarity_indices('X-rays.cif', 'neutrons.cif')
   >>> calculate_similarity_indices('X-rays.cif', 'neutrons.cif', 'RT', '100K')

   The behaviour of script can be further altered via other parameters.
   If `output_file` is set True, the results will be written there instead of
   console. If `uncertainties` is set True, standard deviations of all ADPs
   as well as the unit cell parameters from 1st cif file will be assumed
   uncorrelated and used to estimate the uncertainty of every SI determination.

   For more information about Similarity Index (SI) itself, please consult
   Whitten and Spackman, Acta Cryst B **62**, 875 (2006)
   https://doi.org/10.1107/S0108768106020787.

   :param cif1_path: Absolute or relative path to the first cif file.
   :param cif2_path: Absolute or relative path to the second cif file.
       If not specified, it is assumed equal to `cif1_path`.
   :param cif1_block: Name of the first data block used in SI determination.
       It points to the data block inside the file specified by `cif1_path`.
       If not specified, the first block found in said file will be used.
   :param cif2_block: Name of the second data block used in SI determination.
       It points to the data block inside the file specified by `cif2_path`.
       If not specified, the first unused block in said file will be used.
   :param output_path: Path where the output of the program should be written.
   :param uncertainties: If True, propagate the standard deviations of
       individual ADPs' and cif1's unit cell to estimate SI's uncertainties.
   :param normalize: If True, equalize the volume of displacement ellipsoids
       by normalizing the determinants of ADP matrices expressed in cartesian
       coordinates. As a result, SI is a function of displacement "shape" only.


.. py:function:: animate_similarity_index(u_diag, transformations, output_path)

   Make a gif presenting the change of similarity index against some arbitrary
   series of `transformations`. Initial displacement matrix must be diagonal,
   values given in `u_diag`, evaluated against a regular unit cell with a = 1.

   :param u_diag: triplet of u matrix diagonal elements
   :param transformations: list of transformations to be plotted every 0.1 sec
   :param output_path: path where resulting gif file will be saved


.. py:data:: t1