==============================
phenix.explore_metric_symmetry
==============================

Purpose
-------
``phenix.explore_metric_symmetry`` is a program that allows a user to quickly
determine the symmetry of the lattice, given a unit cell, and determine
relations between various possible point groups.

Another use of ``phenix.explore_metric_symmetry`` is in the comparison of
related unit cells, that are related by a linear recombination of their basis
vectors.

Keywords
--------

A list of keywords and concise help can be obtained by typing::

  phenix.explore_metric_symmetry

Output::

  Usage: phenix.explore_metric_symmetry [options]

  Options:
    -h, --help            show this help message and exit
    --unit-cell=10,10,20,90,90,120|FILENAME
                          External unit cell parameters
    --space-group=P212121|FILENAME
                          External space group symbol
    --symmetry=FILENAME   External file with symmetry information
    --max-delta=FLOAT     Maximum delta/obliquity used in determining the
                          lattice symmetry, using a modified Le-Page algorithm.
                          Default is 5.0 degrees
    --start-from-p1       Reduce to Niggli cell and forget the input spacegroup
                          before higher metric symmetry is sought.
    --graph=GRAPH         A graphical representation of the graph will be
                          written out. Requiers Graphviz to be installed and in
                          path.
    --centring-type=CENTRING_TYPE
                          Centring type, choose from P,A,B,C,I,R,F
    --other-unit-cell=10,20,30,90,103.7,90
                          Other unit cell, for unit cell comparison
    --other-space-group=OTHER_SPACE_GROUP
                          space group for other_unit_cell, for unit cell
                          comparison
    --other-centring-type=OTHER_CENTRING_TYPE
                          Centring type, choose from P,A,B,C,I,R,F
    --no-point-group-graph
                          Do not carry out the construction of a point group
                          graph.
    --relative-length-tolerance=FLOAT
                          Tolerance for unit cell lengths to be considered
                          equal-ish.
    --absolute-angle-tolerance=FLOAT
                          Angular tolerance in unit cell comparison
    --max-order=INT       Maximum volume change for target cell

  Explore Metric Symmetry. A list of possible unit cells and spacegroups is
  given for the given specified unit cell and spacegroup combination. If a
  second unit cell is given, linear combinations of the basis vector of one
  unit cell are sought that match the other.


The keywords ``unit_cell``, ``space_group`` (or ``centring_type``) define the
crystal symmetry for which a point group graph is constructed.

The keyword ``max_delta`` sets the tolerance used the in determination of the lattice
symmetry.

the keyword ``start_from_p1`` in combination with the space group is equivalent
to specification of the ``centring_type`` only.

If `graphviz`_ is installed, an a png file with the point group graph can be
constructed by specifying the filename of the png graph with the keyword
``graph``.

If a second crystal is specified by the keywords ``other_unit_cell``,
``other_space_group`` (or ``other_centring_type``) the unit cells will be
compared. Using linear combinations of the smallest unit cell, possible
matches for the large unit cell are sought.
If desired, the larger unit cell can be expanded as well using the keyword
``max_order``.

The tolerances in the unit cell comparison can be changed form their defaults
(10% on the lengths and 20 degrees on the angles)
using the keywords ``relative_length_tolerance`` and ``absolute_angle_tolerance``.

Construction of a point group graph can be skipped using the key
``no_point_group_graph``.


Examples
--------

Constructing a point group graph given some basic information::

  phenix.explore_metric_symmetry --unit_cell="20,30,40,90,90,90" --centring_type=P

All point groups between ``P 1`` and ``P 2 2 2`` will be listed

Comparing two related unit cells can be done using::

  phenix.explore_metric_symmetry --unit_cell="20,30,40,90,90,90" --centring_type=P --other_unit_cell="40,80,60,90,90,90" --other_centring_type=F


.. _`graphviz` : http://graphviz.org/