====================
Command line scripts
====================

convgeom
========
Command line script for converting geometries between formats.

Usage
-----
To convert from one format to another::

    convgeom input_file output_file [options]

By default, the input format is determined from the file structure and the
output format is set by the file extension.

Options
-------
``-i, --in-format``
    The input format (xyz, col, gdat, ...)
``-o, --out-format``
    The output format (xyz, col, gdat, ...)
``-iu, --in-units``
    The input distance units (ang, bohr, ...)
``-ou, --out-units``
    The output distance units (ang, bohr, ...)
``-c, --has-comment``
    Boolean argument, whether or not comment is read
``-v, --has-vector``
    Boolean argument, whether or not vector is read


measure
=======
Command line script for measuring internal coordinates from a geometry file.

Usage
-----
To measure a coordinate for one or multiple geometries in an input file::

    measure input_file coord_type {inds} [options]

The number of indices must match the coordinate type (e.g. 2 for stre,
3 for bend, ...).

Options
-------
``-f, --format``
    The input file format (xyz, col, gdat, ...)
``-u, --units``
    The output units (auto, ang, rad, ...)
``-a, --absolute``
    Boolean argument, if present returns absolute values
``-o, --output``
    The output filename. Defaults to writing to stdout
``-v, --val-format``
    The format of an output value, given as a format string


subst
=====
Command line script for adding substituents to a geometry file.

Usage
-----
To add a substituent to all geometries in an input file::

    subst input_file sublbl {inds} [options]

The inds mark which position is substituted. If multiple indices are
given, the first will be the position of the substituent.

Options
-------
``-i, --in-place``
    Boolean argument, whether or not the geometry file is overwritten.
``-b, --bond-ind``
    The index of the atom bound to the substituent. If not specified,
    the nearest atom is used.
``-p, --plane-ind``
    The index of the atom used to specify the xz-plane of the substituent.
    The substituent index, bonding index and plane index make up the plane.
``-f, --format``
    The input/output format (xyz, col, gdat, ...)
``-c, --has-comment``
    Boolean argument, whether or not comment is read.
``-v, --has-vector``
    Boolean argument, whether or not vector is read.


nudge
=====
Command line script for translating/rotating/reflecting a geometry file.

Usage
-----
To displace a molecule about/along a given axis::

    nudge input_file amp axis_string [options]

The axis (and origin, if given) is parsed based on
:class:`displace.VectorParser`, which interprets integers as indices of
the cartesian coordinates and includes scalar and vector operations.

Options
-------
``-i, --in-place``
    Boolean argument, whether or not the geometry file is overwritten.
``-t, --translate``
    Boolean argument, whether or not translate is used instead of rotate.
``-n, --indices``
    Indices to displace, given as a string of integers separated by spaces.
``-u, --units``
    Units for displacement amplitude.
``-r, --reflect``
    Boolean argument, whether rotation is proper or improper.
``-o, --origin``
    String defining the origin of rotation.
``-f, --format``
    The input/output format (xyz, col, gdat, ...)
``-c, --has_comment``
    Boolean argument, whether or not comment is read.
``-v, --has-vector``
    Boolean argument, whether or not vector is read.