Command-line options

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

Command-line options#

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#

--no-reduce#

Keep redundant internal coordinates.

By default, \(\mathrm{LModeA\text{-}}\vec{\mathbf{k}}\) performs QR decomposition to identify linear dependencies in the internal coordinate set based on the \(\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.

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

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.

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 –write-normal); the local.* files are only written if adiabatic vectors were included (see –write-adiabatic); and the internal.* files are only written if Wilson matrices were written (see –write-wilson). Missing datasets produce a warning and are skipped.

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

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

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 <name> (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 <index> "<hex>" or sym <key> "<hex>"; 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#

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