.. include:: /_substitutions.rst 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 `] - ``--reduce`` [:ref:`--reduce `] - ``--no-asr`` [:ref:`--no-asr `] - ``--ignore-negative`` [:ref:`--ignore-negative `] - ``--no-sort`` [:ref:`--no-sort `] - ``--zero-acoustic`` [:ref:`--zero-acoustic `] - ``--write-coords`` [:ref:`--write-coords `] - ``--cnm`` [:ref:`--cnm `] - ``--write-adiabatic`` [:ref:`--write-adiabatic `] - ``--write-normal`` [:ref:`--write-normal `] - ``--write-wilson`` [:ref:`--write-wilson `] - ``--write-all`` [:ref:`--write-all `] - ``--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-reduce: ``--reduce`` ^^^^^^^^^^^^ Reduce redundant internal coordinates. By default, |LModeAk| keeps the full set of internal coordinates, including possible linear dependencies. Specifying the ``--reduce`` flag performs QR decomposition to identify linear dependencies in the internal coordinate set based on the :math:`\Gamma`-point B matrix, reducing the internal coordinates used for analysis to a minimal linearly-independent set (note that this does not guarantee orthogonality). .. _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-ignore-negative: ``--ignore-negative`` ^^^^^^^^^^^^^^^^^^^^^ Ignore negative eigenvalues at nonzero wavevectors. By default, negative eigenvalues at nonzero wavevectors are treated as an error. Specifying the ``--ignore-negative`` flag allows the calculation to continue when such eigenvalues are encountered. .. _cli-no-sort: ``--no-sort`` ^^^^^^^^^^^^^ Disable internal coordinate sorting. By default, internal coordinates are sorted by symmetry equivalence and value before analysis. Specifying the ``--no-sort`` flag preserves the construction order instead. This is not recommended for normal use. .. _cli-zero-acoustic: ``--zero-acoustic`` ^^^^^^^^^^^^^^^^^^^ Explicitly zero acoustic mode contributions at the :math:`\Gamma`-point. This is separate from the acoustic sum rule correction controlled by ``--no-asr``. When specified, acoustic mode contributions are forced to zero at the :math:`\Gamma`-point. .. .. _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-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``. .. _cli-write-all: ``--write-all`` ^^^^^^^^^^^^^^^ Write all optional analysis outputs. Specifying this flag is equivalent to setting ``--write-normal``, ``--write-wilson``, ``--write-adiabatic``, and ``--cnm``. It does not imply ``--write-coords``, which is a separate coordinate-writing workflow. Help ---- .. _cli-help: ``lmodea-k --help`` ^^^^^^^^^^^^^^^^^^^ Prints the live option list with defaults. References ---------- .. [1] M.\ Mojsak, F. Bodo, A. Erba, A. A. L. Michalchuk, and E. Kraka, *J. Chem. Theory Comput.*, 2026, **???**, ???. (see :doc:`cite`)