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), orthogonal complement (o), 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.

--eigval-min (default: 1e-8)#

Minimum Hessian eigenvalue in atomic units (Hartree bohr–2). Eigenvalues below this threshold are set to eigval-min. This is to ensure that exact zeros or small negative eigenvalues at the \(\Gamma\)-point don’t lead to singularities in the compliance matrix, see Ref. [1] for details.

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

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

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

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

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