Main analysis CLI: lmodea-k

\(\newcommand{\AA}{\text{Å}}\)

Main analysis CLI: lmodea-k#

Required#

filename (positional)#

Path to input file. The required input file depends on the --program keyword specifying the interface used. See Interfaces for input file requirements.

Core options#

-p / --program (default: CASTEP, case-insensitive)#

Input file format: castep, castep-phonon, phonopy, or dynmat, see Interfaces for details.

--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.

--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), etc.. See Internal coordinates 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.

-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 \(\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

-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.

--freq-min (default: 0.1)#

Minimum frequency threshold for clamping near-zero eigenvalues, in cm-1. Eigenvalues in the near-zero band whose corresponding frequency \(|\omega| \le\) freq-min (e.g. exact zeros or small eigenvalues near the \(\Gamma\)-point) are clamped up to freq-min. This avoids singularities in the compliance matrix, see Ref. [1] for details. The same threshold also defines a true negative eigenvalue: an eigenvalue whose frequency is more negative than -freq-min is treated as a real imaginary mode and is preserved unchanged (only permitted when --allow-negative is set).

-m / --B-method (default: primitive)#

B matrix construction method.

The default setting primitive constructs a wavevector-dependent \(\mathbf{B}(\mathbf{k})\) matrix at each wavevector, corresponding to the k-dependent B-matrix method in Ref. [1]. This \(\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 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 internal coordinate derivatives stored in the output file.

Special coordinate options#

--rot-axis (default: disabled)#

This option controls rotational zero-mode removal in the acoustic sum rule correction. Setting --rot-axis to x, y, or z applies a rotational Eckart correction around the specified Cartesian axis. Setting --rot-axis all applies rotational Eckart corrections around all three Cartesian axes, with linearly dependent rotational vectors removed automatically. The all option is intended for molecular or finite systems where all rotational zero modes should be projected out.

--mol#

This option is intended for use in molecular crystals when special 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 keyword.

Workflow toggles#

--reduce#

Reduce redundant internal coordinates.

By default, \(\mathrm{LModeA\text{-}}\vec{\mathbf{k}}\) 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 \(\Gamma\)-point B matrix, reducing the internal coordinates used for analysis to a minimal linearly-independent set (note that this does not guarantee orthogonality).

--no-asr#

Disable acoustic sum rule correction at the \(\Gamma\)-point.

By default, \(\mathrm{LModeA\text{-}}\vec{\mathbf{k}}\) projects out translational components from the normal mode eigenvectors to ensure strictly translational acoustic modes at the \(\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.

--allow-negative#

Allow true negative eigenvalues (imaginary modes) at any wavevector, including the \(\Gamma\)-point.

By default, \(\mathrm{LModeA\text{-}}\vec{\mathbf{k}}\) raises an error if any eigenvalue smaller than the --freq-min threshold is encountered, because imaginary modes indicate an unstable structure. Specifying the --allow-negative flag permits the calculation to continue with such eigenvalues included. Near-zero eigenvalues (within the band \(|\tilde{\nu}| \le\) freq-min) are always permitted and are handled by eigenvalue clamping; this is the default behaviour that prevents \(K \rightarrow 0\) discontinuities.

--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.

--zero-acoustic#

Explicitly zero acoustic mode contributions at the \(\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 \(\Gamma\)-point.

Outputs#

--write-coords#

Write coords.in file specifying coordinates identified in the automatic search. When --write-coords is requested, the \(\mathrm{LModeA\text{-}}\vec{\mathbf{k}}\) run terminates after the internal coordinate set has been constructed.

--dynmat-only#

Only parse the input file and write the dynmat.h5 file, then exit.

When this flag is specified, \(\mathrm{LModeA\text{-}}\vec{\mathbf{k}}\) reads the input file (e.g. a CASTEP .castep phonon output or Phonopy phonopy.yaml/qpoints.yaml), converts the dynamical matrices to the standard dynmat.h5 format, and terminates cleanly without performing the internal coordinate search or local mode analysis. This is useful for pre-processing input files into the dynmat.h5 format for later use with the dynmat interface.

--cnm#

Compute and write the 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.

--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.

--write-normal#

Compute and write the 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.

--write-wilson#

Write the 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.

--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#

lmodea-k --help#

Prints the live option list with defaults.

References#