Source code for alm.alm

"""High-level Python interface to the ALAMODE 2.0 ALM library (nanobind backend).

Drop-in compatible replacement for the legacy ``alm`` package (which used a
C/cython wrapper): the same public API is provided on top of the compiled
``alm._alm.ALMCore`` object, plus cleaner primary names (``close()``,
``fix_fc()``, ``fix_fc_from_file()``); the legacy names remain as aliases.

    a = ALM(lavec, xcoord, numbers, verbosity=0)  # ready to use immediately
    a.define(maxorder=2, cutoff_radii=rc)    # up to cubic (fc_order 1=harmonic, 2=cubic)
    a.set_training_data(u, f)                # u, f shape (nsnap, nat, 3)
    A, b = a.get_matrix_elements()           # ALM's exact sensing matrix (for external solvers)
    a.set_fc(coefs)                          # inject an external solution ...
    v, idx = a.get_fc(1, mode="origin")      # ... read the harmonic FCs back, symmetry-expanded
    a.save_fc("out.h5", format="alamode_h5") # write what anphon reads (.h5)
    # 'a' (and its C++ instance) is freed automatically when it goes out of scope.

Units -- Rydberg atomic units internally, as in the ALM CLI.  By default the
input is expected in the same units; pass ``length_unit`` / ``force_unit`` to
the constructor to provide the input in other units (converted on entry):

    lattice vectors, displacements, cutoff radii   ``length_unit``  ('bohr' default, or 'angstrom')
    forces                                         ``force_unit``   ('Ry/bohr' default, 'eV/angstrom' or 'Ha/bohr')
    force constants of order ``fc_order``          Ry/Bohr^(fc_order+1), always
        (``get_fc``/``set_fc``/``fix_fc`` are NOT affected by the units above;
        only ``save_fc(..., format='alamode_h5', fc_unit='eV/angstrom')`` writes
        converted values, with matching ``unit`` metadata in the .h5 file)

Force-constant order convention, used consistently by every method here:

    fc_order = 1 -> harmonic (FC2), 2 -> cubic (FC3), 3 -> quartic (FC4), ...

The C++ instance is created in ``__init__``, so a plain ``a = ALM(...)`` is
enough.  A ``with`` block (or an explicit :meth:`ALM.close`) is optional and
only gives a prompt, deterministic release:

    with ALM(lavec, xcoord, numbers) as a:   # freed at block exit
        a.define(1, cutoff_radii=rc)
        a.suggest()
        patterns = a.get_displacement_patterns(1)
"""

from __future__ import annotations

import warnings
from collections import OrderedDict

import numpy as np

from . import _alm
from ._elements import element_symbol

# Legacy optimizer_control keys and their types (types of the C++
# OptimizerControl fields, alm/optimize.h).  Imported by phonopy's ALM
# interface to coerce user-supplied options; keep the names and order.
optimizer_control_data_types = OrderedDict(
    [
        ("linear_model", int),
        ("use_sparse_solver", int),
        ("maxnum_iteration", int),
        ("tolerance_iteration", float),
        ("output_frequency", int),
        ("standardize", int),
        ("displacement_normalization_factor", float),
        ("debiase_after_l1opt", int),
        ("cross_validation", int),
        ("l1_alpha", float),
        ("l1_alpha_min", float),
        ("l1_alpha_max", float),
        ("num_l1_alpha", int),
        ("l1_ratio", float),
        ("save_solution_path", int),
    ]
)


[docs] class ALM: """Pythonic wrapper around the nanobind ALMCore object (legacy-compatible API). Parameters ---------- lavec : array_like, shape (3, 3) Lattice vectors of the (super)cell in ``length_unit``; row i is the i-th vector. xcoord : array_like, shape (nat, 3) Fractional coordinates of the atoms. numbers : array_like, shape (nat,) Atomic numbers. verbosity : int 0 (silent, default) or 1 (print progress to stdout). length_unit : str Unit of the lattice vectors, displacements and cutoff radii passed to this object: 'bohr' (default) or 'angstrom'. Converted to Bohr internally. force_unit : str Unit of the forces passed to this object: 'Ry/bohr' (default), 'eV/angstrom' or 'Ha/bohr'. Converted to Ry/Bohr internally. symmetry_tolerance : float Tolerance (in ``length_unit``-independent fractional/Cartesian bohr units as in the CLI TOLERANCE tag) used by the symmetry finder (spglib), default 1e-3. Can be changed later through :attr:`symmetry_tolerance`. Notes ----- Assigning to :attr:`lavec`, :attr:`xcoord` or :attr:`numbers` re-sends the cell to the C++ core on the next :meth:`define` call; call :meth:`define` again after changing the structure. """ # Sparse solvers accepted by the 2.0 core (see alm/least_squares.cpp). _SPARSE_SOLVERS = ( "SimplicialLDLT", "SparseQR", "ConjugateGradient", "LeastSquaresConjugateGradient", "BiCGSTAB", "SuiteSparseQR", "CHOLMOD", ) # Output formats accepted by ALMCore.save_fc (see alm/writer.cpp). _SAVE_FORMATS = ( "alamode", "alamode_h5", "shengbte", "shengbte4", "qefc", "hessian", ) # Units accepted for the input data and the alamode_h5 output (see include/units.h). _LENGTH_UNITS = ("bohr", "angstrom") _FORCE_UNITS = ("Ry/bohr", "eV/angstrom", "Ha/bohr") _FC_OUTPUT_UNITS = ("Ry/bohr", "eV/angstrom") # Legacy optimizer_control key -> 2.0 field (kept for backward compatibility). _OC_ALIASES = {"mirror_image_conv": "periodic_image_conv"} @staticmethod def _canonical_unit(value, valid, name): value_lower = str(value).lower() for unit in valid: if value_lower == unit.lower(): return unit raise ValueError( f"{name} must be one of {valid} (case-insensitive), got {value!r}." ) def __init__( self, lavec, xcoord, numbers, verbosity: int = 0, length_unit: str = "bohr", force_unit: str = "Ry/bohr", symmetry_tolerance: float = 1.0e-3, ): self._core = None self._maxorder = 1 self._defined = False self._iconst = 0 self._patterns_ready = False self._supercell_active = False self._need_transfer = True self._need_data_transfer = False self._kind_names = OrderedDict() self._output_filename_prefix = None self._verbosity = verbosity self._symmetry_tolerance = float(symmetry_tolerance) self._length_unit = self._canonical_unit( length_unit, self._LENGTH_UNITS, "length_unit" ) self._force_unit = self._canonical_unit( force_unit, self._FORCE_UNITS, "force_unit" ) self._lavec = np.array(lavec, dtype="double", order="C") self._xcoord = np.array(xcoord, dtype="double", order="C") self._numbers = np.array(numbers, dtype="intc") self._u = None self._f = None # Create the underlying C++ instance right away so the object is usable # directly: a = ALM(lavec, xcoord, numbers). It is freed automatically # when ``a`` is garbage-collected, so 'with'/close() are optional # (they only make the release prompt/deterministic). self.alm_new() # ---- lifecycle / context manager ------------------------------------ def __enter__(self): # The instance already exists from __init__; recreate it only if the # user explicitly called close() before (re-)entering a 'with'. if self._core is None: self.alm_new() return self def __exit__(self, exc_type, exc_value, traceback): self.close() def __repr__(self): nat = len(self._numbers) nkd = np.unique(self._numbers).size if self._core is None: state = "closed" elif self._defined: state = f"defined, maxorder={self._maxorder}" else: state = "not defined" return f"<alm.ALM: {nat} atoms, {nkd} kinds ({state})>"
[docs] def alm_new(self): """Create the underlying C++ ALM instance. Called automatically by ``__init__``, so you normally never call this. It is idempotent (a no-op if the instance already exists) and may be used to recreate the instance after :meth:`close`. """ if self._core is not None: return self._core = _alm.ALMCore() self._algebraic_constraint = True # core default: ICONST = 11 self._core.set_verbosity(self._verbosity) # Always initialize the symmetry tolerance (the CLI does the same); # the core's System class has no usable default otherwise. self._core.set_symmetry_tolerance(self._symmetry_tolerance) # Must precede the transfers below: set_cell/set_u_train/set_f_train/ # define convert their input from these units to Bohr / Ry/Bohr. self._core.set_input_units(self._length_unit, self._force_unit) if self._output_filename_prefix is not None: self._core.set_output_filename_prefix(self._output_filename_prefix) # A freshly created native core has no cell/data yet, so always # (re-)send them. This matters when alm_new() recreates the instance # after close(): the transfer flags were cleared by the first transfer # and must be re-armed. self._need_transfer = True if self._u is not None and self._f is not None: self._need_data_transfer = True self._transfer_parameters()
[docs] def close(self): """Free the underlying C++ ALM instance immediately. Optional: the instance is also freed automatically when this object is garbage-collected. Call this (or use a ``with`` block) only when you want a prompt, deterministic release, e.g. inside a tight loop that builds many large sensing matrices. Idempotent; :meth:`alm_new` re-creates the instance. """ if self._core is None: return self._core = None self._defined = False self._patterns_ready = False self._supercell_active = False
[docs] def alm_delete(self): """Legacy alias for :meth:`close`.""" self.close()
def _check(self): if self._core is None: raise RuntimeError( "The C++ ALM instance has been released by close()/alm_delete(). " "Call alm_new() to re-create it, or construct a new ALM object." ) def _check_defined(self): if not self._defined: raise RuntimeError("define() must be called first.") def _check_fc_order(self, fc_order: int): if not (1 <= fc_order <= self._maxorder): raise ValueError( f"fc_order must be in [1 (harmonic), maxorder={self._maxorder}], " f"got {fc_order}." ) # ---- structure properties ------------------------------------------- @property def lavec(self) -> np.ndarray: """Lattice vectors of the (super)cell in :attr:`length_unit`, shape (3, 3); row i is the i-th vector. Assigning a new value re-sends the cell to the C++ core on the next :meth:`define` call.""" return np.array(self._lavec, dtype="double", order="C") @lavec.setter def lavec(self, lavec): self._need_transfer = True self._lavec = np.array(lavec, dtype="double", order="C") @property def xcoord(self) -> np.ndarray: """Fractional coordinates of the atoms, shape (nat, 3). Assigning a new value re-sends the cell to the C++ core on the next :meth:`define` call.""" return np.array(self._xcoord, dtype="double", order="C") @xcoord.setter def xcoord(self, xcoord): self._need_transfer = True self._xcoord = np.array(xcoord, dtype="double", order="C") @property def numbers(self) -> np.ndarray: """Atomic numbers of the atoms, shape (nat,). Assigning a new value re-sends the cell to the C++ core on the next :meth:`define` call.""" return np.array(self._numbers, dtype="intc") @numbers.setter def numbers(self, numbers): self._need_transfer = True self._numbers = np.array(numbers, dtype="intc") @property def kind_names(self) -> OrderedDict: """Atomic number -> element symbol for the kinds in the cell (a copy).""" return OrderedDict(self._kind_names) def _transfer_parameters(self): if self._need_transfer and self._core is not None: self._set_cell() self._need_transfer = False def _set_cell(self): nat = len(self._xcoord) if len(self._numbers) != nat: raise ValueError( f"len(numbers) = {len(self._numbers)} does not match the " f"number of atoms in xcoord ({nat})." ) self._kind_names = OrderedDict() for z in self._numbers: self._kind_names.setdefault(int(z), element_symbol(z)) z_list = list(self._kind_names.keys()) kind = np.array([z_list.index(int(z)) + 1 for z in self._numbers], dtype="intc") # The Python API takes the lattice vectors as ROWS (row i = i-th # vector); the C++ core stores them as COLUMNS (as the CLI &cell / # POSCAR parsers do), so transpose at the boundary. lavec_columns = np.ascontiguousarray(self._lavec.T, dtype="double") self._core.set_cell(lavec_columns, self._xcoord, kind) self._core.set_element_names(list(self._kind_names.values())) # Non-magnetic defaults (the CLI always sets these; required for correct symmetry). self._core.set_magnetic_params( np.zeros((nat, 3), dtype="double"), False, 0, 1, "" ) # ---- units ------------------------------------------------------------ @property def length_unit(self) -> str: """Unit of the lattice vectors, displacements and cutoff radii passed to this object ('bohr' or 'angstrom'; read-only, set at construction).""" return self._length_unit @property def force_unit(self) -> str: """Unit of the forces passed to this object ('Ry/bohr', 'eV/angstrom' or 'Ha/bohr'; read-only, set at construction).""" return self._force_unit # ---- symmetry tolerance --------------------------------------------- @property def symmetry_tolerance(self) -> float: """Tolerance of the symmetry finder (CLI TOLERANCE tag), default 1e-3.""" return self._symmetry_tolerance @symmetry_tolerance.setter def symmetry_tolerance(self, tol): self._symmetry_tolerance = float(tol) if self._core is not None: self._core.set_symmetry_tolerance(self._symmetry_tolerance) self._patterns_ready = False # ---- verbosity / output --------------------------------------------- @property def verbosity(self) -> int: """Verbosity level (0 = silent, 1 = print progress to stdout).""" return self._verbosity @verbosity.setter def verbosity(self, verbosity): self._verbosity = int(verbosity) if self._core is not None: self._core.set_verbosity(self._verbosity)
[docs] def set_verbosity(self, verbosity: int): """Set the verbosity level (same as assigning to :attr:`verbosity`).""" self.verbosity = verbosity
@property def output_filename_prefix(self): """Prefix of the files written by the C++ core (e.g. the ``.cvscore`` file of cross-validation); mirrors the CLI ``PREFIX`` tag.""" return self._output_filename_prefix @output_filename_prefix.setter def output_filename_prefix(self, prefix): if isinstance(prefix, str): self._output_filename_prefix = prefix if self._core is not None: self._core.set_output_filename_prefix(prefix) @property def cv_l1_alpha(self) -> float: """Optimal L1 alpha found by the last cross-validation run.""" self._check() return self._core.get_cv_l1_alpha()
[docs] def get_cv_l1_alpha(self) -> float: """Legacy alias for :attr:`cv_l1_alpha`.""" return self.cv_l1_alpha
# ---- model definition ------------------------------------------------
[docs] def define( self, maxorder: int, cutoff_radii=None, nbody=None, symmetrization_basis: str = "Cartesian", ): """Define the force-constant model (orders, cutoffs, interaction bodies). Parameters ---------- maxorder : int Highest fc_order to include: 1 = harmonic only, 2 = up to cubic, ... cutoff_radii : array_like, shape (maxorder, nkd, nkd), optional Interaction cutoff radius in :attr:`length_unit` per order and kind pair. A negative value means no cutoff (all pairs included); the default ``None`` applies no cutoff at any order. nbody : sequence of int, length maxorder, optional Maximum number of distinct atoms in a cluster per order. Default: 2, 3, 4, ... (i.e. no restriction). symmetrization_basis : {'Cartesian', 'Lattice'} Basis used to symmetrize the force constants (CLI FCSYM_BASIS). Default 'Cartesian' (changed from 'Lattice' in 2.0); rotational invariance requires 'Cartesian'. """ self._check() self._transfer_parameters() if maxorder < 1: raise ValueError(f"maxorder must be a positive integer, got {maxorder}.") nkd = len(self._kind_names) if nbody is None: nbody = [i + 2 for i in range(maxorder)] elif len(nbody) != maxorder: raise ValueError( f"len(nbody) = {len(nbody)} must equal maxorder = {maxorder}." ) if cutoff_radii is None: # Pass explicit -1 (= no cutoff) values instead of letting the C++ # side fall back to a nullptr: Cluster::define() re-allocates its # cutoff array without initializing it when given a nullptr, which # silently yields an (almost) empty interaction model. cut = np.full(maxorder * nkd * nkd, -1.0, dtype="double") else: cut = np.array(cutoff_radii, dtype="double", order="C").ravel() if cut.size != maxorder * nkd * nkd: raise ValueError( f"cutoff_radii must have shape (maxorder={maxorder}, " f"nkd={nkd}, nkd={nkd}), i.e. {maxorder * nkd * nkd} " f"elements in total; got {cut.size}." ) basis = str(symmetrization_basis).capitalize() if basis not in ("Lattice", "Cartesian"): raise ValueError( "symmetrization_basis must be 'Lattice' or 'Cartesian', " f"got {symmetrization_basis!r}." ) self._check_rotation_basis(self._iconst, basis) self._core.set_forceconstant_basis(basis) self._core.define(maxorder, nkd, np.array(nbody, dtype="intc"), cut) self._core.init_fc_table() self._maxorder = maxorder self._defined = True self._patterns_ready = False
[docs] def set_supercell( self, transmat_to_super, transmat_to_prim=None, autoset_primcell: bool = False ): """Declare the cell given to the constructor as the PRIMITIVE cell. The model is then built on the supercell obtained from ``transmat_to_super`` -- a (3, 3) integer matrix M with a_super = M a_prim. Mirrors the CLI STRUCTURE_FILE(primitive)+SUPERCELL setup. Call before :meth:`define`. """ self._check() ts = np.array(transmat_to_super, dtype="double", order="C").reshape(3, 3) tp = ( np.eye(3) if transmat_to_prim is None else np.array(transmat_to_prim, dtype="double", order="C").reshape(3, 3) ) self._core.set_periodicity(np.array([1, 1, 1], dtype="intc")) self._core.set_transformation_matrices(ts, tp, int(autoset_primcell)) # The supercell is generated inside the C++ core, so training-data # arrays are sized by the supercell, not by the constructor cell. self._supercell_active = True
[docs] def set_constraint( self, translation: bool = True, rotation: bool = False, rotation_axis: str = "xyz", iconst: int | None = None, stress=None, ): """Invariance constraints, imposed algebraically (CLI ICONST / ROTAXIS). ``translation=True`` gives ICONST=11 (acoustic sum rule); ``rotation=True`` gives ICONST=12 (translational plus rotational invariance about ``rotation_axis``, e.g. ``'xyz'`` or ``'z'``). ``iconst`` selects any CLI value directly (0-4, 11-14) and overrides ``translation`` and ``rotation``. Rotational invariance requires ``symmetrization_basis='Cartesian'`` (the default) in :meth:`define`. ``stress`` (CLI STRESS) is the Cauchy stress of the reference structure in GPa, tension positive, as a (3, 3) array or 6 Voigt values (xx, yy, zz, yz, xz, xy). It modifies the Huang invariance (``iconst`` 4 or 14) for a stressed reference; ``None`` (default) keeps the stress-free Huang conditions. """ self._check() if iconst is None: iconst = 12 if rotation else (11 if translation else 0) if iconst not in (0, 1, 2, 3, 4, 11, 12, 13, 14): raise ValueError(f"iconst must be 0-4 or 11-14, got {iconst}.") axis = "".join(sorted(str(rotation_axis).lower())) if axis not in ("x", "y", "z", "xy", "xz", "yz", "xyz"): raise ValueError( f"rotation_axis must be a combination of x, y, z, got {rotation_axis!r}." ) if self._core.constraints_initialized(): # The core builds the constraints once and would keep the old ones. raise RuntimeError( "set_constraint() must be called before the constraints are " "built (optimize, get_matrix_elements, get_fc, ...); create a " "new ALM object to change them." ) if self._defined: self._check_rotation_basis(iconst, self._core.get_forceconstant_basis()) self._iconst = iconst self._core.set_constraint_mode(iconst) self._core.set_algebraic_constraint(iconst // 10) self._core.set_rotation_axis(axis) if stress is None: self._core.set_stress([]) else: s = np.asarray(stress, dtype="double").ravel() if s.size == 6: s = s[[0, 5, 4, 5, 1, 3, 4, 3, 2]] if s.size != 9: raise ValueError("stress must be a (3, 3) array or 6 Voigt values.") if not np.all(np.isfinite(s)): raise ValueError("stress must be finite.") self._core.set_stress(s.tolist()) self._algebraic_constraint = bool(iconst // 10)
@staticmethod def _check_rotation_basis(iconst: int, basis: str): # The C++ core would terminate the interpreter on this combination. if iconst % 10 in (2, 3, 4) and basis != "Cartesian": raise ValueError( "Rotational invariance (ICONST 2-4, 12-14) requires " "define(..., symmetrization_basis='Cartesian')." ) # ---- fixing / freezing FCs ------------------------------------------
[docs] def fix_fc_from_file(self, fc_order: int, filename: str): """Fix the ``fc_order``-th FCs (1 = harmonic, 2 = cubic) to the values read from an ALM .xml/.h5 file. Mirrors the CLI FC2FIX/FC3FIX tags. Call before :meth:`define`. """ self._check() if fc_order not in (1, 2): raise ValueError( "fc_order must be 1 (harmonic) or 2 (cubic); fixing higher " f"orders from a file is not supported, got {fc_order}." ) self._core.set_fc_file(fc_order + 1, str(filename)) self._core.set_fc_fix(fc_order + 1, True)
[docs] def fix_force_constants_from_file(self, order: int, fc_file: str): """Legacy alias for :meth:`fix_fc_from_file` using the derivative-order convention (order = 2 harmonic, 3 cubic).""" self.fix_fc_from_file(int(order) - 1, fc_file)
[docs] def fix_fc(self, fc_values, fc_indices): """Fix a subset of FCs to given values during the fit (e.g. FC2 from a reference fit). Parameters ---------- fc_values : array_like, shape (n,) Force-constant values in Ry/Bohr^(fc_order+1). fc_indices : array_like, shape (n, fc_order+1) Flattened indices 3*atom + xyz of each FC element. """ self._check() fc_indices = np.array(fc_indices, dtype="intc", order="C") fc_values = np.array(fc_values, dtype="double") if fc_indices.ndim != 2: raise ValueError("fc_indices must be 2-dimensional.") if len(fc_indices) != len(fc_values): raise ValueError("fc_indices and fc_values must have the same length.") self._core.set_forceconstants_to_fix( [list(map(int, p)) for p in fc_indices], fc_values.tolist() )
[docs] def set_forceconstants_to_fix(self, intpair_fix, values_fix): """Legacy alias for :meth:`fix_fc` (note the swapped argument order).""" self.fix_fc(values_fix, intpair_fix)
[docs] def freeze_fc(self, fc_values, fc_indices): """Legacy alias for :meth:`fix_fc`.""" self.fix_fc(fc_values, fc_indices)
# ---- training / validation data ------------------------------------- def _as_data_array(self, data, name: str) -> np.ndarray: """Validate a displacement/force array: (nsnap, nat, 3) or (nsnap, 3*nat).""" arr = np.array(data, dtype="double", order="C") if self._supercell_active: # The supercell is built inside the C++ core, so its atom count is # not known here; check only the layout. if arr.ndim == 3 and arr.shape[2] == 3: return arr if arr.ndim == 2 and arr.shape[1] % 3 == 0: return arr raise ValueError( f"{name} must have shape (nsnap, nat_supercell, 3) or " f"(nsnap, 3*nat_supercell); got {arr.shape}." ) nat = len(self._numbers) if arr.ndim == 3: if arr.shape[1:] != (nat, 3): raise ValueError( f"{name} must have shape (nsnap, {nat}, 3) to match the " f"{nat}-atom cell; got {arr.shape}." ) elif arr.ndim == 2: if arr.shape[1] != 3 * nat: raise ValueError( f"{name} must have shape (nsnap, {3 * nat}) when 2-D; " f"got {arr.shape}." ) else: raise ValueError(f"{name} must be 2-D or 3-D, got ndim={arr.ndim}.") return arr def _transfer_training_data(self): """Push staged displacements/forces to the C++ core (no-op when up to date).""" if not self._need_data_transfer or self._core is None: return if self._u is None or self._f is None: raise RuntimeError( "both displacements and forces must be set before fitting; " "use set_training_data(u, f) or assign both properties." ) if self._u.shape != self._f.shape: raise ValueError( f"displacements {self._u.shape} and forces {self._f.shape} " "must have the same shape." ) nsnap = self._u.shape[0] self._core.set_u_train(self._u.reshape(nsnap, -1)) self._core.set_f_train(self._f.reshape(nsnap, -1)) self._need_data_transfer = False @property def displacements(self) -> np.ndarray: """Training displacements in :attr:`length_unit`, shape (nsnap, nat, 3).""" if self._u is None: raise RuntimeError("displacements have not been set.") return np.array(self._u, dtype="double", order="C") @displacements.setter def displacements(self, u): self._u = self._as_data_array(u, "displacements") self._need_data_transfer = True @property def forces(self) -> np.ndarray: """Training forces in :attr:`force_unit`, shape (nsnap, nat, 3).""" if self._f is None: raise RuntimeError("forces have not been set.") return np.array(self._f, dtype="double", order="C") @forces.setter def forces(self, f): self._f = self._as_data_array(f, "forces") self._need_data_transfer = True
[docs] def set_training_data(self, u, f): """Set the displacement-force training data. Parameters ---------- u : array_like, shape (nsnap, nat, 3) Atomic displacements in :attr:`length_unit`. f : array_like, shape (nsnap, nat, 3) Forces in :attr:`force_unit`. """ self._check() u = self._as_data_array(u, "u (displacements)") f = self._as_data_array(f, "f (forces)") if u.shape != f.shape: raise ValueError(f"u {u.shape} and f {f.shape} must have the same shape.") self._u, self._f = u, f self._need_data_transfer = True self._transfer_training_data()
[docs] def set_displacement_and_force(self, u, f): """Deprecated alias for :meth:`set_training_data`.""" warnings.warn( "set_displacement_and_force is deprecated; use set_training_data.", DeprecationWarning, stacklevel=2, ) self.set_training_data(u, f)
[docs] def set_validation_data(self, u, f): """Set the validation set used by cross-validation (same shapes/units as :meth:`set_training_data`).""" self._check() u = self._as_data_array(u, "u (displacements)") f = self._as_data_array(f, "f (forces)") if u.shape != f.shape: raise ValueError(f"u {u.shape} and f {f.shape} must have the same shape.") n = u.shape[0] self._core.set_validation_data(u.reshape(n, -1), f.reshape(n, -1))
# ---- optimizer control ---------------------------------------------- @property def optimizer_control(self) -> dict: """ALM's optimizer settings as a dict, mirroring the CLI ``&optimize`` tags (e.g. ``linear_model``, ``cross_validation``, ``l1_alpha``, ``l1_ratio``). Assign a dict with only the keys to change; unknown keys raise ``KeyError``. The legacy key ``mirror_image_conv`` is accepted as an alias of ``periodic_image_conv``.""" self._check() oc = self._core.get_optimizer_control() d = { k: getattr(oc, k) for k in dir(oc) if not k.startswith("_") and not callable(getattr(oc, k)) } # expose legacy aliases too for old, new in self._OC_ALIASES.items(): if new in d: d[old] = d[new] return d @optimizer_control.setter def optimizer_control(self, params): self.set_optimizer_control(params)
[docs] def set_optimizer_control(self, params: dict): """Update a subset of the optimizer settings (see :attr:`optimizer_control`).""" self._check() oc = self._core.get_optimizer_control() valid = sorted( k for k in dir(oc) if not k.startswith("_") and not callable(getattr(oc, k)) ) for k, v in params.items(): key = self._OC_ALIASES.get(k, k) if key not in valid: raise KeyError( f"unknown optimizer_control key: {k!r}; valid keys: {valid}" ) setattr(oc, key, v) self._core.set_optimizer_control(oc)
# ---- run -------------------------------------------------------------
[docs] def suggest(self): """Compute the displacement patterns needed to determine the FCs (retrieve them with :meth:`get_displacement_patterns`).""" self._check() self._check_defined() self._core.run_suggest() self._patterns_ready = True
[docs] def optimize(self, solver: str = "dense") -> int: """Fit the force constants to the training data. Parameters ---------- solver : str 'dense' (LAPACK) or one of the sparse solvers (case-insensitive): SimplicialLDLT, SparseQR, ConjugateGradient, LeastSquaresConjugateGradient, BiCGSTAB, SuiteSparseQR, CHOLMOD. Returns ------- int Solver info code (0 on success). Notes ----- With ``optimizer_control['cross_validation']`` set, this runs cross-validation instead of a single fit; the optimal alpha is then available as :attr:`cv_l1_alpha`. """ self._check() self._check_defined() self._transfer_training_data() if self._core.get_number_of_data() == 0: raise RuntimeError( "no training data; call set_training_data(u, f) (or assign the " "displacements/forces properties) before optimize()." ) # The free-parameter count is defined only for algebraic constraints: # ICONST >= 10, or any ICONST once linear_model >= 2 (Constraint::setup # then switches to algebraic). It is 0 for ICONST = 0 under OLS. # ponytail: no warning for an empty ICONST = 0 OLS model; needs a # core-side count of the numerical-constraint case. algebraic = ( self._algebraic_constraint or self._core.get_optimizer_control().linear_model >= 2 ) if algebraic and self._core.get_number_of_free_parameters() == 0: warnings.warn( "the model has no free FC parameters left after symmetry and " "constraint reduction; the fit will be empty. Check the " "structure and cutoff_radii.", stacklevel=2, ) canonical = {s.lower(): s for s in self._SPARSE_SOLVERS} oc = self._core.get_optimizer_control() if solver.lower() == "dense": oc.use_sparse_solver = 0 elif solver.lower() in canonical: oc.use_sparse_solver = 1 oc.sparsesolver = canonical[solver.lower()] else: raise ValueError( f"solver must be 'dense' or one of {self._SPARSE_SOLVERS}, " f"got {solver!r}." ) self._core.set_optimizer_control(oc) return self._core.run_optimize()
# ---- sensing matrix & force constants -------------------------------
[docs] def get_matrix_elements(self) -> tuple: """Return the sensing matrix and force vector (A, b) for external solvers. A has shape (nrows, n_free_parameters) in Fortran order, b shape (nrows,); the fitted parameters solve ``A @ x = b`` and can be injected back with :meth:`set_fc`. """ self._check() self._check_defined() self._transfer_training_data() if self._u is None or self._f is None: raise RuntimeError( "set training data via set_training_data() before get_matrix_elements()." ) amat, bvec, nrows, ncols = self._core.get_matrix_elements() return np.reshape(amat, (nrows, ncols), order="F"), bvec
[docs] def get_fc( self, fc_order: int, mode: str = "origin", permutation: bool = True ) -> tuple: """Return force constants as ``(values, elem_indices)``. Parameters ---------- fc_order : int 1 = harmonic (FC2), 2 = cubic (FC3), ... mode : {'origin', 'irreducible', 'all'} 'origin': FCs whose first atom sits in the primitive cell at the origin; 'irreducible': the symmetry-irreducible set; 'all': FCs expanded over every pure translation. permutation : bool Include index-permuted copies of each element. Returns ------- values : ndarray, shape (n,) Force constants in Ry/Bohr^(fc_order+1). elem_indices : ndarray, shape (n, fc_order+1) Flattened indices 3*atom + xyz of each element. Notes ----- The element ordering is not guaranteed to be stable across calls (it differs e.g. between optimize() and set_fc()); always pair ``values`` with ``elem_indices`` instead of relying on position. """ self._check() self._check_defined() self._check_fc_order(fc_order) perm = 1 if permutation else 0 if mode == "origin": v, idx = self._core.get_fc_origin(fc_order, perm) elif mode in ("irreducible", "irred"): v, idx = self._core.get_fc_irreducible(fc_order) elif mode == "all": v, idx = self._core.get_fc_all(fc_order, perm) else: raise ValueError( f"mode must be 'origin', 'irreducible', or 'all', got {mode!r}." ) return v, idx.reshape(-1, fc_order + 1)
[docs] def set_fc(self, fc_in): """Inject a free-parameter FC vector (e.g. from an external regressor fit to the matrix returned by :meth:`get_matrix_elements`).""" self._check() self._check_defined() fc_in = np.array(fc_in, dtype="double", order="C") n = self._core.get_number_of_free_parameters() if fc_in.size != n: raise ValueError(f"expected {n} free FCs, got {fc_in.size}.") self._core.set_fc(fc_in)
[docs] def get_number_of_free_parameters(self) -> int: """Number of free FC parameters after symmetry and constraint reduction; equals the column count of the matrix returned by :meth:`get_matrix_elements`.""" self._check() self._check_defined() return self._core.get_number_of_free_parameters()
[docs] def get_number_of_irred_fc_elements(self, fc_order: int) -> int: """Number of symmetry-irreducible FC elements of the given ``fc_order`` (1 = harmonic).""" self._check() self._check_defined() self._check_fc_order(fc_order) return self._core.get_number_of_irred_fc_elements(fc_order)
# ---- mappings & displacement patterns -------------------------------
[docs] def getmap_primitive_to_supercell(self) -> np.ndarray: """Return map_p2s, shape (num_trans, num_atoms_primitive) (legacy orientation).""" self._check() self._check_defined() # C++ returns (nat_primitive, num_trans); transpose to match the legacy API. m = np.array(self._core.get_atom_mapping_by_pure_translations(), dtype="intc") return m.T.copy()
[docs] def get_displacement_patterns(self, fc_order: int) -> list: """Return a list (per pattern) of ``(atom_index, direction(3,), basis)`` tuples; requires :meth:`suggest` to have run.""" self._check() self._check_defined() self._check_fc_order(fc_order) if not self._patterns_ready: raise RuntimeError("call suggest() before get_displacement_patterns().") numbers = self._core.get_number_of_displaced_atoms(fc_order) atom_indices, disp_flat, nbasis = self._core.get_displacement_patterns(fc_order) disp = np.reshape(disp_flat, (-1, 3)) if nbasis not in (0, 1): raise RuntimeError( f"ALM returned invalid displacement basis index {nbasis}" ) basis = ["Cartesian", "Fractional"][nbasis] all_disps, pos = [], 0 for num in numbers: disp_one = [] for _ in range(int(num)): disp_one.append((int(atom_indices[pos]), disp[pos], basis)) pos += 1 all_disps.append(disp_one) return all_disps
# ---- save ------------------------------------------------------------
[docs] def save_fc( self, filename: str, format: str = "alamode", maxorder_to_save: int = None, fc_unit: str = "Ry/bohr", ): """Write the force constants to a file. Parameters ---------- filename : str Output path. format : str 'alamode' (.xml), 'alamode_h5' (.h5, what anphon reads), 'shengbte', 'shengbte4', 'qefc', or 'hessian'. maxorder_to_save : int, optional Highest fc_order to write (default: all defined orders). fc_unit : str Unit system of the written file: 'Ry/bohr' (default) or 'eV/angstrom'. Only supported for format='alamode_h5', whose files carry the unit as metadata that anphon reads back; the other formats have fixed units (the .xml is always Ry/bohr^n). """ self._check() self._check_defined() fmt = str(format).lower() if fmt not in self._SAVE_FORMATS: raise ValueError( f"format must be one of {self._SAVE_FORMATS}, got {format!r}." ) fc_unit = self._canonical_unit(fc_unit, self._FC_OUTPUT_UNITS, "fc_unit") if fc_unit != "Ry/bohr" and fmt != "alamode_h5": raise ValueError( "fc_unit is only supported for format='alamode_h5'; the other " "formats have fixed units (the XML is always Ry/bohr^n)." ) if maxorder_to_save is None: maxorder_to_save = self._maxorder elif not (1 <= maxorder_to_save <= self._maxorder): raise ValueError( f"maxorder_to_save must be in [1, maxorder={self._maxorder}], " f"got {maxorder_to_save}." ) # fc_unit is passed on every call (defaults included) so the writer # state can never leak from a previous save. self._core.save_fc(str(filename), fmt, maxorder_to_save, fc_unit)