.. include:: /_substitutions.rst .. _cli-plot: 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``. .. list-table:: :header-rows: 1 * - 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. .. list-table:: :header-rows: 1 * - 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.