"""
Phonon mode viewer: ``crystod-phonon --visualize``.
The phonon counterpart of the SALC viewer of ``crystod --visualize``. From
POSCAR + FORCE_SETS (or FORCE_CONSTANTS) it
1. runs phonopy along the k path (the seekpath path of the primitive cell, or
``--band``) with eigenvectors and writes phonopy's ``band.yaml`` under the
name ``band_vector.yaml``, the vertices named by their ISO-IR k-vector types
(``GM``, ``X``, ``M``, ``R``) as the irreps figure ticks them;
2. writes one standalone HTML page (``phonon_visualize.html``): the dispersion
along the path with a marker on every degenerate level of the labeled
special points, and a 3D scene with the atomic displacement pattern of the
selected mode, every mode of every special point listed with its ISO-IR
label (and, at Gamma, its Mulliken symbol and IR/Raman activity), arrows
and an optional animation of the vibration. With ``--all-irreps``
(``phonon_visualize_all.html``) the page also shows the midpoint of every
segment of the path (the symmetry lines DT, Z, SM, ... of
``crystod-phonon --irreps --all-irreps``), each with its line irreps and
its own display cell.
The bands, the path and the labeled points are those of the irreps figure
(:func:`crystod.phonon_irreps_plot.compute_dispersion`), the labels those of
``phonon_irreps.yaml`` (:func:`crystod.phonon_irreps.get_irrep_labels`), the
mode vectors the symmetry-adapted eigenvectors of ``crystod-phonon --vector``
(:func:`crystod.phonon_vector.build_symmetry_adapted_modes`: the partners of
a degenerate level transform with the irrep matrices).
Conventions: frequencies in THz, imaginary ones negative (phonopy); q in the
primitive reciprocal basis of phonopy's primitive cell. The displacement of
primitive atom ``a`` in the cell at lattice translation ``T`` (primitive
basis) is drawn as ``Re[u_a exp(i(2 pi q.T - phi))]`` with the atomic-gauge
vector ``u_a = e_a exp(2 pi i q.tau_a) / sqrt(m_a)`` (``e_a`` the
mass-weighted phonopy eigenvector, ``tau_a`` the fractional position of the
atom), the global phase of :func:`crystod.phonon_vector.get_supercell_displacement_field`
(maximal real part, phonopy's MODULATION choice) and normalized so that the
largest displacement in the display cell at ``phi = 0`` is 1 (the amplitude
slider gives it in Angstrom); ``phi`` is the animation phase.
The page layout (left control/mode sidebar + central viewport) is modeled
after the phonon website by Henrique Miranda
(https://henriquemiranda.github.io/phononwebsite/, BSD-3-Clause); the
rendering uses plotly; atom colors are VESTA's.
"""
from __future__ import annotations
import json
import re
import warnings
from argparse import (
ArgumentDefaultsHelpFormatter,
ArgumentParser,
RawDescriptionHelpFormatter,
RawTextHelpFormatter,
)
from dataclasses import dataclass, field
from fractions import Fraction
import numpy as np
from numpy.typing import NDArray
from .spglib_compat import ensure_spglib_compat
ensure_spglib_compat()
#: Default file names: the band structure keeps its fixed name, ``-o`` renames
#: the page only.
BAND_VECTOR_YAML = "band_vector.yaml"
DEFAULT_OUTPUT = "phonon_visualize.html"
#: The page of ``--all-irreps`` (the pair of ``phonon_irreps_all.yaml``).
DEFAULT_OUTPUT_ALL = "phonon_visualize_all.html"
#: Default largest displacement of a pattern on the page: this fraction of the
#: nearest-neighbor distance, rounded to 0.05 A (0.5 A for ScF3 and SrTiO3).
AMPLITUDE_FRACTION = 0.25
#: Length of an arrow head as a fraction of the arrow (plotly cone, ``raw`` size).
HEAD_FRACTION = 0.5
#: Band line and imaginary-level colors of the irreps figure.
CURVE = "#184f95"
IMAGINARY = "#e34948"
#: Initial camera of the 3D scene: off the body diagonal, so that the atoms of
#: a cubic cell do not hide each other, and closer than the SALC viewer's.
CAMERA_EYE = {"x": 1.55, "y": 1.0, "z": 0.8}
#: Arrow color of the displacement pattern: near-black, which no VESTA atom
#: color is close to (red arrows vanish on the red O atoms of oxides).
ARROW = "#222222"
#: Displacements below this fraction of the largest one get no arrow.
ARROW_CUTOFF = 0.02
#: A display cell with more atoms than this gets a NOTE (the page may be slow);
#: a segment midpoint of ``--all-irreps`` whose cell would be larger is skipped.
LARGE_CELL_ATOMS = 1000
#: Largest denominator of the q coordinates read as exact fractions (that of
#: :func:`crystod.operations.snap_qpoint`): the display cell and the fractions
#: of the page and the terminal.
Q_DENOMINATOR = 48
#: Decimals of the shipped data: positions (A), mode vectors, bands.
_POSITION_DECIMALS = 4
_VECTOR_DECIMALS = 7
_BAND_DECIMALS = 4
_DISTANCE_DECIMALS = 5
_GREEK = {"Gamma": "Γ", "Delta": "Δ", "Sigma": "Σ", "Lambda": "Λ"}
_GAMMA_ALIASES = {"G", "GM", "GAMMA", "Γ"}
class MyHelpFormatter(
RawTextHelpFormatter,
RawDescriptionHelpFormatter,
ArgumentDefaultsHelpFormatter,
):
pass
desc = """
Phonon mode viewer: one standalone HTML page with the dispersion along the k
path and the displacement pattern of every mode at its special points, each
labeled with its ISO-IR irrep (Mulliken symbol and IR/Raman activity at
Gamma); also writes phonopy's band.yaml with eigenvectors as band_vector.yaml.
POSCAR and FORCE_SETS (or FORCE_CONSTANTS with --readfc) must exist in the
directory where this code runs, as in --irreps mode.
# Command Examples:
crystod-phonon --visualize --dim "4 4 4" -c 221_PPOSCAR_ScF3
crystod-phonon --visualize --dim "4 4 4" -c 221_PPOSCAR_ScF3 --bond Sc F 2.3
crystod-phonon --visualize --dim "4 4 4" -c 221_PPOSCAR_ScF3 --qpoint R -o ScF3_R.html
crystod-phonon --visualize --dim "4 4 4" -c 227_PPOSCAR_Si --readfc --conventional
crystod-phonon --visualize --dim "4 4 4" -c 221_PPOSCAR_SrTiO3 --bond Ti O 2.1 --all-irreps
The page opens on the first q point and its first mode; the URL hash
#q=R&mode=4&view=a opens the q point R with band 4 selected, viewed down the
a axis (orthographic; view=b, view=c likewise). With --all-irreps the page
(phonon_visualize_all.html) also shows the midpoints of the path segments, as
crystod-phonon --irreps --all-irreps labels them: #q=DT opens the first
midpoint named DT, #q=DT(GM-X) the midpoint of GM-X, #q=7 the seventh q button.
"""
# --------------------------------------------------------------------------
# data
# --------------------------------------------------------------------------
[docs]
@dataclass
class ViewerMode:
"""One phonon mode (band) at a q point of the viewer.
Attributes:
band: 1-based band index (frequency order).
frequency: Frequency in THz (negative: imaginary).
irrep: Text of the degenerate set the band belongs to, as
``phonon_irreps.yaml`` labels it (``GM4-(3)``; ``X3-`` for a
one-dimensional irrep; ``GM1 + GM5(2)`` for a set holding several
irreps; ``?`` when unlabeled).
component: 1..dimension inside the degenerate set.
dimension: Number of bands of the set.
set_index: 0-based index of the set at this q point.
mulliken: Mulliken symbol of the set at Gamma (``T1u``), else None.
activity: Activity of the set at Gamma (``IR``, ``Raman``,
``IR+Raman``, ``silent``, ``acoustic``), else None.
u: Atomic-gauge complex displacement vectors, shape
``(n_primitive_atoms, 3)``, normalized so that the largest
displacement of the display cell at phase 0 is 1.
scale: The factor removed by that normalization (the largest real
displacement of the field of
:func:`crystod.phonon_vector.get_supercell_displacement_field`).
vector: The mass-weighted mode vector the pattern comes from (phonopy
convention, ``3 * n_atoms`` complex components).
"""
band: int
frequency: float
irrep: str
component: int
dimension: int
set_index: int
mulliken: str | None
activity: str | None
u: NDArray[np.complex128]
scale: float
vector: NDArray[np.complex128] = field(repr=False)
[docs]
@dataclass
class ViewerPoint:
"""One q point of the viewer: its display cell, atoms, bonds and modes.
Attributes:
name: ISO-IR name of the point (``GM``, ``X``; ``U|K`` for the two
sides of a break that carry the same levels; ``DT`` for a segment
midpoint, its ISO-IR k-vector type).
q: Fractional coordinates, primitive reciprocal basis.
x: Position on the dispersion (path distance; the middle of its leg
for a segment midpoint), or None when the point is not on the
path (``--qpoint`` elsewhere).
cell_matrix: Rows are the display-cell vectors in the primitive basis
(commensurate with q: each axis times the denominator of q,
:func:`_display_cell_matrix`).
cell_description: ``primitive, 2 x 2 x 2 cells`` (as the SALC viewer).
lattice: The display-cell lattice vectors as rows (Angstrom).
symbols, positions, atom_index, translations: The drawn atoms
(boundary completion and bonded images included): element,
Cartesian position (A), primitive atom index ``a`` and
primitive-basis lattice translation ``T`` (ints).
bonds: ``[(name, [(slot_i, slot_j), ...]), ...]`` per ``--bond``.
polyhedra: ``[(element, center_slot, [(slot_i, slot_j, slot_k), ...]),
...]``: the triangles of the convex hull of each coordination
polyhedron at equilibrium (kept while the atoms move).
modes: The :class:`ViewerMode` list, in band order.
notes: Notes of this point (fallbacks).
segment: The segment of the path whose midpoint this point is
(``GM-X``; ``--all-irreps``), None at a special point.
"""
name: str
q: list
x: float | None
cell_matrix: NDArray[np.int_]
cell_description: str
lattice: NDArray[np.float64]
symbols: list
positions: NDArray[np.float64]
atom_index: list
translations: NDArray[np.int_]
bonds: list
polyhedra: list
modes: list
notes: list = field(default_factory=list)
segment: str | None = None
@property
def is_gamma(self) -> bool:
return bool(np.allclose(self.q, np.rint(np.asarray(self.q, dtype=float)), atol=1e-8))
@property
def is_midpoint(self) -> bool:
"""Whether the point is a segment midpoint of ``--all-irreps``."""
return self.segment is not None
[docs]
@dataclass
class PhononViewer:
"""Everything the phonon mode viewer page shows.
Attributes:
formula: Reduced formula (``ScF3``).
space_group: Hermann-Mauguin symbol; ``number`` its number.
supercell: The force-calculation supercell (``4 x 4 x 4``).
force_data: ``FORCE_SETS`` or ``FORCE_CONSTANTS`` (or None).
nac: Whether the NAC correction is applied.
path_source: ``seekpath`` or ``--band``.
dispersion: The :class:`crystod.phonon_irreps_plot.Dispersion` of the path.
points: The :class:`ViewerPoint` list, in the order of the selector.
threshold: Frequency (THz) below which a level counts as imaginary.
bonds: The ``(el1, el2, max_length)`` bond specifications.
primitive_lattice: Rows, Angstrom; ``conventional_lattice`` the
conventional cell with ``--conventional`` (else None).
amplitude: Default largest displacement on the page (Angstrom,
:func:`default_amplitude`).
notes: Notes of the run (path, NAC, segment midpoints not drawn).
all_irreps: Whether the segment midpoints are shown too
(``--all-irreps``; they follow the special points in ``points``).
"""
formula: str
space_group: str
number: int
supercell: str
force_data: str | None
nac: bool
path_source: str
dispersion: object
points: list
threshold: float
bonds: list
primitive_lattice: NDArray[np.float64]
conventional_lattice: NDArray[np.float64] | None
amplitude: float = 0.5
notes: list = field(default_factory=list)
all_irreps: bool = False
def default_amplitude(phonon) -> float:
"""The page's default largest displacement: :data:`AMPLITUDE_FRACTION`
of the nearest-neighbor distance of the primitive cell, rounded to
0.05 A and kept within 0.2 to 1.0 A (0.5 A for ScF3 and SrTiO3, whose
shortest bonds are about 2 A)."""
primitive = phonon.primitive
lattice = np.array(primitive.cell, dtype=float)
cart = np.array(primitive.scaled_positions, dtype=float) @ lattice
offsets = np.array([[i, j, k] for i in (-1, 0, 1) for j in (-1, 0, 1) for k in (-1, 0, 1)],
dtype=float) @ lattice
images = (cart[None, :, None, :] + offsets[None, None, :, :]) - cart[:, None, None, :]
distances = np.linalg.norm(images, axis=-1).ravel()
distances = distances[distances > 1e-3]
nearest = float(distances.min()) if distances.size else 2.0
return float(min(1.0, max(0.2, round(AMPLITUDE_FRACTION * nearest / 0.05) * 0.05)))
# --------------------------------------------------------------------------
# text helpers
# --------------------------------------------------------------------------
def _fraction(value: float) -> str:
"""``1/2``, ``-1/3``, ``3/16``, ``0`` (denominators up to
:data:`Q_DENOMINATOR`), else ``%g``."""
frac = Fraction(float(value)).limit_denominator(Q_DENOMINATOR)
if abs(float(frac) - float(value)) > 1e-6:
return f"{float(value):g}"
if frac.denominator == 1:
return str(frac.numerator)
return f"{frac.numerator}/{frac.denominator}"
def format_q_fraction(q) -> str:
"""``(0, 1/2, 0)``: q as fractions, the form of the viewer's q selector."""
return "(" + ", ".join(_fraction(v) for v in np.asarray(q, dtype=float) + 0.0) + ")"
def _tick_html(text: str) -> str:
"""The HTML of a tick label of the irreps figure (mathtext ``$\\Gamma$``,
``X$_{1}$``) for the plotly chart (Greek capitals, ``<sub>``)."""
text = re.sub(r"\$\\(Gamma|Delta|Sigma|Lambda)\$", lambda m: _GREEK[m.group(1)], text)
text = re.sub(r"\$_\{(.*?)\}\$", r"<sub>\1</sub>", text)
return text.replace("$", "")
def _supercell_text(phonon) -> str:
"""``4 x 4 x 4`` for a diagonal supercell matrix, else its rows."""
matrix = np.rint(np.asarray(phonon.supercell_matrix)).astype(int)
if np.count_nonzero(matrix - np.diag(np.diag(matrix))) == 0:
return " x ".join(str(int(v)) for v in np.diag(matrix))
return " / ".join(" ".join(str(int(v)) for v in row) for row in matrix)
def _clean(value: float, decimals: int) -> float:
"""``round(value, decimals)`` without a negative zero."""
return round(float(value), decimals) + 0.0
# --------------------------------------------------------------------------
# band path and band_vector.yaml
# --------------------------------------------------------------------------
def _band_path(phonon, band, band_labels, npoints, tolerance):
"""``(qpoints, connections, labels, segments, names, notes)`` of the path
of :func:`crystod.phonon_irreps_plot.compute_dispersion`: the same
vertices (``_path``) and the same q points per leg, the vertex names
flattened in phonopy's ``labels`` order (the start of every continuous
part, then every end point)."""
from phonopy.phonon.band_structure import get_band_qpoints_and_path_connections
from .phonon_irreps_plot import _path
segments, names, notes = _path(phonon, band, band_labels, tolerance)
band_paths = [np.array(segment, dtype=float) for segment in segments]
qpoints, connections = get_band_qpoints_and_path_connections(
band_paths, npoints=npoints or 51
)
labels = [str(name) for part in names for name in part]
return qpoints, connections, labels, segments, names, notes
[docs]
def write_band_vector_yaml(
phonon,
*,
band: str | None = None,
band_labels: str | None = None,
npoints: int | None = None,
tolerance: float = 1e-5,
filename: str = BAND_VECTOR_YAML,
) -> int:
"""Write phonopy's ``band.yaml`` with eigenvectors along the viewer's path.
The path and the q points are those of the irreps figure and the viewer
(:func:`crystod.phonon_irreps_plot.compute_dispersion`); the vertices are
labeled with their ISO-IR names (``GM``, ``X``) in phonopy's ``labels``
list. The file is phonopy's own format (``nqpoint``, ``npath``,
``segment_nqpoint``, ``labels``, ``reciprocal_lattice``, the primitive
cell, then ``phonon:`` with one entry per q point: ``q-position``,
``distance`` and ``band:``, each band with its ``frequency`` (THz) and
``eigenvector``: one list per atom of three ``[re, im]`` pairs, the
mass-weighted eigenvector in phonopy's atom-position phase convention),
so phonopy's and other band.yaml readers read it.
Args:
phonon: ``phonopy.Phonopy`` object with force constants.
band, band_labels, npoints, tolerance: The path, as for
:func:`crystod.phonon_irreps_plot.compute_dispersion`.
filename: Output path.
Returns:
The number of q points written (``nqpoint``).
"""
qpoints, connections, labels, _, _, _ = _band_path(
phonon, band, band_labels, npoints, tolerance
)
phonon.run_band_structure(
qpoints, path_connections=connections, labels=labels,
with_eigenvectors=True, is_band_connection=False,
)
phonon.write_yaml_band_structure(filename=filename)
return int(sum(len(q) for q in qpoints))
# --------------------------------------------------------------------------
# modes, labels and the display cell of one q point
# --------------------------------------------------------------------------
def _plain_modes(phonon, qpoint):
"""Plain phonopy eigenvectors at q, as ``crystod-phonon --vector`` falls
back on them: ``[(frequency_THz, vector), ...]``."""
from .phonon_vector import FREQUENCY_CONVERSION_THZ
dynamical_matrix = phonon.dynamical_matrix
dynamical_matrix.run(qpoint)
eigenvalues, vectors = np.linalg.eigh(dynamical_matrix.dynamical_matrix)
eigenvalues = eigenvalues.real
frequencies = np.sign(eigenvalues) * np.sqrt(np.abs(eigenvalues)) * FREQUENCY_CONVERSION_THZ
return [(float(f), vectors[:, i]) for i, f in enumerate(frequencies)]
def _degenerate_sets(frequencies, tolerance):
sets: list[list[int]] = []
for index, frequency in enumerate(frequencies):
if sets and abs(frequency - frequencies[sets[-1][0]]) < tolerance:
sets[-1].append(index)
else:
sets.append([index])
return sets
def _set_labels(phonon, qpoint, labelling, degeneracy_tolerance):
"""``(texts, band_sets, mulliken_texts, activity_texts, note)`` at q:
one entry per degenerate set, labeled at the tabulated arm of the star of
q (as ``crystod-phonon --vector`` and the irreps figure do); the Gamma
entries are None elsewhere."""
from .phonon_irreps import (
_gamma_activities,
_set_mulliken,
find_star_representative,
get_irrep_labels,
)
from .phonon_irreps_plot import _set_text
irt_table, prim_mat, q_names, q_list, rotations, mulliken = labelling
label_q = list(qpoint)
representative = find_star_representative(qpoint, rotations, q_names, q_list)
if representative is not None:
label_q = list(representative[1])
try:
with warnings.catch_warnings():
warnings.filterwarnings("ignore", message="No irreps at")
labels, band_indices, frequencies = get_irrep_labels(
q=label_q, phonon=phonon, irt_table=irt_table, prim_mat=prim_mat,
degeneracy_tolerance=degeneracy_tolerance,
)
except Exception as exc:
phonon.run_qpoints([qpoint])
from .runtime_compat import get_qpoints_result
frequencies = get_qpoints_result(phonon).frequencies[0]
sets = _degenerate_sets(list(frequencies), degeneracy_tolerance)
return (["?"] * len(sets), sets, [None] * len(sets), [None] * len(sets),
f"no ISO-IR labels ({exc}); the sets are shown as '?'")
band_sets = [[int(i) for i in indices] for indices in band_indices]
texts = [_set_text(set_labels) for set_labels in labels]
activities = _gamma_activities(phonon, label_q, labels)
if activities is None:
return texts, band_sets, [None] * len(texts), [None] * len(texts), None
mulliken_texts = [_set_mulliken(set_labels, mulliken) for set_labels in labels]
activity_texts = ["+".join(record.activity) for record in activities]
return texts, band_sets, mulliken_texts, activity_texts, None
def _hull_faces(points: NDArray[np.float64]) -> list[tuple[int, int, int]]:
"""Triangles of the convex hull of a coordination polyhedron (indices into
``points``); a flat polygon (square-planar coordination) is fanned from
its first vertex in angular order."""
from scipy.spatial import ConvexHull, QhullError
try:
return [tuple(int(i) for i in simplex) for simplex in ConvexHull(points).simplices]
except (QhullError, ValueError):
center = points.mean(axis=0)
_, _, vt = np.linalg.svd(points - center)
local = (points - center) @ vt[:2].T
order = list(np.argsort(np.arctan2(local[:, 1], local[:, 0])))
return [(int(order[0]), int(order[i]), int(order[i + 1])) for i in range(1, len(order) - 1)]
def _display_atoms(phonon, cell_matrix, bonds):
"""The drawn atoms of one display cell and their bonds and polyhedra.
The atoms of the SALC viewer (``_display_cell_entries``: boundary
completion), plus, with ``bonds``, the periodic images that complete the
coordination polyhedra (``_bond_pairs``, as in VESTA), each with its own
primitive atom index and lattice translation.
Returns:
``(symbols, positions, atom_index, translations, bond_list,
polyhedra)``; see :class:`ViewerPoint`.
"""
from .visualize_basis import _bond_pairs, _display_cell_entries
primitive = phonon.primitive
lattice = np.array(primitive.cell, dtype=float)
frac = np.array(primitive.scaled_positions, dtype=float)
prim_symbols = list(primitive.symbols)
cell_matrix = np.asarray(cell_matrix, dtype=int)
display_lattice = np.array(cell_matrix, dtype=float) @ lattice
entries = _display_cell_entries(frac, cell_matrix)
atom_index = [int(a) for a, _ in entries]
translations = [np.rint(t).astype(int) for _, t in entries]
positions = [(frac[a] + t) @ lattice for a, t in entries]
symbols = [prim_symbols[a] for a in atom_index]
bond_list, polyhedra = [], []
if bonds:
base_positions = np.array(positions)
base_symbols = list(symbols)
# an atom is (a, T): a bonded image already drawn (a boundary
# duplicate, or the image of another bond) is not drawn twice
slots = {(a, tuple(int(v) for v in t)): slot
for slot, (a, t) in enumerate(zip(atom_index, translations))}
def slot_of(b, offset, position):
if not any(offset):
return b
translation = translations[b] + np.asarray(offset, dtype=int) @ cell_matrix
key = (atom_index[b], tuple(int(v) for v in translation))
if key not in slots:
slots[key] = len(positions)
positions.append(np.array(position, dtype=float))
atom_index.append(atom_index[b])
translations.append(translation)
symbols.append(symbols[b])
return slots[key]
for el1, el2, max_length in bonds:
pairs, centers = [], {}
for a, b, offset, position_b in _bond_pairs(
base_positions, base_symbols, display_lattice, el1, el2, max_length
):
slot = slot_of(b, offset, position_b)
pairs.append((a, slot))
centers.setdefault(a, []).append(slot)
if pairs:
bond_list.append((f"{el1}-{el2} bonds", pairs))
for center, vertices in centers.items():
if len(vertices) >= 4: # a convex hull needs at least four ligands
faces = _hull_faces(np.array([positions[v] for v in vertices]))
if faces:
polyhedra.append(
(el1, center, [tuple(vertices[i] for i in face) for face in faces])
)
return (
symbols, np.array(positions, dtype=float), atom_index,
np.array(translations, dtype=int).reshape(-1, 3), bond_list, polyhedra,
)
def _atomic_gauge_vectors(phonon, qpoint, cell_matrix, vector):
"""``(u, scale)``: the atomic-gauge displacement vectors of the primitive
atoms (``(n_atoms, 3)`` complex) carrying the global phase of
:func:`crystod.phonon_vector.get_supercell_displacement_field` on the
display cell, normalized by ``scale``, the largest real displacement of
that field. ``u`` is read off the field itself, ``u_a = u(l, a)
exp(-2 pi i q.T_l)``, and checked to be the same in every cell."""
from .phonon_vector import get_supercell_displacement_field
supercell, displacements = get_supercell_displacement_field(
phonon, qpoint, cell_matrix, vector
)
matrix = np.asarray(cell_matrix, dtype=int)
frac = np.array(phonon.primitive.scaled_positions, dtype=float)
s2uu = np.array([supercell.u2u_map[x] for x in supercell.s2u_map], dtype=int)
x_primitive = np.array(supercell.scaled_positions, dtype=float) @ matrix
translations = np.rint(x_primitive - frac[s2uu])
back = np.exp(-2j * np.pi * translations @ np.asarray(qpoint, dtype=float))
per_cell = displacements * back[:, None]
u = np.zeros((len(frac), 3), dtype=complex)
for atom in range(len(frac)):
u[atom] = per_cell[np.flatnonzero(s2uu == atom)[0]]
spread = float(np.max(np.abs(per_cell - u[s2uu]))) if len(s2uu) else 0.0
size = float(np.max(np.abs(per_cell))) or 1.0
if spread > 1e-8 * size:
raise RuntimeError(
f"the displacement field is not a Bloch wave on the display cell ({spread:.1e})"
)
scale = float(np.max(np.linalg.norm(displacements.real, axis=1)))
if scale < 1e-12:
# the real part of the pattern vanishes (cannot happen with the
# maximal-real-part phase unless the vector is zero)
scale = float(np.max(np.linalg.norm(np.abs(displacements), axis=1))) or 1.0
return u / scale, scale
def _display_cell_matrix(qpoint, base_matrix) -> NDArray[np.int_]:
"""The display cell of q: the smallest diagonal multiple of ``base_matrix``
commensurate with q, from the exact fractions of q.
:func:`crystod.phonon_vector.get_commensurate_supercell_matrix` reads each
component as a fraction with a denominator up to 12, which gives a cell
that is not commensurate with a segment midpoint such as (3/16, 3/16,
3/8) (the K-GM midpoint of an fcc path); here the components are the
fractions of :func:`crystod.operations.snap_qpoint` (denominators up to
:data:`Q_DENOMINATOR`), multiplied into the base-cell reciprocal basis
exactly. A q that is no such fraction falls back on
``get_commensurate_supercell_matrix``.
Args:
qpoint: Fractional coordinates of q in the primitive reciprocal basis.
base_matrix: Rows are the base-cell vectors in the primitive basis.
Returns:
Integer matrix ``S`` (rows: the display-cell vectors in the primitive
basis) with ``q . S_row`` an integer for every row.
"""
from .phonon_vector import get_commensurate_supercell_matrix
fractions = []
for value in np.asarray(qpoint, dtype=float):
frac = Fraction(float(value)).limit_denominator(Q_DENOMINATOR)
if abs(float(frac) - float(value)) > 1e-9:
return np.array(get_commensurate_supercell_matrix(qpoint, base_matrix), dtype=int)
fractions.append(frac)
base = np.rint(np.asarray(base_matrix, dtype=float)).astype(int)
sizes = [
sum((int(base[row, col]) * fractions[col] for col in range(3)), Fraction(0)).denominator
for row in range(3)
]
return np.diag(sizes) @ base
def _cell_atom_count(phonon, cell_matrix) -> int:
"""Atoms of the display cell (primitive cells times primitive atoms),
without the boundary completion of the drawing."""
cells = int(round(abs(np.linalg.det(np.asarray(cell_matrix, dtype=float)))))
return cells * len(phonon.primitive)
def _viewer_point(phonon, name, qpoint, x, labelling, degeneracy_tolerance,
base_matrix, conventional_centring, bonds, segment=None) -> ViewerPoint:
from .phonon_vector import build_symmetry_adapted_modes
notes: list[str] = []
qpoint = [float(v) for v in qpoint]
try:
modes = build_symmetry_adapted_modes(phonon, qpoint)
except Exception as exc:
notes.append(
f"symmetry-adapted mode construction failed ({exc}); plain phonopy "
"eigenvectors are drawn, which may look tilted within degenerate subspaces"
)
modes = _plain_modes(phonon, qpoint)
texts, band_sets, mulliken, activity, note = _set_labels(
phonon, qpoint, labelling, degeneracy_tolerance
)
if note:
notes.append(note)
cell_matrix = _display_cell_matrix(qpoint, base_matrix)
if conventional_centring is not None:
multiples = np.rint(
np.diag(cell_matrix @ np.linalg.inv(np.array(base_matrix, dtype=float)))
).astype(int)
description = (
f"conventional ({conventional_centring} centring), "
f"{multiples[0]} x {multiples[1]} x {multiples[2]} cells"
)
else:
n1, n2, n3 = np.diag(cell_matrix)
description = f"primitive, {n1} x {n2} x {n3} cells"
lattice = np.array(cell_matrix, dtype=float) @ np.array(phonon.primitive.cell, dtype=float)
symbols, positions, atom_index, translations, bond_list, polyhedra = _display_atoms(
phonon, cell_matrix, bonds
)
if len(symbols) > LARGE_CELL_ATOMS:
notes.append(
f"the display cell of q = {format_q_fraction(qpoint)} holds {len(symbols)} atoms; "
"the page may be slow"
)
set_of_band = {}
for set_index, indices in enumerate(band_sets):
for component, band_index in enumerate(indices):
set_of_band[band_index] = (set_index, component + 1, len(indices))
viewer_modes = []
for band_index, (frequency, vector) in enumerate(modes):
set_index, component, dimension = set_of_band.get(band_index, (len(band_sets), 1, 1))
u, scale = _atomic_gauge_vectors(phonon, qpoint, cell_matrix, vector)
has_set = set_index < len(band_sets)
viewer_modes.append(
ViewerMode(
band=band_index + 1,
frequency=float(frequency),
irrep=texts[set_index] if has_set else "?",
component=component,
dimension=dimension,
set_index=set_index,
mulliken=mulliken[set_index] if has_set else None,
activity=activity[set_index] if has_set else None,
u=u,
scale=scale,
vector=np.asarray(vector, dtype=complex),
)
)
return ViewerPoint(
name=name, q=qpoint, x=x, cell_matrix=cell_matrix, cell_description=description,
lattice=lattice, symbols=symbols, positions=positions, atom_index=atom_index,
translations=translations, bonds=bond_list, polyhedra=polyhedra,
modes=viewer_modes, notes=notes, segment=segment,
)
def _same_q(q1, q2) -> bool:
diff = np.asarray(q1, dtype=float) - np.asarray(q2, dtype=float)
return bool(np.allclose(diff, np.rint(diff), atol=1e-6))
def _selected_points(phonon, dispersion, segments, names, qpoint, dataset):
"""``[(name, q, x), ...]``: the labeled special points of the path in the
order of their first appearance on it, or the one ``--qpoint`` point."""
from .phonon_irreps import _special_points_in_label_frame
from .phonon_vector import resolve_qpoint
from .runtime_compat import get_symmetry_dataset
vertices = [(n, k) for part, ns in zip(segments, names) for n, k in zip(ns, part)]
if qpoint is None:
def first(point):
for index, (_, k) in enumerate(vertices):
if _same_q(k, point.q):
return index
return len(vertices)
ordered = sorted(dispersion.points, key=first)
return [(point.name, list(point.q), point.x) for point in ordered]
from phonopy.structure.cells import get_primitive_matrix_by_centring
from .phonon_vector import IrrepTable
try:
irt_table = IrrepTable(dataset["number"], spinor=False)
prim_mat = get_primitive_matrix_by_centring(dataset["international"][0])
q_names, q_list = _special_points_in_label_frame(phonon, irt_table, prim_mat)
except Exception:
q_names, q_list = [], []
rotations = get_symmetry_dataset(phonon.primitive_symmetry)["rotations"]
primitive, unitcell = phonon.primitive, phonon.unitcell
isoir_context = (
dataset["number"],
(primitive.cell, primitive.scaled_positions, primitive.numbers),
phonon.primitive_symmetry.tolerance,
(unitcell.cell, unitcell.scaled_positions, unitcell.numbers),
)
if len(qpoint) == 1:
requested = qpoint[0].strip().upper()
requested = "GM" if requested in _GAMMA_ALIASES else requested
# a label names the vertex of the path called so (its marker and its
# modes then agree; K of a merged U|K is the K vertex of the path, at
# the marker of U|K), else the tabulated point
for point in dispersion.points:
parts = [part.upper() for part in point.name.split("|")]
if parts[0] == requested:
return [(point.name, list(point.q), point.x)]
if requested in parts:
for name, k in vertices:
if str(name).upper() == requested:
return [(str(name), [float(v) for v in k], point.x)]
try:
name, q = resolve_qpoint(
qpoint, q_names, q_list, rotations=rotations, isoir_context=isoir_context
)
except ValueError as exc:
raise SystemExit(f"ERROR: {exc}") from None
for point in dispersion.points:
if _same_q(point.q, q):
return [(point.name, list(q), point.x)]
return [(name, list(q), None)]
def _segment_midpoints(phonon, dispersion, segments, names, band, taken, base_matrix):
"""``(midpoints, notes)``: the segment midpoints of ``--all-irreps``.
``midpoints`` is ``[(label, q, x, segment), ...]`` in path order: for the
seekpath path the midpoints of ``crystod-phonon --irreps --all-irreps``
(:func:`crystod.phonon_irreps._seekpath_path_midpoints`, the same labels
and segment names), for a ``--band`` path those of its own legs
(:func:`crystod.phonon_irreps._label_segment_midpoints`); ``x`` is the
middle of the leg on the dispersion. A midpoint equal (modulo a
reciprocal lattice vector) to a q of ``taken`` (the special points, then
the midpoints already met) is left out; one whose display cell would
hold more than :data:`LARGE_CELL_ATOMS` atoms is left out with a note.
"""
from .phonon_irreps import _label_segment_midpoints, _seekpath_path_midpoints
from .operations import snap_qpoint
legs = [
(str(ns[i]) or "?", str(ns[i + 1]) or "?", part[i], part[i + 1])
for part, ns in zip(segments, names) for i in range(len(ns) - 1)
]
notes: list[str] = []
try:
if band:
found = _label_segment_midpoints(phonon, legs)
else:
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
_, found = _seekpath_path_midpoints(phonon)
if not found and any("does not match the phonopy primitive" in str(w.message)
for w in caught):
notes.append(
"the segment midpoints are not drawn: the seekpath primitive cell differs "
"from the primitive cell of phonopy (as in --irreps --all-irreps; give "
"--band for a path in the primitive cell of the input)"
)
except Exception as exc:
found = []
notes.append(f"the segment midpoints are not drawn ({type(exc).__name__}: {exc})")
leg_midpoints = [
snap_qpoint((np.asarray(k1, dtype=float) + np.asarray(k2, dtype=float)) / 2.0)
for _, _, k1, k2 in legs
]
taken = [list(q) for q in taken]
midpoints = []
for label, segment, q in found:
q = [float(v) for v in q]
if any(_same_q(q, other) for other in taken):
continue
x = None
for index, k in enumerate(leg_midpoints):
if index < len(dispersion.distances) and np.allclose(k, q, atol=1e-8):
leg = np.asarray(dispersion.distances[index], dtype=float)
x = float(leg[0] + leg[-1]) / 2.0
break
n_atoms = _cell_atom_count(phonon, _display_cell_matrix(q, base_matrix))
taken.append(q) # one NOTE for a skipped point, however often the path meets it
if n_atoms > LARGE_CELL_ATOMS:
coordinates = " ".join(_fraction(v) for v in np.asarray(q, dtype=float) + 0.0)
notes.append(
f"the midpoint {label} {format_q_fraction(q)} of {segment} is not drawn: its "
f"display cell would hold {n_atoms} atoms (give --qpoint {coordinates} to "
"draw it)"
)
continue
midpoints.append((label, q, x, segment))
return midpoints, notes
[docs]
def phonon_viewer_data(
phonon,
*,
irt_table=None,
prim_mat=None,
degeneracy_tolerance: float = 1e-3,
band: str | None = None,
band_labels: str | None = None,
npoints: int | None = None,
qpoint: list[str] | None = None,
conventional: bool = False,
bonds: list[tuple[str, str, float]] | None = None,
threshold: float = -0.1,
force_data: str | None = None,
tolerance: float = 1e-5,
all_irreps: bool = False,
) -> PhononViewer:
"""Compute everything the phonon mode viewer shows.
Args:
phonon: ``phonopy.Phonopy`` object with force constants, built with
``primitive_matrix="auto"`` (as ``crystod-phonon --irreps``).
irt_table, prim_mat: ISO-IR table of the space group and centring
matrix (default: from the symmetry of ``phonon``).
degeneracy_tolerance: THz within which bands form one set.
band, band_labels, npoints, tolerance: The path (``--band``,
``--band-labels``, ``--npoints``; default the seekpath path).
qpoint: ``--qpoint`` tokens (one label or three coordinates) to show
that point only; default every labeled special point of the path.
conventional: Display the conventional cell (times the multiples
commensurate with q) instead of the primitive cell.
bonds: ``[(el1, el2, max_length_A), ...]``: bonds and the VESTA-style
coordination polyhedra around ``el1``.
threshold: Frequency (THz) below which a level is drawn as imaginary.
force_data: Name of the force data shown on the page.
all_irreps: Also show the midpoint of every segment of the path, as
``crystod-phonon --irreps --all-irreps`` labels it (the symmetry
lines DT, Z, SM, ...; ``--band``: the midpoints of its legs),
after the special points; the points get ``segment`` set. A
midpoint equal to a special point or to an earlier midpoint is
left out, and so is one whose display cell would hold more than
:data:`LARGE_CELL_ATOMS` atoms (with a note; ``qpoint`` draws it).
Returns:
The :class:`PhononViewer`; :func:`write_phonon_viewer_html` writes it.
Raises:
ValueError: ``all_irreps`` together with ``qpoint``, or an unknown
``qpoint`` label.
"""
if all_irreps and qpoint is not None:
raise ValueError("all_irreps is not used with qpoint (qpoint shows one point).")
from phonopy.structure.cells import get_primitive_matrix_by_centring
from .phonon_irreps import _gamma_mulliken, get_irt_special_points
from .phonon_irreps_plot import compute_dispersion
from .phonon_vector import IrrepTable, get_conventional_matrix, reduced_formula
from .runtime_compat import get_symmetry_dataset
dataset = get_symmetry_dataset(phonon.symmetry)
if irt_table is None:
irt_table = IrrepTable(dataset["number"], spinor=False)
if prim_mat is None:
prim_mat = get_primitive_matrix_by_centring(dataset["international"][0])
dispersion = compute_dispersion(
phonon, irt_table, prim_mat, degeneracy_tolerance=degeneracy_tolerance,
band=band, band_labels=band_labels, npoints=npoints, tolerance=tolerance,
)
nac = getattr(phonon, "nac_params", None) is not None
notes = list(dispersion.notes)
if nac:
notes.append(
"at GM the labels and patterns are those of the TO modes (phonopy applies no q "
"direction at GM itself); the LO branches end there without labels"
)
_, _, _, segments, names, _ = _band_path(phonon, band, band_labels, npoints, tolerance)
selected = _selected_points(phonon, dispersion, segments, names, qpoint, dataset)
lattice = np.array(phonon.primitive.cell, dtype=float)
centring = None
base_matrix = np.eye(3, dtype=int)
conventional_lattice = None
if conventional:
centring = dataset["international"][0]
base_matrix = get_conventional_matrix(centring)
conventional_lattice = np.array(base_matrix, dtype=float) @ lattice
entries = [(name, q, x, None) for name, q, x in selected]
if all_irreps:
midpoints, midpoint_notes = _segment_midpoints(
phonon, dispersion, segments, names, band, [q for _, q, _ in selected], base_matrix
)
entries += midpoints
notes += midpoint_notes
q_names, q_list = get_irt_special_points(irt_table, prim_mat)
rotations = get_symmetry_dataset(phonon.primitive_symmetry)["rotations"]
has_gamma = any(np.allclose(q, np.rint(q), atol=1e-8) for _, q, _ in selected)
mulliken = _gamma_mulliken(phonon) if has_gamma else {}
labelling = (irt_table, prim_mat, q_names, q_list, rotations, mulliken)
points = [
_viewer_point(phonon, name, q, x, labelling, degeneracy_tolerance,
base_matrix, centring, bonds or [], segment=segment)
for name, q, x, segment in entries
]
return PhononViewer(
formula=reduced_formula(list(phonon.primitive.symbols)),
space_group=str(dataset["international"]),
number=int(dataset["number"]),
supercell=_supercell_text(phonon),
force_data=force_data,
nac=nac,
path_source="--band" if band else "seekpath",
dispersion=dispersion,
points=points,
threshold=float(threshold),
bonds=list(bonds or []),
primitive_lattice=lattice,
conventional_lattice=conventional_lattice,
amplitude=round(default_amplitude(phonon), 2),
notes=notes,
all_irreps=bool(all_irreps),
)
# --------------------------------------------------------------------------
# the page
# --------------------------------------------------------------------------
def _round_list(values, decimals):
return [_clean(v, decimals) for v in np.asarray(values, dtype=float).ravel()]
def _polyhedra_payload(polyhedra) -> list[dict]:
"""The polyhedra of one q point, one mesh per element: ``{element,
faces: [[i, j, k], ...]}`` with the drawn-atom slots of the triangles."""
merged: dict[str, list] = {}
for element, _, faces in polyhedra:
merged.setdefault(element, []).extend([[int(v) for v in face] for face in faces])
return [{"element": element, "faces": faces} for element, faces in merged.items()]
def _point_payload(point: ViewerPoint, label: str | None = None) -> dict:
"""The data of one q point as shipped to the page: the page rebuilds the
displacement of drawn atom ``j`` as ``Re[u_{a_j} exp(2 pi i q.T_j)]``.
A segment midpoint carries its ``segment`` and, when another q point of
the page has the same name, the button ``label`` ``DT (GM-X)``."""
from .visualize_basis import _lattice_edge_traces
modes = []
for mode in point.modes:
entry = {
"band": mode.band,
"freq": _clean(mode.frequency, _BAND_DECIMALS),
"irrep": mode.irrep,
"comp": mode.component,
"dim": mode.dimension,
"set": mode.set_index,
"u": [
[[_clean(c.real, _VECTOR_DECIMALS), _clean(c.imag, _VECTOR_DECIMALS)] for c in atom]
for atom in mode.u
],
}
if mode.mulliken:
entry["mulliken"] = mode.mulliken
if mode.activity:
entry["activity"] = mode.activity
modes.append(entry)
edges = _lattice_edge_traces(point.lattice, (1, 1, 1))
for axis in "xyz":
edges[axis] = [None if v is None else _clean(v, _POSITION_DECIMALS) for v in edges[axis]]
extra = {}
if point.segment is not None:
extra["segment"] = point.segment
if label is not None:
extra["label"] = label
return {
"name": point.name,
**extra,
"q": [float(v) + 0.0 for v in point.q],
"qText": format_q_fraction(point.q),
"x": None if point.x is None else _clean(point.x, _DISTANCE_DECIMALS),
"gamma": point.is_gamma,
"cell": point.cell_description,
"lattice": [_round_list(row, _POSITION_DECIMALS) for row in point.lattice],
"edges": edges,
"atoms": {
"s": list(point.symbols),
"p": [_round_list(p, _POSITION_DECIMALS) for p in point.positions],
"a": [int(a) for a in point.atom_index],
"T": [[int(t) for t in row] for row in point.translations],
},
"bonds": [{"name": name, "pairs": [[int(i), int(j)] for i, j in pairs]}
for name, pairs in point.bonds],
"polyhedra": _polyhedra_payload(point.polyhedra),
"modes": modes,
"notes": list(point.notes),
}
def _payload(data: PhononViewer) -> dict:
"""Everything the page script reads (``var DATA``)."""
from .phonon_vector import VESTA_ELEMENTS, DEFAULT_ELEMENT
from .visualize_basis import _load_atom_colors
dispersion = data.dispersion
colors = _load_atom_colors()
elements = sorted({s for point in data.points for s in point.symbols})
return {
"threshold": data.threshold,
"amplitude": data.amplitude,
"arrowCutoff": ARROW_CUTOFF,
"colors": {s: colors.get(s, "#cccccc") for s in elements},
"radii": {s: VESTA_ELEMENTS.get(s, DEFAULT_ELEMENT)[0] for s in elements},
"band": {
"distances": [_round_list(d, _DISTANCE_DECIMALS) for d in dispersion.distances],
"frequencies": [
[_round_list(row, _BAND_DECIMALS) for row in np.asarray(f, dtype=float)]
for f in dispersion.frequencies
],
"ticks": [_clean(t, _DISTANCE_DECIMALS) for t in dispersion.ticks],
"tickText": [_tick_html(t) for t in dispersion.tick_labels],
},
"points": [
_point_payload(point, label)
for point, label in zip(data.points, _button_labels(data.points))
],
}
def _button_labels(points) -> list:
"""The q-button text of each point that needs more than its name: a
segment midpoint whose name another point of the page carries too (two
arms of one line type) is ``DT (GM-X)``; None for every other point."""
counts: dict[str, int] = {}
for point in points:
counts[point.name] = counts.get(point.name, 0) + 1
return [
f"{point.name} ({point.segment})"
if point.segment is not None and counts[point.name] > 1 else None
for point in points
]
def _info_rows(data: PhononViewer) -> str:
bond_summary = "; ".join(
f"{el1}–{el2} ≤ {length:g} Å" for el1, el2, length in data.bonds
)
rows = (
("Compound", data.formula),
("Space group", f"{data.space_group} (#{data.number})"),
("Supercell", data.supercell),
("Force data", data.force_data or ""),
("NAC", "yes" if data.nac else "no"),
(f"k path ({data.path_source})", data.dispersion.path_string),
("q points", str(data.dispersion.n_qpoints)),
("Bonds", bond_summary),
)
return "".join(f"<tr><td>{name}</td><td>{value}</td></tr>" for name, value in rows if value)
_CSS = """\
* { box-sizing: border-box; }
body { margin: 0; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
color: #333; background: #fff; height: 100vh; display: flex; flex-direction: column; }
#topbar { background: #2c3e50; color: #ecf0f1; padding: 8px 16px;
display: flex; justify-content: space-between; align-items: baseline; gap: 16px; }
#topbar .brand { font-size: 18px; font-weight: bold; white-space: nowrap; }
#topbar .brand small { font-weight: normal; opacity: 0.8; margin-left: 8px; }
#topbar .page-title { font-size: 13px; opacity: 0.9; text-align: right; }
#container { flex: 1; display: flex; min-height: 0; }
#sidebar { width: 360px; min-width: 360px; overflow-y: auto; background: #f7f7f7;
border-right: 1px solid #ddd; padding: 12px 16px; font-size: 13px; }
#sidebar h2 { font-size: 13px; text-transform: uppercase; letter-spacing: 0.05em;
color: #2c3e50; border-bottom: 2px solid #2c3e50; padding-bottom: 3px;
margin: 18px 0 8px; }
#sidebar h2:first-child { margin-top: 4px; }
table.info { width: 100%; border-collapse: collapse; }
table.info td { padding: 2px 4px; vertical-align: top; }
table.info td:first-child { color: #777; width: 36%; }
#qpoints { display: flex; flex-wrap: wrap; gap: 4px; }
#qpoints .qgroup { flex-basis: 100%; color: #777; font-size: 11px; margin-top: 4px; }
button.qbtn, button.vbtn { font: inherit; font-size: 12px; padding: 3px 7px;
border: 1px solid #c8d2dc;
background: #fff; border-radius: 3px; cursor: pointer; color: #2c3e50; }
button.qbtn:hover, button.vbtn:hover { background: #eaf1f8; }
button.qbtn.active { background: #2c3e50; border-color: #2c3e50; color: #fff; }
table#mode-table { width: 100%; border-collapse: collapse; background: #fff;
border: 1px solid #e0e0e0; font-size: 12px; }
table#mode-table th { background: #2c3e50; color: #fff; font-weight: normal;
padding: 4px 5px; text-align: left; white-space: nowrap; }
table#mode-table td { padding: 3px 5px; border-top: 1px solid #eee; cursor: pointer;
white-space: nowrap; }
table#mode-table td.num { text-align: right; font-variant-numeric: tabular-nums; }
table#mode-table th.num { text-align: right; }
table#mode-table td.irrep { font-family: Menlo, Consolas, monospace; font-size: 11px; }
table#mode-table tr.set-start td { border-top: 1px solid #b9c4cf; }
tr.mode-row:hover { background: #eaf1f8; }
tr.mode-row.active { background: #d5e5f5; font-weight: bold; }
tr.mode-row.imaginary td { color: #e34948; }
.control { margin: 6px 0; display: flex; align-items: center; gap: 8px; }
.control label { flex: 1; }
.control input[type=range] { width: 130px; }
.control .value { width: 52px; text-align: right; font-variant-numeric: tabular-nums; }
.note { color: #777; font-size: 12px; margin: 4px 0; }
.credit { margin-top: 24px; padding-top: 8px; border-top: 1px solid #ddd;
font-size: 11px; color: #888; }
.credit a { color: #2c6aa0; }
#main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
#mode-title { padding: 8px 14px; font-size: 15px; border-bottom: 1px solid #eee;
background: #fff; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
#mode-title .irrep { font-family: Menlo, Consolas, monospace; color: #2c6aa0; }
#mode-title .imaginary { color: #e34948; }
#band { flex: 0 0 38%; min-height: 0; border-bottom: 1px solid #eee; }
#plot { flex: 1; min-height: 0; }
"""
_SCRIPT = r"""
var CURVE = '__CURVE__', IMAGINARY = '__IMAGINARY__', ARROW = '__ARROW__';
var CAMERA_EYE = __CAMERA_EYE__;
var plotDiv = document.getElementById('plot');
var bandDiv = document.getElementById('band');
var state = {point: 0, mode: 0, phase: 0, animating: false, last: null, uirevision: 0,
view: null, aspect: null};
var ORTHO_ZOOM = 1.9, ORTHO_FILL = 0.9;
var scene = null; // trace layout and the field of the current mode
function isChecked(id) {
var element = document.getElementById(id);
return element ? element.checked : true;
}
function amplitude() { return Number(document.getElementById('amplitude').value); }
function isImaginary(f) { return f < DATA.threshold; }
function fmt(f) { return (Math.abs(f) < 5e-5 ? 0 : f).toFixed(4); }
// ---- the displacement field: Re[u_a exp(i(2 pi q.T - phi))] -------------
function modeField(point, mode) {
var q = point.q, atoms = point.atoms, re = [], im = [];
for (var j = 0; j < atoms.a.length; j++) {
var u = mode.u[atoms.a[j]], T = atoms.T[j];
var theta = 2 * Math.PI * (q[0] * T[0] + q[1] * T[1] + q[2] * T[2]);
var c = Math.cos(theta), s = Math.sin(theta);
re.push([u[0][0] * c - u[0][1] * s, u[1][0] * c - u[1][1] * s, u[2][0] * c - u[2][1] * s]);
im.push([u[0][0] * s + u[0][1] * c, u[1][0] * s + u[1][1] * c, u[2][0] * s + u[2][1] * c]);
}
return {re: re, im: im};
}
function atomPositions(phase) {
// equilibrium positions, displaced by the pattern at the animation phase
var point = DATA.points[state.point], p = point.atoms.p;
if (!state.animating) { return p; }
var A = amplitude(), c = Math.cos(phase), s = Math.sin(phase), out = [];
for (var j = 0; j < p.length; j++) {
var re = scene.field.re[j], im = scene.field.im[j];
out.push([p[j][0] + A * (re[0] * c + im[0] * s),
p[j][1] + A * (re[1] * c + im[1] * s),
p[j][2] + A * (re[2] * c + im[2] * s)]);
}
return out;
}
// ---- 3D traces -----------------------------------------------------------
function groupTrace(point, group, positions) {
var xs = [], ys = [], zs = [];
group.slots.forEach(function (j) {
xs.push(positions[j][0]); ys.push(positions[j][1]); zs.push(positions[j][2]);
});
return {x: xs, y: ys, z: zs};
}
function arrowData(positions) {
// shafts from the (moving) atom to atom + pattern, heads as cones at the tip
var A = amplitude(), re = scene.field.re;
var sx = [], sy = [], sz = [], cx = [], cy = [], cz = [], cu = [], cv = [], cw = [];
for (var j = 0; j < positions.length; j++) {
var d = re[j], n = Math.sqrt(d[0] * d[0] + d[1] * d[1] + d[2] * d[2]);
if (n < DATA.arrowCutoff) { continue; }
var p = positions[j];
var tip = [p[0] + A * d[0], p[1] + A * d[1], p[2] + A * d[2]];
var f = 1 - 0.9 * DATA.headFraction; // the shaft ends inside the head
sx.push(p[0], p[0] + f * A * d[0], null); sy.push(p[1], p[1] + f * A * d[1], null);
sz.push(p[2], p[2] + f * A * d[2], null);
cx.push(tip[0]); cy.push(tip[1]); cz.push(tip[2]);
cu.push(A * d[0]); cv.push(A * d[1]); cw.push(A * d[2]);
}
return {shaft: {x: sx, y: sy, z: sz}, cone: {x: cx, y: cy, z: cz, u: cu, v: cv, w: cw}};
}
function bondData(bond, positions) {
var xs = [], ys = [], zs = [];
bond.pairs.forEach(function (pair) {
var a = positions[pair[0]], b = positions[pair[1]];
xs.push(a[0], b[0], null); ys.push(a[1], b[1], null); zs.push(a[2], b[2], null);
});
return {x: xs, y: ys, z: zs};
}
function polyData(positions) {
// every drawn atom is a vertex; the faces index them
return {x: positions.map(function (p) { return p[0]; }),
y: positions.map(function (p) { return p[1]; }),
z: positions.map(function (p) { return p[2]; })};
}
function groupsOf(point) {
// one trace per element, in alphabetical order (as the SALC viewer)
var symbols = Array.from(new Set(point.atoms.s)).sort();
return symbols.map(function (symbol) {
var slots = [];
point.atoms.s.forEach(function (s, j) { if (s === symbol) { slots.push(j); } });
return {symbol: symbol, slots: slots};
});
}
function sceneTraces(point) {
// atom markers have a fixed size in pixels: shrink them with the extent of
// the display cell so that the default view keeps the proportions
var extent = Math.max.apply(null, point.lattice.map(function (v) {
return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
}));
scene.markerScale = Math.max(0.55, Math.min(1.0, 6.0 / extent));
var traces = [], positions = atomPositions(state.phase);
var cell = Object.assign({}, point.edges);
traces.push(cell);
DATA.axes.forEach(function (trace) { traces.push(trace); });
var cellEnd = traces.length;
var groups = groupsOf(point);
groups.forEach(function (group) {
var xyz = groupTrace(point, group, positions);
var radius = DATA.radii[group.symbol] || 0.8;
traces.push({type: 'scatter3d', mode: 'markers', x: xyz.x, y: xyz.y, z: xyz.z,
marker: {size: scene.markerScale * (1.6 + 2.2 * radius),
color: DATA.colors[group.symbol] || '#cccccc',
line: {color: '#333333', width: 1}},
name: group.symbol,
text: group.slots.map(function (j) {
return group.symbol + (point.atoms.a[j] + 1)
+ ' T = (' + point.atoms.T[j].join(', ') + ')';
}),
hoverinfo: 'text'});
});
var atomsEnd = traces.length;
var arrows = arrowData(positions);
traces.push({type: 'scatter3d', mode: 'lines',
x: arrows.shaft.x, y: arrows.shaft.y, z: arrows.shaft.z,
line: {color: ARROW, width: 6}, hoverinfo: 'skip', showlegend: false});
traces.push({type: 'cone', x: arrows.cone.x, y: arrows.cone.y, z: arrows.cone.z,
u: arrows.cone.u, v: arrows.cone.v, w: arrows.cone.w,
anchor: 'tip', sizemode: 'raw', sizeref: DATA.headFraction,
colorscale: [[0, ARROW], [1, ARROW]], showscale: false,
lighting: {ambient: 0.75, diffuse: 0.5, specular: 0.2},
hoverinfo: 'skip', showlegend: false});
var arrowsEnd = traces.length;
point.bonds.forEach(function (bond) {
var xyz = bondData(bond, positions);
traces.push({type: 'scatter3d', mode: 'lines', x: xyz.x, y: xyz.y, z: xyz.z,
line: {color: '#7a7a7a', width: 5}, name: bond.name, hoverinfo: 'skip'});
});
var bondsEnd = traces.length;
point.polyhedra.forEach(function (poly) {
var xyz = polyData(positions);
traces.push({type: 'mesh3d', x: xyz.x, y: xyz.y, z: xyz.z,
i: poly.faces.map(function (f) { return f[0]; }),
j: poly.faces.map(function (f) { return f[1]; }),
k: poly.faces.map(function (f) { return f[2]; }),
opacity: 0.35, color: DATA.colors[poly.element] || '#cccccc', flatshading: true,
name: poly.element + ' polyhedra', showlegend: true, hoverinfo: 'skip'});
});
scene.groups = groups;
scene.cellEnd = cellEnd; scene.atomsEnd = atomsEnd; scene.arrowsEnd = arrowsEnd;
scene.bondsEnd = bondsEnd; scene.n = traces.length;
traces.forEach(function (trace, index) { trace.visible = traceVisible(index); });
return traces;
}
function traceVisible(index) {
if (index < scene.cellEnd) { return isChecked('show-cell'); }
if (index < scene.atomsEnd) { return isChecked('show-atoms'); }
if (index < scene.arrowsEnd) { return isChecked('show-arrows'); }
if (index < scene.bondsEnd) { return isChecked('show-bonds'); }
return isChecked('show-poly');
}
function applyVisibility() {
var indices = [], visible = [];
for (var i = 0; i < scene.n; i++) { indices.push(i); visible.push(traceVisible(i)); }
Plotly.restyle(plotDiv, {visible: visible}, indices);
}
function updateScene() {
// move atoms, arrows, bonds and polyhedra to the current phase: one restyle
// of their coordinates, one of the cone vectors
var point = DATA.points[state.point], positions = atomPositions(state.phase);
var update = {x: [], y: [], z: []}, indices = [];
var add = function (xyz, index) {
update.x.push(xyz.x); update.y.push(xyz.y); update.z.push(xyz.z); indices.push(index);
};
scene.groups.forEach(function (group, k) {
add(groupTrace(point, group, positions), scene.cellEnd + k);
});
var arrows = arrowData(positions);
add(arrows.shaft, scene.atomsEnd);
add(arrows.cone, scene.atomsEnd + 1);
point.bonds.forEach(function (bond, k) { add(bondData(bond, positions), scene.arrowsEnd + k); });
point.polyhedra.forEach(function (poly, k) { add(polyData(positions), scene.bondsEnd + k); });
Plotly.restyle(plotDiv, update, indices);
Plotly.restyle(plotDiv, {u: [arrows.cone.u], v: [arrows.cone.v], w: [arrows.cone.w]},
[scene.atomsEnd + 1]);
}
// ---- dispersion chart ----------------------------------------------------
function bandTraces() {
var band = DATA.band, xs = [], ys = [], rx = [], ry = [];
var nBands = band.frequencies[0][0].length;
for (var b = 0; b < nBands; b++) {
for (var leg = 0; leg < band.distances.length; leg++) {
var d = band.distances[leg], f = band.frequencies[leg];
for (var i = 0; i < d.length; i++) {
xs.push(d[i]); ys.push(f[i][b]);
rx.push(d[i]); ry.push(isImaginary(f[i][b]) ? f[i][b] : null);
}
xs.push(null); ys.push(null); rx.push(null); ry.push(null);
}
}
var mx = [], my = [], mc = [], mt = [], md = [];
DATA.points.forEach(function (point, pi) {
if (point.x === null) { return; }
var seen = {};
point.modes.forEach(function (mode, mi) {
if (seen[mode.set]) { return; }
seen[mode.set] = true;
mx.push(point.x); my.push(mode.freq);
mc.push(isImaginary(mode.freq) ? IMAGINARY : CURVE);
mt.push(pointLabel(point) + ' ' + mode.irrep + '<br>' + fmt(mode.freq) + ' THz');
md.push([pi, mi]);
});
});
return [
{type: 'scatter', mode: 'lines', x: xs, y: ys, line: {color: CURVE, width: 1.3},
hoverinfo: 'skip', showlegend: false},
{type: 'scatter', mode: 'lines', x: rx, y: ry, line: {color: IMAGINARY, width: 1.6},
hoverinfo: 'skip', showlegend: false},
{type: 'scatter', mode: 'markers', x: mx, y: my, text: mt, customdata: md,
marker: {size: 8, color: mc, line: {color: '#ffffff', width: 1}},
hovertemplate: '%{text}<extra></extra>', showlegend: false},
{type: 'scatter', mode: 'markers', x: [], y: [],
marker: {size: 15, color: 'rgba(0,0,0,0)', line: {color: '#2c3e50', width: 2.5}},
hoverinfo: 'skip', showlegend: false}
];
}
function bandLayout() {
var band = DATA.band, last = band.distances[band.distances.length - 1];
var xmax = last[last.length - 1];
var shapes = band.ticks.slice(1, -1).map(function (t) {
return {type: 'line', xref: 'x', yref: 'paper', x0: t, x1: t, y0: 0, y1: 1,
line: {color: '#c8c8c8', width: 1}, layer: 'below'};
});
shapes.push({type: 'line', xref: 'paper', yref: 'y', x0: 0, x1: 1, y0: 0, y1: 0,
line: {color: '#777777', width: 1, dash: 'dash'}, layer: 'below'});
return {
margin: {l: 58, r: 14, t: 10, b: 28},
paper_bgcolor: '#ffffff', plot_bgcolor: '#ffffff',
font: {family: "'Helvetica Neue', Helvetica, Arial, sans-serif", size: 12, color: '#333'},
xaxis: {range: [0, xmax], tickvals: band.ticks, ticktext: band.tickText, showgrid: false,
zeroline: false, showline: true, linecolor: '#444', mirror: true, ticks: '',
tickfont: {size: 13}, fixedrange: true},
yaxis: {title: {text: 'Frequency (THz)', standoff: 6}, zeroline: false, showgrid: false,
showline: true, linecolor: '#444', mirror: true, ticks: 'outside', fixedrange: true},
hovermode: 'closest', shapes: shapes, dragmode: false
};
}
function markSelected() {
var point = DATA.points[state.point], mode = point.modes[state.mode];
var x = point.x === null ? [] : [point.x], y = point.x === null ? [] : [mode.freq];
Plotly.restyle(bandDiv, {x: [x], y: [y]}, [3]);
}
// ---- sidebar -------------------------------------------------------------
function pointLabel(point) { return point.label || point.name; }
function buildQButtons() {
// the special points, then (--all-irreps) the segment midpoints
var html = '', midpoints = false;
DATA.points.forEach(function (point, i) {
if (point.segment && !midpoints) {
midpoints = true;
html += '<div class="qgroup">Segment midpoints</div>';
}
html += '<button class="qbtn" data-index="' + i + '" onclick="selectPoint(' + i + ', 0)"'
+ (point.segment ? ' title="midpoint of ' + point.segment + '"' : '') + '>'
+ pointLabel(point) + ' ' + point.qText + '</button>';
});
document.getElementById('qpoints').innerHTML = html;
}
function buildModeTable(point) {
var gamma = point.gamma;
var head = '<tr><th class="num">Band</th><th class="num">Freq (THz)</th><th>Irrep</th>'
+ '<th class="num">Comp.</th>'
+ (gamma ? '<th>Mulliken</th><th>Activity</th>' : '') + '</tr>';
var rows = point.modes.map(function (mode, i) {
var classes = 'mode-row' + (mode.comp === 1 ? ' set-start' : '')
+ (isImaginary(mode.freq) ? ' imaginary' : '');
return '<tr class="' + classes + '" onclick="selectMode(' + i + ')">'
+ '<td class="num">' + mode.band + '</td><td class="num">' + fmt(mode.freq) + '</td>'
+ '<td class="irrep">' + mode.irrep + '</td><td class="num">' + mode.comp + '</td>'
+ (gamma ? '<td>' + (mode.mulliken || '') + '</td><td>' + (mode.activity || '') + '</td>'
: '')
+ '</tr>';
}).join('');
document.getElementById('mode-table').innerHTML = head + rows;
document.getElementById('cell-line').innerHTML =
(point.segment ? 'Segment: ' + point.segment + ' (midpoint)<br>' : '')
+ 'Display cell: ' + point.cell;
document.getElementById('point-notes').innerHTML = point.notes.map(function (note) {
return '<div class="note">NOTE: ' + note + '</div>';
}).join('');
}
function updateTitle() {
var point = DATA.points[state.point], mode = point.modes[state.mode];
var extra = point.gamma && (mode.mulliken || mode.activity)
? ' · ' + [mode.mulliken, mode.activity].filter(Boolean).join(', ') : '';
document.getElementById('mode-title').innerHTML =
'<b>' + point.name + '</b> ' + point.qText
+ (point.segment ? ', midpoint of ' + point.segment : '') + ' · band ' + mode.band
+ ' <span class="irrep">' + mode.irrep + '</span> comp ' + mode.comp
+ ' · <span class="' + (isImaginary(mode.freq) ? 'imaginary' : '') + '">'
+ fmt(mode.freq) + ' THz</span>' + extra;
}
function highlight() {
document.querySelectorAll('#qpoints button.qbtn').forEach(function (button, i) {
button.classList.toggle('active', i === state.point);
});
document.querySelectorAll('tr.mode-row').forEach(function (row, i) {
row.classList.toggle('active', i === state.mode);
});
}
// ---- selection -----------------------------------------------------------
function currentCamera() {
var layoutScene = plotDiv._fullLayout && plotDiv._fullLayout.scene;
return (layoutScene && layoutScene.camera && layoutScene.camera.eye)
? layoutScene.camera
: {eye: CAMERA_EYE, up: {x: 0, y: 0, z: 1}};
}
function selectPoint(index, modeIndex) {
var changed = index !== state.point || scene === null;
state.point = index;
var point = DATA.points[index];
state.mode = Math.max(0, Math.min(modeIndex || 0, point.modes.length - 1));
if (changed) {
var camera = scene === null ? null : currentCamera();
scene = {field: modeField(point, point.modes[state.mode])};
buildModeTable(point);
var traces = sceneTraces(point);
var layout = JSON.parse(JSON.stringify(LAYOUT));
layout.uirevision = state.uirevision;
if (camera && !state.view) {
layout.scene.camera = {eye: camera.eye, up: camera.up, center: camera.center};
}
if (state.view) {
// stay orthographic down the axis of the new cell: every change of the
// projection makes plotly build a new WebGL context, and the browser
// drops the oldest one after about 16
layout.scene.camera = axisCamera(state.view, point.lattice);
}
state.aspect = null;
Plotly.react(plotDiv, traces, layout, {responsive: true, displaylogo: false}).then(function () {
// an axis view is set up again on the new display cell
if (state.view) { return viewAlong(state.view); }
syncCompass(currentCamera());
});
} else {
scene.field = modeField(point, point.modes[state.mode]);
updateScene();
}
highlight();
updateTitle();
markSelected();
}
function selectMode(index) { selectPoint(state.point, index); }
function onAmplitude(value) {
document.getElementById('amplitude-value').innerHTML = Number(value).toFixed(2) + ' Å';
updateScene();
}
function onSpeed(value) {
document.getElementById('speed-value').innerHTML = Number(value).toFixed(1) + ' Hz';
}
function toggleAnimation(on) {
state.animating = on;
state.phase = 0;
state.last = null;
if (on) { requestAnimationFrame(step); } else { updateScene(); }
}
function step(time) {
if (!state.animating) { return; }
if (state.last !== null) {
var speed = Number(document.getElementById('speed').value);
state.phase = (state.phase + 2 * Math.PI * speed * (time - state.last) / 1000) % (2 * Math.PI);
}
state.last = time;
updateScene();
requestAnimationFrame(step);
}
function syncCompass(camera) {
// update ONLY the compass scene through plotly's internal setViewport:
// calling Plotly.relayout during a drag would redraw the main scene
// from the (stale) stored camera and cancel the rotation in progress.
var eye = camera.eye;
var radius = Math.sqrt(eye.x * eye.x + eye.y * eye.y + eye.z * eye.z) || 1;
var scale = 2.0 / radius; // compass orientation follows the view, size stays fixed
var sceneLayout = plotDiv._fullLayout && plotDiv._fullLayout.scene2;
var sceneObject = sceneLayout && sceneLayout._scene;
if (!sceneObject) { return; }
var scaledEye = {x: eye.x * scale, y: eye.y * scale, z: eye.z * scale};
var upVector = camera.up
? {x: camera.up.x, y: camera.up.y, z: camera.up.z}
: {x: 0, y: 0, z: 1};
sceneLayout.camera.eye = scaledEye;
sceneLayout.camera.up = upVector;
sceneLayout.camera.center = {x: 0, y: 0, z: 0};
sceneLayout.camera.projection = sceneLayout.camera.projection || {type: 'perspective'};
// persist into the user layout too: on drag end plotly rebuilds the
// compass scene from plotDiv.layout, which would reset the camera
if (plotDiv.layout && plotDiv.layout.scene2) {
plotDiv.layout.scene2.camera = {eye: scaledEye, up: upVector, center: {x: 0, y: 0, z: 0}};
}
try { sceneObject.setViewport(sceneLayout); } catch (error) { /* keep the drag alive */ }
}
function axisCamera(axis, lattice) {
// the orthographic camera down the a, b or c axis of a cell (up: c, c, b)
var k = {a: 0, b: 1, c: 2}[axis];
var unit = function (v) {
var n = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
return {x: v[0] / n, y: v[1] / n, z: v[2] / n};
};
var d = unit(lattice[k]), up = unit(lattice[k === 2 ? 1 : 2]);
return {eye: {x: 2 * d.x, y: 2 * d.y, z: 2 * d.z}, up: up, center: {x: 0, y: 0, z: 0},
projection: {type: 'orthographic'}};
}
function orthoZoom(camera, lattice, base) {
// the zoom of an axis view: ORTHO_ZOOM, or less when the cell projected on
// the screen would fill more than ORTHO_FILL of the scene (an orthographic
// scene shows about 2 zoomed units vertically); a cube-shaped cell keeps
// ORTHO_ZOOM, an elongated one (1 x 4 x 1 cells of a line midpoint seen
// down a) is zoomed out until it fits
var sceneLayout = plotDiv._fullLayout.scene, scale = 0;
['x', 'y', 'z'].forEach(function (key) {
var range = sceneLayout[key + 'axis'].range;
scale = Math.max(scale, base[key] / Math.max(range[1] - range[0], 1e-9));
});
var unit = function (v) {
var n = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) || 1;
return [v[0] / n, v[1] / n, v[2] / n];
};
var d = unit([camera.eye.x, camera.eye.y, camera.eye.z]);
var u = [camera.up.x, camera.up.y, camera.up.z];
var ud = u[0] * d[0] + u[1] * d[1] + u[2] * d[2];
u = unit([u[0] - ud * d[0], u[1] - ud * d[1], u[2] - ud * d[2]]);
var r = [d[1] * u[2] - d[2] * u[1], d[2] * u[0] - d[0] * u[2], d[0] * u[1] - d[1] * u[0]];
var lo = [Infinity, Infinity], hi = [-Infinity, -Infinity];
for (var corner = 0; corner < 8; corner++) {
var f = [corner & 1, (corner >> 1) & 1, (corner >> 2) & 1], p = [0, 0, 0];
for (var c = 0; c < 3; c++) {
p[c] = f[0] * lattice[0][c] + f[1] * lattice[1][c] + f[2] * lattice[2][c];
}
var across = p[0] * r[0] + p[1] * r[1] + p[2] * r[2];
var upward = p[0] * u[0] + p[1] * u[1] + p[2] * u[2];
lo[0] = Math.min(lo[0], across); hi[0] = Math.max(hi[0], across);
lo[1] = Math.min(lo[1], upward); hi[1] = Math.max(hi[1], upward);
}
var width = (hi[0] - lo[0]) * scale, height = (hi[1] - lo[1]) * scale;
var ratio = plotDiv.clientWidth / Math.max(plotDiv.clientHeight, 1);
return Math.min(ORTHO_ZOOM, 2 * ORTHO_FILL / Math.max(height, 1e-9),
2 * ORTHO_FILL * ratio / Math.max(width, 1e-9));
}
function viewAlong(axis) {
// look down the a, b or c axis of the display cell (up: c, c, b) in
// orthographic projection, so that the atoms of a column coincide, or
// return to the initial perspective view
var camera = {eye: CAMERA_EYE, up: {x: 0, y: 0, z: 1}, center: {x: 0, y: 0, z: 0},
projection: {type: 'perspective'}};
var k = {a: 0, b: 1, c: 2}[axis];
var layout = JSON.parse(JSON.stringify(LAYOUT));
state.view = k === undefined ? null : axis;
if (k !== undefined) {
camera = axisCamera(axis, DATA.points[state.point].lattice);
// plotly zooms an orthographic scene through its aspect ratio
var aspect = plotDiv._fullLayout.scene.aspectratio;
if (plotDiv._fullLayout.scene.aspectmode !== 'manual') { state.aspect = aspect; }
var base = state.aspect || aspect;
var zoom = orthoZoom(camera, DATA.points[state.point].lattice, base);
layout.scene.aspectmode = 'manual';
layout.scene.aspectratio = {x: zoom * base.x, y: zoom * base.y, z: zoom * base.z};
}
// a new projection needs a full redraw: react with a new uirevision
state.uirevision += 1;
layout.scene.camera = camera;
layout.uirevision = state.uirevision;
return Plotly.react(plotDiv, plotDiv.data, layout).then(function () { syncCompass(camera); });
}
function fromHash() {
// #q=R&mode=4&view=a : the first q point named R (G, GM, GAMMA for Gamma),
// band 4, viewed down the a axis; #q=DT(GM-X) the midpoint of the segment
// GM-X, #q=7 the seventh q button
var params = {};
location.hash.replace(/^#/, '').split('&').forEach(function (part) {
var kv = part.split('=');
if (kv.length === 2) { params[kv[0].toLowerCase()] = decodeURIComponent(kv[1]); }
});
var pointIndex = 0, modeIndex = 0;
if (params.q) {
var wanted = params.q.toUpperCase().replace(/\s+/g, '');
if (['G', 'GAMMA', 'Γ'].indexOf(wanted) >= 0) { wanted = 'GM'; }
var found = -1;
if (/^[0-9]+$/.test(wanted)) {
var n = parseInt(wanted, 10);
if (n >= 1 && n <= DATA.points.length) { found = n - 1; }
}
DATA.points.forEach(function (point, i) {
if (found >= 0) { return; }
var qualified = point.segment ? (point.name + '(' + point.segment + ')').toUpperCase() : '';
if (point.name.toUpperCase().split('|').indexOf(wanted) >= 0 || wanted === qualified) {
found = i;
}
});
if (found >= 0) { pointIndex = found; }
}
if (params.mode) {
var band = parseInt(params.mode, 10);
DATA.points[pointIndex].modes.forEach(function (mode, i) {
if (mode.band === band) { modeIndex = i; }
});
}
return [pointIndex, modeIndex, params.view];
}
buildQButtons();
Plotly.newPlot(bandDiv, bandTraces(), bandLayout(), {responsive: true, displaylogo: false,
displayModeBar: false}).then(function () {
bandDiv.on('plotly_click', function (event) {
var hit = event.points && event.points.filter(function (p) { return p.customdata; })[0];
if (hit) { selectPoint(hit.customdata[0], hit.customdata[1]); }
});
var start = fromHash();
selectPoint(start[0], start[1]);
if (start[2]) { setTimeout(function () { viewAlong(start[2]); }, 0); }
plotDiv.on('plotly_relayouting', function (event) {
if (event['scene.camera']) { syncCompass(event['scene.camera']); }
});
plotDiv.on('plotly_relayout', function (event) {
if (event['scene.camera']) { syncCompass(event['scene.camera']); }
});
});
window.addEventListener('hashchange', function () {
var start = fromHash();
selectPoint(start[0], start[1]);
if (start[2]) { viewAlong(start[2]); }
});
document.addEventListener('keydown', function (event) {
if (event.target && /INPUT|SELECT|TEXTAREA/.test(event.target.tagName)) { return; }
var n = DATA.points[state.point].modes.length;
if (event.key === 'ArrowDown') {
selectMode(Math.min(state.mode + 1, n - 1)); event.preventDefault();
}
if (event.key === 'ArrowUp') { selectMode(Math.max(state.mode - 1, 0)); event.preventDefault(); }
});
"""
def _scene_layout(conventional: bool) -> dict:
"""The 3D scene and the compass scene2 of the SALC viewer."""
return {
"scene": {
"domain": {"x": [0.0, 1.0], "y": [0.0, 1.0]},
"aspectmode": "data",
"xaxis": {"visible": False},
"yaxis": {"visible": False},
"zaxis": {"visible": False},
"bgcolor": "#ffffff",
"camera": {"eye": dict(CAMERA_EYE)},
},
"scene2": {
"domain": (
{"x": [0.02, 0.26], "y": [0.02, 0.34]}
if conventional
else {"x": [0.03, 0.19], "y": [0.02, 0.22]}
),
"aspectmode": "cube",
"xaxis": {"visible": False, "range": [-2.2, 2.2]},
"yaxis": {"visible": False, "range": [-2.2, 2.2]},
"zaxis": {"visible": False, "range": [-2.2, 2.2]},
"bgcolor": "rgba(0,0,0,0)",
"dragmode": False,
},
"margin": {"l": 0, "r": 0, "t": 0, "b": 0},
"paper_bgcolor": "#ffffff",
"legend": {"x": 0.99, "y": 0.95, "xanchor": "right"},
"showlegend": True,
"uirevision": 0,
}
[docs]
def write_phonon_viewer_html(data: PhononViewer, output: str | None = None) -> None:
"""Write the standalone phonon mode viewer page.
The page ships, per q point, the drawn atoms (element, Cartesian
position, primitive atom index ``a``, lattice translation ``T``), the
bonds and polyhedra as atom pairs and vertex lists, and per mode the
atomic-gauge vectors ``u_a`` (:class:`ViewerMode`); the script rebuilds
the displacement of atom ``(a, T)`` as ``Re[u_a exp(i(2 pi q.T - phi))]``
times the amplitude (Angstrom), ``phi`` the animation phase. The
dispersion ships the bands per leg, the ticks and, per labeled level,
the mode it selects.
The page opens on the first q point and its first mode; the URL hash
``#q=R&mode=4&view=a`` selects the first q point named ``R`` (``G``,
``GM`` or ``GAMMA`` for Gamma), the mode of band 4 and the orthographic
view down the a axis of the display cell (``b``, ``c``); ``#q=DT(GM-X)``
selects the midpoint of the segment GM-X and ``#q=7`` the seventh q
button. The arrow keys step through the modes.
Args:
data: The :class:`PhononViewer` of :func:`phonon_viewer_data`.
output: Path of the HTML file (default ``phonon_visualize.html``,
``phonon_visualize_all.html`` when ``data.all_irreps``).
"""
if output is None:
output = DEFAULT_OUTPUT_ALL if data.all_irreps else DEFAULT_OUTPUT
from .visualize_basis import _axis_traces, _crystod_citation_html
payload = _payload(data)
payload["axes"] = _axis_traces(
data.primitive_lattice, "abc", conventional_lattice=data.conventional_lattice
)
payload["headFraction"] = HEAD_FRACTION
conventional = data.conventional_lattice is not None
has_bonds = any(point.bonds for point in data.points)
has_poly = any(point.polyhedra for point in data.points)
bond_controls = ""
if has_bonds:
bond_controls += (
" <div class=\"control\"><label><input type=\"checkbox\" id=\"show-bonds\" checked\n"
" onchange=\"applyVisibility()\"/> show bonds</label></div>\n"
)
if has_poly:
bond_controls += (
" <div class=\"control\"><label><input type=\"checkbox\" id=\"show-poly\" checked\n"
" onchange=\"applyVisibility()\"/> show polyhedra</label></div>\n"
)
run_notes = "".join(f"<div class=\"note\">NOTE: {note}</div>" for note in data.notes)
title = f"{data.formula} phonon modes"
page_title = (
f"{data.formula} ({data.space_group}, #{data.number}): phonon modes along "
f"{data.dispersion.path_string}" + (" (NAC)" if data.nac else "")
)
script = (
_SCRIPT.replace("__CURVE__", CURVE)
.replace("__IMAGINARY__", IMAGINARY)
.replace("__ARROW__", ARROW)
.replace("__CAMERA_EYE__", json.dumps(CAMERA_EYE))
)
html = (
"<!DOCTYPE html>\n<html>\n<head>\n<meta charset=\"utf-8\"/>\n"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"/>\n"
f"<title>{title}</title>\n"
"<script src=\"https://cdn.plot.ly/plotly-2.32.0.min.js\"></script>\n"
f"<style>\n{_CSS}</style>\n</head>\n<body>\n"
"<div id=\"topbar\">\n"
" <div class=\"brand\">CrystOD<small>Phonon mode viewer</small></div>\n"
f" <div class=\"page-title\">{page_title}</div>\n"
"</div>\n"
"<div id=\"container\">\n"
"<div id=\"sidebar\">\n"
" <h2>Structure</h2>\n"
f" <table class=\"info\">{_info_rows(data)}</table>\n"
f" {run_notes}\n"
" <h2>q point</h2>\n"
" <div id=\"qpoints\"></div>\n"
" <h2>Phonon modes (click to show)</h2>\n"
" <table id=\"mode-table\"></table>\n"
" <div id=\"point-notes\"></div>\n"
" <h2>Display</h2>\n"
" <div class=\"control\"><label>Amplitude</label>\n"
" <input type=\"range\" id=\"amplitude\" min=\"0.05\" max=\"1.5\" step=\"0.05\"\n"
f" value=\"{data.amplitude:g}\" oninput=\"onAmplitude(this.value)\"/>\n"
f" <span class=\"value\" id=\"amplitude-value\">{data.amplitude:.2f} Å"
"</span></div>\n"
" <div class=\"control\"><label><input type=\"checkbox\" id=\"animate\"\n"
" onchange=\"toggleAnimation(this.checked)\"/> animate</label>\n"
" <input type=\"range\" id=\"speed\" min=\"0.1\" max=\"2\" step=\"0.1\" value=\"0.5\"\n"
" oninput=\"onSpeed(this.value)\"/>\n"
" <span class=\"value\" id=\"speed-value\">0.5 Hz</span></div>\n"
" <div class=\"control\"><label><input type=\"checkbox\" id=\"show-arrows\" checked\n"
" onchange=\"applyVisibility()\"/> show arrows</label></div>\n"
" <div class=\"control\"><label><input type=\"checkbox\" id=\"show-cell\" checked\n"
" onchange=\"applyVisibility()\"/> show cell edges & abc axes</label></div>\n"
" <div class=\"control\"><label><input type=\"checkbox\" id=\"show-atoms\" checked\n"
" onchange=\"applyVisibility()\"/> show atoms</label></div>\n"
+ bond_controls +
" <div class=\"control\"><label>View along</label>\n"
" <button class=\"vbtn\" onclick=\"viewAlong('a')\">a</button>\n"
" <button class=\"vbtn\" onclick=\"viewAlong('b')\">b</button>\n"
" <button class=\"vbtn\" onclick=\"viewAlong('c')\">c</button>\n"
" <button class=\"vbtn\" onclick=\"viewAlong('reset')\">reset</button></div>\n"
" <div class=\"note\" id=\"cell-line\"></div>\n"
" <div class=\"credit\">Viewer layout inspired by the\n"
" <a href=\"https://henriquemiranda.github.io/phononwebsite/\"\n"
" target=\"_blank\">phonon website</a>\n"
" by Henrique Miranda (BSD-3-Clause). 3D rendering and charts by plotly;\n"
" atom colors from VESTA. Irrep labels: ISO-IR (H. T. Stokes, B. J. Campbell\n"
" and R. Cordes, Acta Cryst. A69, 388 (2013)).<br><br>\n"
f" {_crystod_citation_html()}</div>\n"
"</div>\n"
"<div id=\"main\">\n"
" <div id=\"mode-title\"></div>\n"
" <div id=\"band\"></div>\n"
" <div id=\"plot\"></div>\n"
"</div>\n"
"</div>\n"
"<script>\n"
f"var DATA = {json.dumps(payload, separators=(',', ':'))};\n"
f"var LAYOUT = {json.dumps(_scene_layout(conventional), separators=(',', ':'))};\n"
f"{script}"
"</script>\n</body>\n</html>\n"
)
with open(output, "w", encoding="utf-8") as handle:
handle.write(html)
# --------------------------------------------------------------------------
# self-check of the shipped data
# --------------------------------------------------------------------------
def _check_reconstruction(phonon, data: PhononViewer, tol: float = 1e-6) -> tuple[float, int]:
"""Check the page's displacement fields against phonopy's modulation.
For every q point and mode, the field the page draws (the shipped,
rounded ``u`` and atom list, rebuilt with the page formula
``Re[u_a exp(2 pi i q.T)]``) must equal the real part of
:func:`crystod.phonon_vector.get_supercell_displacement_field` on the
display cell up to one overall real scale, atom by atom (the drawn atoms
are matched to the supercell atoms by position modulo the display
lattice, so the boundary duplicates and bonded images are checked with
the phase of their own translation), and every supercell atom must be
drawn.
Args:
phonon: The ``phonopy.Phonopy`` object ``data`` was computed from.
data: The :class:`PhononViewer`.
tol: Largest allowed deviation, relative to the largest displacement.
Returns:
``(worst relative deviation, number of modes checked)``.
Raises:
AssertionError: A field deviates by more than ``tol``, or the drawn
atoms do not cover the display cell.
"""
from .phonon_vector import get_supercell_displacement_field
payload = json.loads(json.dumps(_payload(data)))
worst, count = 0.0, 0
for point, shipped in zip(data.points, payload["points"]):
q = np.array(shipped["q"], dtype=float)
atom_index = np.array(shipped["atoms"]["a"], dtype=int)
translations = np.array(shipped["atoms"]["T"], dtype=float)
positions = np.array(shipped["atoms"]["p"], dtype=float)
phases = np.exp(2j * np.pi * translations @ q)
match = None
for mode, shipped_mode in zip(point.modes, shipped["modes"]):
u = np.array(shipped_mode["u"], dtype=float)
u = u[..., 0] + 1j * u[..., 1]
drawn = np.real(u[atom_index] * phases[:, None])
supercell, field_ = get_supercell_displacement_field(
phonon, point.q, point.cell_matrix, mode.vector
)
reference = field_.real
if match is None:
lattice = np.array(supercell.cell, dtype=float)
frac_drawn = positions @ np.linalg.inv(lattice)
frac_super = np.array(supercell.scaled_positions, dtype=float)
diff = frac_drawn[:, None, :] - frac_super[None, :, :]
diff -= np.rint(diff)
distance = np.linalg.norm(diff @ lattice, axis=2)
match = np.argmin(distance, axis=1)
if np.max(distance[np.arange(len(match)), match]) > 2e-3:
raise AssertionError(
f"{point.name}: a drawn atom is not an atom of the display cell"
)
if len(set(match.tolist())) != len(frac_super):
raise AssertionError(
f"{point.name}: the drawn atoms do not cover the display cell"
)
s2uu = [supercell.u2u_map[x] for x in supercell.s2u_map]
if any(s2uu[m] != a for m, a in zip(match, atom_index)):
raise AssertionError(
f"{point.name}: drawn atom matched to another primitive atom"
)
target = reference[match]
size = float(np.max(np.linalg.norm(reference, axis=1)))
scale = float(np.sum(drawn * target) / max(np.sum(drawn * drawn), 1e-300))
deviation = float(np.max(np.abs(scale * drawn - target))) / max(size, 1e-300)
if deviation > tol:
raise AssertionError(
f"{point.name} band {mode.band}: drawn field deviates by {deviation:.2e} "
"from phonopy's modulation"
)
worst = max(worst, deviation)
count += 1
return worst, count
# --------------------------------------------------------------------------
# command line
# --------------------------------------------------------------------------
def build_parser() -> ArgumentParser:
parser = ArgumentParser(description=desc, formatter_class=MyHelpFormatter)
parser.add_argument(
"--dim", required=True, type=str,
help="Supercell dimension used for the force calculation.",
)
parser.add_argument("--poscar", type=str, default="POSCAR", help="POSCAR path.")
parser.add_argument(
"--readfc", action="store_true", help="Read FORCE_CONSTANTS instead of FORCE_SETS.",
)
parser.add_argument(
"--nac", dest="nac", action="store_true",
help="Apply the non-analytical term correction with ./BORN (without it\n"
"a BORN file is not read).",
)
parser.add_argument(
"--tolerance", "-tol", dest="tol", type=float, default=1e-3,
help="Degeneracy tolerance (THz) of the irrep labels.",
)
parser.add_argument(
"--qpoint", nargs="+", default=None,
help="Show one q point only: a special-point label such as R or three\n"
"primitive reciprocal coordinates (default: every labeled special point\n"
"of the path).",
)
parser.add_argument(
"--band", default=None,
help="Manual k path (primitive reciprocal basis), e.g.\n"
'"0 0 0 0 1/2 0 1/2 1/2 0, 1/2 1/2 0 1/2 1/2 1/2" (default: seekpath).',
)
parser.add_argument(
"--band-labels", dest="band_labels", default=None,
help="Names of the vertices of --band (default: their ISO-IR k-vector types).",
)
parser.add_argument(
"--npoints", type=int, default=None, help="q points per leg of the path (default 51).",
)
parser.add_argument(
"--threshold", type=float, default=-0.1,
help="Frequency (THz) below which a level is drawn in red (imaginary).",
)
parser.add_argument(
"--conventional", action="store_true",
help="Display the conventional cell instead of the primitive cell.",
)
parser.add_argument(
"--bond", nargs=3, action="append", default=None, metavar=("EL1", "EL2", "MAX"),
help="Draw bonds between EL1 and EL2 atoms up to MAX Angstroms, plus the\n"
"VESTA-style coordination polyhedra around the EL1 atoms (repeatable),\n"
"e.g. --bond Sc F 2.3.",
)
parser.add_argument(
"--all-irreps", dest="all_irreps", action="store_true",
help="Also show the modes at the midpoints of the path segments (the symmetry\n"
"lines DT, Z, SM, ... with their ISO-IR line irreps), as crystod-phonon\n"
"--irreps --all-irreps labels them; the page is then\n"
f"{DEFAULT_OUTPUT_ALL}. Not with --qpoint.",
)
parser.add_argument(
"--output", "-o", default=None,
help=f"Path of the HTML page (default {DEFAULT_OUTPUT}, with --all-irreps\n"
f"{DEFAULT_OUTPUT_ALL}; {BAND_VECTOR_YAML} keeps its name).",
)
return parser
def _mode_table_lines(point: ViewerPoint) -> list[str]:
"""The terminal table of the modes of one q point (unindented)."""
width = max([5] + [len(mode.irrep) for mode in point.modes])
gamma = point.is_gamma
header = f"{'Band':>4s} {'Freq (THz)':>10s} {'Irrep':<{width}s} Comp."
if gamma:
mulliken_width = max([8] + [len(mode.mulliken or "") for mode in point.modes])
header += f" {'Mulliken':<{mulliken_width}s} Activity"
lines = [header]
for mode in point.modes:
line = (
f"{mode.band:4d} {_clean(mode.frequency, 4):10.4f} "
f"{mode.irrep:<{width}s} {mode.component:5d}"
)
if gamma:
line += f" {mode.mulliken or '-':<{mulliken_width}s} {mode.activity or '-'}"
lines.append(line.rstrip())
return lines
def main(argv: list[str] | None = None) -> None:
from phonopy import load
from .phonon_irreps import (
check_force_constants_consistency,
check_nac_loaded,
format_note_lines,
nac_load_options,
)
from .vasp_io import read_poscar_cell
parser = build_parser()
args = parser.parse_args(argv)
if args.all_irreps and args.qpoint:
parser.error("--all-irreps is not used with --qpoint (--qpoint shows one point).")
output = args.output or (DEFAULT_OUTPUT_ALL if args.all_irreps else DEFAULT_OUTPUT)
bonds: list[tuple[str, str, float]] = []
for el1, el2, max_text in args.bond or []:
try:
bonds.append((el1, el2, float(max_text)))
except ValueError:
raise SystemExit(
f"ERROR: --bond expects a numeric maximum length in Angstroms, got '{max_text}'."
) from None
supercell_matrix = [float(n) for n in args.dim.split()]
if args.readfc:
force_sets, force_constants, force_data = None, "./FORCE_CONSTANTS", "FORCE_CONSTANTS"
else:
force_sets, force_constants, force_data = "./FORCE_SETS", None, "FORCE_SETS"
phonon = load(
supercell_matrix=supercell_matrix,
primitive_matrix="auto",
unitcell=read_poscar_cell(args.poscar),
force_sets_filename=force_sets,
force_constants_filename=force_constants,
**nac_load_options(args.nac),
)
nac_note = check_nac_loaded(phonon, args.nac, "BORN")
fc_note = check_force_constants_consistency(
phonon, force_sets_filename=force_sets, force_constants_filename=force_constants
)
data = phonon_viewer_data(
phonon,
degeneracy_tolerance=args.tol,
band=args.band,
band_labels=args.band_labels,
npoints=args.npoints,
qpoint=args.qpoint,
conventional=args.conventional,
bonds=bonds,
threshold=args.threshold,
force_data=force_data,
all_irreps=args.all_irreps,
)
n_qpoints = write_band_vector_yaml(
phonon, band=args.band, band_labels=args.band_labels, npoints=args.npoints,
filename=BAND_VECTOR_YAML,
)
if n_qpoints != data.dispersion.n_qpoints: # the two runs share the path
raise RuntimeError("band_vector.yaml and the dispersion disagree on the path")
write_phonon_viewer_html(data, output)
print("\n* Structure *")
print(f" Space group: {data.space_group} (#{data.number})")
print(f" Formula: {data.formula}")
print(f" Supercell: {data.supercell} ({force_data})")
if nac_note:
print(f" {nac_note}")
if fc_note:
print("\n".join(format_note_lines(fc_note)))
print("\n* Band path *")
print(f" k path ({data.path_source}): {data.dispersion.path_string} "
f"({data.dispersion.n_qpoints} q points)")
print(" Labeled points: " + ", ".join(point.name for point in data.dispersion.points))
if data.all_irreps:
midpoints = [f"{point.name} ({point.segment})" for point in data.points
if point.is_midpoint]
print(" Segment midpoints: " + (", ".join(midpoints) or "none"))
for note in data.notes:
print(f" NOTE: {note}")
for point in data.points:
print(f"\n* Phonon modes at q = {point.name} {format_q_fraction(point.q)} *")
for line in _mode_table_lines(point):
print(line)
if point.is_midpoint:
print(f" Segment: {point.segment}")
print(f" Display cell: {point.cell_description}")
if point.x is None:
print(" NOTE: this q point is not a labeled vertex of the path "
"(no marker on the dispersion)")
for note in point.notes:
print(f" NOTE: {note}")
print("\n* Output files *")
print(f" Phonon band structure with eigenvectors written to: {BAND_VECTOR_YAML}")
print(f" Phonon mode viewer written to: {output}")
if __name__ == "__main__":
main()