Plotting CLI: lmodea-k-plot

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

Unified dispersion-style plot. Use --quantity to choose normal-mode, local-mode, force-constant, or normal/local overlay data.

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.

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 name. Numeric colour codes are not supported. Defaults depend on the plot type.

--quantity (default: normal for dispersion)

Quantity to plot for the unified dispersion command. Accepted values are normal, local, force_constant, and normal_local. The normal_local mode plots the normal-mode dispersion in black and overlays the local-mode dispersion in colour.

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

--group-by

Grouping source for grouped colour schemes. Choices are coord, symkey, type, and custom. For example, --color-by dominant_group --group-by symkey colours each branch by the symmetry-key group with the largest aggregate CNM amplitude.

--cnm-aggregate

How to combine selected CNM amplitudes for continuous dispersion colouring. Choices are average and maximum.

--cnm-vmax

Upper bound for continuous CNM contribution colours. Use max to end the colour scale at the maximum plotted value, or pass a positive float for a custom upper bound. The default is 1.0.

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

Continuous CNM dispersion colouring can be adjusted in this file:

{
    "dispersion": {
        "color_by": "continuous",
        "group_by": "symkey",
        "cnm_aggregate": "average",  # or "maximum"
        "cnm_vmax": 1.0,              # or "max", or a float
        "colormap": "viridis",
    },
}

Colouring schemes#

The following named colour schemes are accepted by --color-by:

  • black — plot all branches in black.

  • continuous — normal-mode dispersion coloured continuously by selected CNM amplitudes. Use --cnm-aggregate to choose averaging or maximum aggregation.

  • dominant_coord — normal-mode dispersion coloured by the coordinate with the largest CNM amplitude.

  • dominant_group — normal-mode dispersion coloured by the group with the largest aggregate CNM amplitude. Use --group-by to select the grouping source.

  • coord — local-mode, force-constant, or normal/local dispersion coloured by coordinate.

  • group — local-mode, force-constant, or normal/local dispersion coloured by a group selected with --group-by.

  • char_coord — character evolution coloured by coordinate.

  • char_symkey — character evolution coloured by symmetry key.

  • bar_symkey — bar plot grouped by symmetry key.

  • bar_coord — bar plot coloured by coordinate.

For dispersion --quantity normal, the valid colour schemes are black, continuous, dominant_coord, and dominant_group. For local, force_constant, and normal_local, the valid colour schemes are black, coord, and group. Grouped dispersion schemes use --group-by coord|symkey|type|custom.

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

For --quantity normal, selected rows from normal_modes/frequencies and selected kpoints/labels. CNM data is read only for CNM-based colouring; --color-by black does not read

CNM/amplitudes. For continuous with explicit --coords and without --normalise-cnm, only those CNM coordinate

columns are read. For --quantity local, selected rows from local_modes/frequencies and coordinate metadata. For --quantity force_constant, selected rows from local_modes/effective_force_constants and coordinate metadata. For --quantity normal_local, selected rows from both normal_modes/frequencies and local_modes/frequencies.

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

With --quantity normal, requires --write-normal. CNM data is required only for CNM-based colouring schemes. With --quantity local or normal_local, requires the local-mode frequency datasets written by the main analysis. With --quantity force_constant, requires the local-mode force-constant datasets written by the main analysis.

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. This is an alias for dispersion --quantity force_constant.

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 dominant_coord --coords 1-3
 lmodea-k-plot dispersion --quantity normal --color-by black
 lmodea-k-plot dispersion --quantity local --color-by group --group-by type --coords 1-10
 lmodea-k-plot dispersion --quantity force_constant --color-by group --group-by symkey
 lmodea-k-plot dispersion --quantity normal_local --color-by coord
 lmodea-k-plot dispersion --color-by continuous --coords 4,5 --xmin 2 --xmax 20
 lmodea-k-plot dispersion --color-by dominant_group --group-by symkey
 lmodea-k-plot character_evolution --modes 1,2,3 --color-by char_symkey --sym-keys 2
 lmodea-k-plot bar --kpoint 2 --color-by bar_symkey --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.