.. include:: /_substitutions.rst Command-line options ==================== Main analysis CLI: ``lmodea-k`` ------------------------------- - ``filename`` [:ref:`filename `] - ``--program`` / ``-p`` [:ref:`--program `] - ``--coord-spec`` [:ref:`--coord-spec `] - ``--coord-types`` [:ref:`--coord-types `] - ``--cutoff`` / ``-c`` [:ref:`--cutoff `] - ``--wavevector`` / ``-k`` [:ref:`--wavevector / -k `] - ``--eigval-min`` [:ref:`--eigval-min `] - ``--B-method`` / ``-m`` [:ref:`--B-method `] - ``--rot-axis`` [:ref:`--rot-axis `] - ``--mol`` [:ref:`--mol `] - ``--no-reduce`` [:ref:`--no-reduce `] - ``--no-asr`` [:ref:`--no-asr `] - ``--write-coords`` [:ref:`--write-coords `] - ``--cnm`` [:ref:`--cnm `] - ``--write-adiabatic`` [:ref:`--write-adiabatic `] - ``--write-normal`` [:ref:`--write-normal `] - ``--write-wilson`` [:ref:`--write-wilson `] - ``--help`` [:ref:`--help `] Required ^^^^^^^^ .. _cli-filename: ``filename`` (positional) ************************* Path to input file. The required input file depends on the ``--program`` keyword specifying the interface used. See :ref:`interfaces-page` for input file requirements. Core options ^^^^^^^^^^^^ .. _cli-program: ``-p`` / ``--program`` (default: *CASTEP*, case-insensitive) ************************************************************ Input file format: ``castep``, ``castep-phonon``, ``phonopy``, or ``dynmat``, see :ref:`interfaces-page` for details. .. _cli-coord-spec: ``--coord-spec`` (default: *coords.in*) *************************************** Path to a coordinate specification input file, listing internal coordinates to include in the analysis. If ``--coord-spec`` specified without an argument, the file ``coords.in`` in the current directory is used. If the option is not specified at all, no coordinate specification file is read and coordinates are determined automatically according to ``--coord-types``. .. _cli-coord-types: ``--coord-types`` (default: *badto*) ************************************ String of letters specifying which internal coordinates to include in the automatic search, e.g. bonds (``b``), angles (``a``), dihedrals (``d``), translations (``t``), orthogonal complement (``o``), etc.. See :ref:`internal-coordinates-page` for a complete list of supported internal coordinates. The automatic search uses default bonding cutoffs, which can be modified via the ``--cutoff`` parameter. If ``--coord-spec`` is provided, the internal coordinates listed in the specification file are used and no automatic coordinate search is performed. In this case the ``--coord-types`` option is ignored. .. _cli-cutoff: ``-c`` / ``--cutoff`` ********************* Override default bonding cutoffs used to determine atomic connectivity. Accepts custom bond cutoffs in the format ``Element1-Element2=max`` or ``Element1-Element2=min-max``, e.g. ``O-O=2.6 C-H=0.8-1.2``, with distances specified in :math:`\AA`. By default, bond cutoffs specified in ``lmodea_k/utils/bond_cutoffs.py`` are used to determine the connectivity matrix, which is the basis for the internal coordinate search. Providing custom bond cutoffs using this parameter allows to overwrite the default bonding cutoffs. This can be used to: - capture bonds with atypical lengths in the studied system - exclude bonds of a given type from the analysis, e.g. by setting the maximum bond length for a pair of elements to a sufficiently small number - capture internal coordinates between nonbonded atoms, by setting the bond length range for relevant pairs of elements to treat them as effectively connected .. _cli-wavevector: ``-k`` / ``--wavevector`` (default: *all*) ******************************************* Indices of wavevectors from the input file to perform analysis at, e.g. ``2`` (single index), ``0-3`` (index range, inclusive), ``1,4,7`` (comma-separated list of indices). This parameter uses zero-based indexing. .. _cli-eigval-min: ``--eigval-min`` (default: *1e-8*) ********************************** Minimum Hessian eigenvalue in atomic units (Hartree bohr\ :sup:`--2`). Eigenvalues below this threshold are set to ``eigval-min``. This is to ensure that exact zeros or small negative eigenvalues at the :math:`\Gamma`-point don't lead to `singularities in the compliance matrix `_, see Ref. [1]_ for details. .. _cli-bmethod: ``-m`` / ``--B-method`` (default: *primitive*) ********************************************** B matrix construction method. The default setting ``primitive`` constructs a wavevector-dependent :math:`\mathbf{B}(\mathbf{k})` matrix at each wavevector, corresponding to the `k-dependent B-matrix method `_ in Ref. [1]_. This :math:`\mathbf{B}(\mathbf{k})` matrix encodes wavevector-dependent phase relations in atomic displacements within the internal coordinate derivatives. The alternative ``supercell`` method implements the `expanded B-matrix method `_ in Ref. [1]_. This method treats the phase relations explicitly by expanding the B matrix to include derivatives with respect to all atoms necessary to define the internal coordinate set. This includes atoms beyond the primitive cell. The two methods should yield identical results, and the more expensive ``supercell`` method is only provided for validation or debugging purposes. The :ref:`B matrix stored in the output file ` always corresponds to the one generated using the ``primitive`` method (shape ``(n_ic, 3*n_atoms)``) even if the ``supercell`` method was used for analysis. If needed, the ``supercell`` B matrix can be re-constructed directly from the :ref:`internal coordinate derivatives ` stored in the :ref:`output file `. Special coordinate options ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _cli-rot-axis: ``--rot-axis`` (default: *disabled*) ************************************ This option is intended for use in one-dimensional systems, in which energy is invariant with respect to rigid-body rotation around the periodic axis. Setting ``--rot-axis`` to ``x``, ``y``, or ``z`` applies rotational zero-mode correction around the specified axis. .. _cli-mol: ``--mol`` ********* This option is intended for use in molecular crystals when special :ref:`rigid-body molecular coordinates ` are included in the analysis. The keyword is used to specify allowed molecular fragments, e.g. ``CH3COO Na``, to constrain the molecule identification algorithm. Each fragment represents a connected group of atoms that should be treated as a rigid body. It is recommended that this keyword is always used when molecular translation (``m``) and rotation (``q``) coordinates are requested for analysis using the ``--coord-types`` :ref:`keyword `. Workflow toggles ^^^^^^^^^^^^^^^^ .. _cli-no-reduce: ``--no-reduce`` *************** Keep redundant internal coordinates. By default, |LModeAk| performs QR decomposition to identify linear dependencies in the internal coordinate set based on the :math:`\Gamma`-point B matrix, reduce the internal coordinates used for analysis to a minimal linearly-independent set (note that this does not guarantee orthogonality). Specifying the ``--no-reduce`` flag disables this behaviour, resulting in the full set of internal coordinates being used for analysis. .. _cli-no-asr: ``--no-asr`` ************ Disable acoustic sum rule correction at the :math:`\Gamma`-point. By default, |LModeAk| projects out translational components from the normal mode eigenvectors to ensure strictly translational acoustic modes at the :math:`\Gamma`-point, and hence zero contributions from these acoustic modes to the local modes (except for special translational coordinates). This behaviour is disabled by specifying the ``--no-asr`` flag. .. .. _cli-no-complete: .. ``--no-complete`` .. ***************** .. Skip B matrix completion when rank-deficient. .. By default, |LModeAk| automatically augments rank-deficient B matrices to a full :math:`\mathrm{rank} = 3N_\mathrm{atoms}`. This uses the QR method to construct additional rows that span the orthogonal complement of the row space of the :math:`\Gamma`-point B matrix. The complementing rows may not correspond to localised or chemically interpretable internal coordinates, but they ensure that the internal coordinate set spans all :math:`3N_\mathrm{atoms}` degrees of freedom of the studied system. Specifying the ``--no-complete`` flag disables this behaviour, allowing rank-deficient B matrices to be used in the analysis. Outputs ^^^^^^^ .. _cli-write-coords: ``--write-coords`` ****************** Write ``coords.in`` file specifying coordinates identified in the automatic search. When ``--write-coords`` is requested, the |LModeAk| run terminates after the internal coordinate set has been constructed. .. _cli-vis: Visualisation CLI: ``lmodea-k-vis`` ----------------------------------- Writes the ``.phonon`` and/or ``.json`` visualisation files by reading the existing ``lmodea.h5`` and ``dynmat.h5`` files in the current directory and reformatting the stored eigenvectors and frequencies. No local-mode analysis is performed. Usage:: lmodea-k-vis [--format castep json] [--vis-types ain] - ``--format``: which output format(s) to write. Choose one or both of ``castep`` (writes ``normal.phonon``, ``local.phonon`` and, if Wilson matrices were written, ``internal.phonon`` for visualisation in `Jmol `_) and ``json`` (writes ``normal.json``, ``local.json`` and, if Wilson matrices were written, ``internal.json`` for the `phononwebsite `_). Default: both. - ``--vis-types`` / ``-v``: which displacement datasets to write. A combination of ``n`` (normal modes), ``a`` (adiabatic vectors), and ``i`` (internal distortions). Only datasets present in ``lmodea.h5`` are written; missing datasets produce a warning and are skipped. Default: ``ain``. The ``normal.*`` files are only written if normal modes were included in the ``lmodea.h5`` output (see :ref:`--write-normal `); the ``local.*`` files are only written if adiabatic vectors were included (see :ref:`--write-adiabatic `); and the ``internal.*`` files are only written if Wilson matrices were written (see :ref:`--write-wilson `). Missing datasets produce a warning and are skipped. .. _cli-cnm: ``--cnm`` ******** Compute and write the :ref:`CNM ` dataset (``CNM/amplitudes``) to the output file. By default, CNM amplitudes are **not** computed or written. Specifying this flag enables the local mode–normal mode similarity metric and writes it to the ``CNM`` group of the output file. .. _cli-write-adiabatic: ``--write-adiabatic`` ********************* Write the ``local_modes/adiabatic_vectors`` dataset to the output file. By default, adiabatic vectors are **not** written. Specifying this flag enables writing of the adiabatic displacement vectors for each local mode at each wavevector. .. _cli-write-normal: ``--write-normal`` ****************** Compute and write the :ref:`normal mode ` datasets (``normal_modes/frequencies`` and ``normal_modes/eigenvectors``) to the output file. By default, normal modes are **not** computed or written. Specifying this flag enables the normal-mode calculation and writes the corresponding datasets. The ``normal.json`` / ``normal.phonon`` outputs of ``lmodea-k-vis`` that depend on normal modes are only produced when this flag is set. .. _cli-write-wilson: ``--write-wilson`` ****************** Write the :ref:`Wilson matrices ` (``Wilson_matrices/G_diagonal``, ``Wilson_matrices/B_matrix``, ``Wilson_matrices/D_matrix``) to the output file. By default, Wilson matrices are **not** written. This flag is required for the ``internal.json`` / ``internal.phonon`` outputs of ``lmodea-k-vis``. Help ^^^^ .. _cli-help: ``lmodea-k --help`` ******************* Prints the live option list with defaults. Plotting CLI: ``lmodea-k-plot`` ------------------------------- Quick overview (full help: ``lmodea-k-plot --help``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - One figure per run. Choose exactly one: ``--dispersion``, ``--character-evolution``, ``--bar``. - Indices are **1-based** on input (k-points, internal coordinates, normal modes) and shown as 1-based on the plots. - Default input: ``lmodea.h5`` (``--input``). Colormap override: ``--cmap `` (matplotlib or built-in). - Axis cut-offs: ``--xmin`` / ``--xmax`` (k-point for dispersion/character; mode index for bar), ``--ymin`` / ``--ymax`` (wavenumber for dispersion; ignored for character evolution y-axis). - Palette: ``--palette [path]``; if no path is given, ``./palette.in`` is used. Lines (1-based indices): ``coord ""`` or ``sym ""``; hex codes must be quoted; trailing ``#`` comments allowed. - Normalisation: ``--normalise-cnm`` (optional for dispersion/character; always on for bar). Colour selection (numeric ``--color-by``; prompted if omitted) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Dispersion: ``0`` coord_contribution, ``1`` coord_triplet, ``2`` max_symkey, ``3`` max_coord, ``4`` symkey_sum, ``5`` coord_fraction. - Character evolution: ``6`` per-coordinate colours; ``7`` by symmetry key (coords sharing a sym key share a colour). - Bar: ``8`` bars coloured by sym key (one bar per coordinate); ``9`` bars coloured per coordinate. Defaults: continuous schemes → ``gnuplot``; sequential schemes → ``ibm`` unless overridden by ``--cmap`` or config. Plot-specific selectors ^^^^^^^^^^^^^^^^^^^^^^^ - Dispersion: coordinate filter ``-i/--internal-coords`` (default all). - Character evolution: modes ``-m/--modes`` (comma/range list, 1-based); coordinate filter ``-i``; sym-key filter ``--sym-keys``. - Bar: k-point ``-k/--kpoint-index`` (default 1); coordinate filter ``-i``; sym-key filter ``--sym-keys``. Outputs ^^^^^^^ - Plots saved to filenames from ``plotting.conf`` (defaults: ``dispersion.png``, ``character_evolution.png``, ``decomposition.png``). - Legends are written as separate ``*_legend`` images when applicable; continuous schemes place a colour bar above the plot. Examples ^^^^^^^^ - Dispersion coloured by dominant coord, coords 1–3: ``lmodea-k-plot --dispersion -i 1-3 -c 3`` - Character evolution for modes 1,2,3 coloured by sym key: ``lmodea-k-plot --character-evolution --modes 1,2,3 --sym-keys 2 -c 7`` - Bar chart at k-point 2 with custom palette: ``lmodea-k-plot --bar -k 2 --palette`` References ^^^^^^^^^^ .. [1] M.\ Mojsak, F. Bodo, A. Erba, A. A. L. Michalchuk, and E. Kraka, *J. Chem. Theory Comput.*, 2026, **???**, ???. (see :doc:`cite`) CNM Analysis CLI: ``lmodea-k-cnm`` ---------------------------------- This command reads existing ``lmodea.h5`` and ``dynmat.h5`` files and computes advanced CNM (Characterisation of Normal Modes) methods, including de-overlapped Konkoli-Cremer amplitudes that remove contributions from overlapping internal coordinates. This is a post-processing step that enhances the CNM data generated by ``lmodea-k --cnm``. Usage:: lmodea-k-cnm [options] Options ^^^^^^^ - ``--lmodea-h5``: path to lmodea.h5 file (default: ``lmodea.h5``) - ``--dynmat-h5``: path to dynmat.h5 file (default: ``dynmat.h5``) - ``-o/--output``: output HDF5 file path (default: overwrite lmodea.h5) - ``--method``: de-overlapping method (default: ``normalize_sum``): - ``normalize_sum``: normalize so contributions sum to 1 per mode - ``orthogonalise``: orthogonalise overlapping contributions using QR - ``project``: project out contributions using symmetry keys - ``none``: return original amplitudes unchanged - ``--in-place``: modify lmodea.h5 in place instead of creating a new file - ``--verbose/-v``: print detailed progress information Output ^^^^^^ The command writes the following datasets to the output file: - ``CNM/amplitudes_deoverlapped``: de-overlapped CNM amplitudes - ``CNM/amplitudes_normalised``: normalised amplitudes (for plotting compatibility) - ``CNM/dominant_coord``: index of dominant coordinate per mode - ``CNM/max_amplitude``: maximum amplitude per mode - ``CNM/character_cumsum``: cumulative sum of sorted amplitudes - ``CNM/coords_for_90_percent``: number of coords needed for 90% character - ``local_modes/sym_keys``: symmetry keys (for plotting compatibility) Examples ^^^^^^^^ - Compute de-overlapped amplitudes in-place:: lmodea-k-cnm --in-place - Create a new output file with custom de-overlapping:: lmodea-k-cnm -o cnm_output.h5 --method orthogonalise