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

Plotting CLI: lmodea-k-plot

lmodea-k-plot reads an existing lmodea.h5 file and produces one plot per command. The command now follows a simple flow:

1. determine the requested plot and command-line/configuration parameters,

2. fetch only the required HDF5 datasets and slices,

3. process the selected data for the requested colouring method,

4. produce the plot and any standalone legend.

The plotting command no longer loads all possible plotting data up front. Instead, each plot function receives a small HDF5-backed data accessor and reads only what it needs.

Usage

lmodea-k-plot plot_type [options]

Available plot types are:

dispersion

Phonon dispersion coloured by local-mode character.

character_evolution

Stacked-area plot showing how selected normal-mode character evolves along the k-point path.

bar

Stacked bar chart of local-mode character for normal modes at one k-point.

similarity_matrix

Heatmap of the mass-weighted cosine similarity between internal-coordinate rows of the Wilson B matrix.

fc_dispersion

Effective force constants as a function of k-point.

Shared options

--input (default: lmodea.h5)

Path to the lmodea-k HDF5 output file.

--output

Output image path. If omitted, the value from plotting.conf is used, then the plot-specific default.

-c / --color-by

Colouring scheme as a numeric code or scheme name. Defaults depend on the plot type.

-i / --coords

Internal coordinate selection, using 1-based indices, comma lists, ranges, or all.

-m / --modes

Normal-mode selection for bar and character_evolution. Uses 1-based indices.

-k / --kpoint

K-point index for bar and similarity_matrix. Uses 1-based indexing.

--sym-keys

Symmetry-key filter, using comma lists or ranges. The values are converted from 1-based input in the same way as coordinate indices.

--xmin / --xmax

X-axis index cutoffs. For dispersion, character evolution, and force-constant dispersion these select k-points. For bar plots they select normal modes. Input is 1-based.

--ymin / --ymax

Y-axis limits.

--cmap

Matplotlib colormap name or built-in lmodea-k colormap. Built-ins are ibm, tol, blackblue, and black.

--palette [path]

Load coordinate or symmetry-key colours from a palette file. If the flag is given without a path, palette.in is used.

--normalise-cnm

Row-normalise CNM amplitudes on the fly so that each normal-mode row sums to one before plotting.

--config (default: plotting.conf)

Python-literal configuration file. Values in this file override the defaults in lmodea_k.plotting._config.DEFAULTS.

Colouring schemes

The following colour schemes are accepted by --color-by.

Code	Name	Main use
0	coord_contribution	Dispersion coloured by the summed contribution of selected coordinates.
2	max_symkey_contribution	Dispersion coloured by the symmetry key of the dominant coordinate.
3	max_coord_contribution	Dispersion coloured by the dominant coordinate.
4	symkey_sum	Dispersion coloured by the symmetry key with the largest summed contribution.
5	coord_fraction	Dispersion coloured by selected-coordinate contribution divided by total contribution.
6	char_coord	Character evolution coloured by coordinate.
7	char_symkey	Character evolution coloured by symmetry key.
8	bar_symkey	Bar plot grouped by symmetry key.
9	bar_coord	Bar plot coloured by coordinate.
10	fc_coord_lines	Force-constant dispersion with one colour per coordinate.
11	fc_coord_range	Reserved for force-constant magnitude colouring.

Data read by each plot

lmodea-k-plot opens the HDF5 file once and passes an HDF5-backed PlotData accessor to the selected plotting function. Dataset shapes are used for validation where possible, so validation does not require reading full arrays.

Plot	Data read
dispersion	Selected rows from normal_modes/frequencies, selected rows from CNM/amplitudes, and selected kpoints/labels. Symmetry keys and coordinate descriptions are read only for colouring schemes that need them. For coord_contribution with explicit --coords and without --normalise-cnm, only those CNM coordinate columns are read.
character_evolution	Selected rows from CNM/amplitudes, selected kpoints/labels, and internal_coordinates/sym_key.
bar	One k-point slice from CNM/amplitudes and internal_coordinates/sym_key.
similarity_matrix	One k-point slice from Wilson_matrices/B_matrix, internal_coordinates/symbols, and internal_coordinates/sym_key.
fc_dispersion	Selected rows from local_modes/effective_force_constants and selected kpoints/labels.

Required datasets

The plotting command can only produce plots for datasets that were written by the original lmodea-k run.

dispersion

Requires --write-normal and --cnm in the analysis run.

character_evolution and bar

Require --cnm.

similarity_matrix

Requires --write-wilson.

fc_dispersion

Requires the local-mode force-constant datasets written by the main analysis.

Palette files

Palette files use one colour rule per line:

coord 1 "#DC267F"
coord 2 "#648FFF"
sym 1 "#FFB000"

Coordinate indices in palette files are 1-based. Trailing # comments are allowed.

Examples

lmodea-k-plot dispersion --color-by 3 --coords 1-3
lmodea-k-plot dispersion --color-by coord_contribution --coords 4,5 --xmin 2 --xmax 20
lmodea-k-plot character_evolution --modes 1,2,3 --color-by 7 --sym-keys 2
lmodea-k-plot bar --kpoint 2 --color-by 8 --palette
lmodea-k-plot similarity_matrix --kpoint 1 --coords 1-30
lmodea-k-plot fc_dispersion --coords 1-5 --cmap tol

Configuration

plotting.conf is optional. It must contain a Python literal dictionary. For example:

{
    "global": {"dpi": 300, "font_size": 9},
    "dispersion": {"scatter_size": 5, "output": "dispersion_custom.png"},
    "bar": {"threshold": 0.02},
}

Command-line options override the relevant configuration values.