minelastic 0.1.0__py3-none-any.whl

minelastic/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Utkarsh Singh
+"""minelastic: second-order elastic constants from minimal uncoupled stress-strain calculations.
+
+The elastic constants C_ij = dsigma_i/de_j are obtained from finite differences of the stress of a few
+strained cells, with the minimal uncoupled strain sets of S. I. Simak and U. Singh, arXiv:2610.11733 (2026),
+for any crystal symmetry. Inputs are generated and outputs read for VASP, Quantum ESPRESSO, ABINIT, FHI-aims
+and any ASE format (generate, collect); ASE calculators are used directly (calculate).
+"""
+__version__ = "0.1.0"
+__url__ = "https://github.com/utksi/minelastic"
+
+from .core import ElasticResult, ElasticSetup  # noqa: E402
+from .calculator import calculate  # noqa: E402
+from .workflow import collect, generate  # noqa: E402
+
+__all__ = ["ElasticSetup", "ElasticResult", "calculate", "generate", "collect", "__version__"]

minelastic/algorithm.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Utkarsh Singh
+"""Minimal uncoupled strain sets (Simak and Singh): the paper's construction and an exhaustive search.
+
+A strain pattern is a vector u with support S (the Voigt components j with u_j != 0). Per unit step it
+produces the stresses s_i = sum_j C_ij u_j = sum_p c_p sum_{j in S} (B_p)_ij u_j (C = sum_p c_p B_p, see
+tensor_form). For generic amplitudes, s_i depends on constant p exactly when (B_p)_ij != 0 for some j in S.
+s_i is uncoupled if it depends on one constant only; that constant then follows from s_i alone. A set of
+patterns is complete if every constant is uncoupled in at least one of its stress components.
+
+paper_greedy is the iterative construction of the paper (Sec. III); exact_minimum searches all
+combinations of the 63 supports for the smallest complete set.
+"""
+from itertools import combinations, product
+
+import numpy as np
+
+_TOL = 1e-8
+
+
+def single_constant_rows(form, support):
+    """[(i, p)]: the stress components i that, for generic amplitudes on the support S, depend on exactly
+    one constant p, i.e. (B_q)_ij != 0 for some j in S only for q = p."""
+    out = []
+    for i in range(6):
+        involved = [p for p in range(form.n) if any(abs(form.basis[p, i, j]) > _TOL for j in support)]
+        if len(involved) == 1:
+            out.append((i, involved[0]))
+    return out
+
+
+def extractable(form, support):
+    """The set of constants p that are uncoupled in some stress component of a pattern on the support."""
+    return {p for _, p in single_constant_rows(form, support)}
+
+
+def reduced_auxiliary(form):
+    """Reduced auxiliary matrix of the paper (Sec. III B).
+
+    A_ij = 1 where C_ij is not identically zero, else 0. Row i is set to zero when the diagonal entry C_ii is
+    not +-1 times a single constant (a dependent diagonal such as C66 = (c11 - c12)/2), or when its constant
+    already appears on an earlier diagonal (an equivalent row, such as C22 = c11).
+    """
+    A = form.nonzero.astype(int)
+    seen = set()
+    for i in range(6):
+        d = form.entry(i, i)
+        nz = np.flatnonzero(np.abs(d) > _TOL)
+        if len(nz) != 1 or abs(abs(d[nz[0]]) - 1) > _TOL or nz[0] in seen:
+            A[i, :] = 0              # dependent diagonal (e.g. c66 = (c11-c12)/2) or equivalent to an earlier row
+        else:
+            seen.add(nz[0])
+    return A
+
+
+def paper_greedy(form):
+    """Strain supports from the iterative construction of the paper (Sec. III C).
+
+    Start from the reduced auxiliary matrix A and the candidate support b (b_j = 1 for the nonzero rows of A).
+    While some component of v = A b exceeds 1 (row i would respond to more than one strained component),
+    remove the highest such index j from b and zero row j. The remaining b is a pattern; its rows are removed
+    from A and from the candidates, and the procedure repeats until A is zero. Stops early, without a
+    complete set, when no component survives (possible in a non-standard frame); the caller then uses
+    exact_minimum.
+    """
+    A = reduced_auxiliary(form)
+    b_in = (A.sum(axis=1) > 0).astype(int)
+    supports = []
+    while A.any():
+        At, b = A.copy(), b_in.copy()
+        while True:
+            v = At @ b
+            bad = np.flatnonzero(v > 1)
+            if bad.size == 0:
+                break
+            j = bad.max()
+            b[j] = 0
+            At[j, :] = 0
+        if not b.any():
+            break                    # no progress possible (non-standard frame); caller falls back
+        supports.append(tuple(int(j) for j in np.flatnonzero(b)))
+        A[b == 1, :] = 0
+        b_in[b == 1] = 0
+    return supports
+
+
+def covers(form, supports):
+    """True if the union of extractable(S) over the supports contains every constant."""
+    got = set()
+    for s in supports:
+        got |= extractable(form, s)
+    return got == set(range(form.n))
+
+
+def exact_minimum(form, max_patterns=6):
+    """A complete set of supports of minimum size, by exhaustive search.
+
+    Each of the 63 nonempty supports S is assigned X(S) = extractable(S). A support is dropped if another
+    support S2 has X(S) a subset of X(S2) and no more components (one of equal ones is kept). For
+    k = 1, 2, ..., max_patterns all
+    k-combinations are tested for complete coverage; among those of the smallest k, the one with the
+    fewest strained components in total (least symmetry lowering, then lexicographic) is returned.
+    """
+    target = set(range(form.n))
+    X = {}
+    for mask in range(1, 64):
+        s = tuple(j for j in range(6) if mask >> j & 1)
+        e = frozenset(extractable(form, s))
+        if e:
+            X[s] = e
+    # WHY: a support is never needed if another one extracts at least the same constants with no more strained
+    #      components (dropping only such supports keeps both the count and the tie-break exact)
+    order = sorted(X, key=lambda s: (len(s), s))
+    cands = [s for n, s in enumerate(order)
+             if not any(X[s] <= X[s2] and len(s2) <= len(s) and (X[s] < X[s2] or len(s2) < len(s) or m < n)
+                        for m, s2 in enumerate(order) if s2 != s)]
+    for k in range(1, max_patterns + 1):
+        best = None
+        for combo in combinations(cands, k):
+            if set().union(*(X[s] for s in combo)) == target:
+                key = (sum(len(s) for s in combo), combo)
+                if best is None or key < best[0]:
+                    best = (key, combo)
+        if best is not None:
+            return list(best[1])
+    raise RuntimeError("no complete set of uncoupled strain patterns exists")
+
+
+def choose_amplitudes(form, support):
+    """Pattern u on the support, first component 1, with every single-constant coefficient (B_p)_i . u nonzero.
+
+    For generic amplitudes each single-constant row (i, p) has a nonzero coefficient, but special amplitudes
+    can cancel it (e.g. c16 (u_1 - u_2) for u_1 = u_2). Amplitudes +-1 are tried first (all positive first),
+    then +-1 and +-2. RuntimeError if none keeps all relations.
+    """
+    rows = single_constant_rows(form, support)
+    for values in ((1.0, -1.0), (1.0, -1.0, 2.0, -2.0)):
+        for amps in product(values, repeat=len(support) - 1):
+            u = np.zeros(6)
+            u[list(support)] = (1.0,) + amps
+            if all(abs(form.basis[p, i] @ u) > _TOL for i, p in rows):
+                return u
+    raise RuntimeError(f"no amplitudes on support {support} keep all single-constant relations")
+
+
+def relations(form, pattern):
+    """The six relations s_i = sum_p a_ip c_p of a pattern u (per unit step), a_ip = (B_p)_i . u.
+
+    One dict per row i: row, coef = (a_ip)_p, and kind 'zero' (all a_ip = 0), 'single' (one nonzero a_ip;
+    then also constant = p and factor = a_ip, so that s_i = factor * c_p) or 'coupled'.
+    """
+    u = np.asarray(pattern, float)
+    out = []
+    for i in range(6):
+        a = form.basis[:, i, :] @ u
+        nz = np.flatnonzero(np.abs(a) > _TOL)
+        if nz.size == 0:
+            out.append(dict(row=i, kind="zero", coef=a))
+        elif nz.size == 1:
+            out.append(dict(row=i, kind="single", coef=a, constant=int(nz[0]), factor=float(a[nz[0]])))
+        else:
+            out.append(dict(row=i, kind="coupled", coef=a))
+    return out

minelastic/calculator.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Utkarsh Singh
+"""Elastic constants with an ASE calculator: every state of an ElasticSetup computed in memory.
+
+ASE returns the stress in eV/A^3, tension positive, Voigt order xx yy zz yz xz xy; it is converted to GPa
+(x 160.2177) and passed to ElasticSetup.compute with the forces of the clamped cells and, if a dipole function
+is given, the dipole moment of every cell.
+"""
+import numpy as np
+
+from .core import ElasticSetup
+
+EV_PER_A3_IN_GPA = 160.21766208
+
+
+def calculate(atoms, calc, relax_ions=False, method="uncoupled", fmax=1e-4, steps=500, optimizer=None,
+              dipole=None, **setup_kwargs):
+    """Elastic tensor of atoms from the stresses of every strained cell, computed with an ASE calculator.
+
+    Builds ElasticSetup(atoms, **setup_kwargs), computes the stress (eV/A^3 from calc, converted to GPa,
+    tension positive) and the forces (eV/A) of every state with calc, and returns ElasticSetup.compute of them.
+
+    Parameters
+    ----------
+    atoms : ase.Atoms
+        Reference structure, relaxed and stress-free for the textbook constants.
+    calc : ase calculator
+        Calculator that returns the stress; it is attached to every strained cell.
+    relax_ions : bool
+        Relax the atoms of each strained cell at fixed cell (optimizer, default BFGS, to fmax eV/A within steps
+        steps); the constants are then the relaxed-ion constants and no forces are passed on. Otherwise the
+        cells are clamped and their forces give the internal-strain tensor.
+    method : str
+        Extraction method of ElasticSetup.compute: 'uncoupled', 'designated' or 'lstsq'.
+    fmax, steps, optimizer :
+        Convergence (eV/A), step limit and ASE optimizer class of the relaxations.
+    dipole : callable, optional
+        Function of an Atoms object (calculator attached, after any relaxation) that returns the dipole moment
+        of the cell in e*Angstrom, physical sign. It gives the piezoelectric tensor e = dP/de (clamped-ion for
+        clamped cells, relaxed-ion with relax_ions) and, with ionic=True, the Born charges, the total e and d.
+    **setup_kwargs :
+        Options of ElasticSetup: scheme, delta, stencil, symprec, frame, ionic, displacement.
+
+    Returns
+    -------
+    ElasticResult
+        With ionic=True, result.C_relaxed is the relaxed-ion stiffness from the clamped cells and the
+        displacements.
+    """
+    setup = ElasticSetup(atoms, **setup_kwargs)
+    if relax_ions and setup.ionic:
+        raise ValueError("ionic=True gives the relaxed-ion constants from clamped cells; do not combine it with "
+                         "relax_ions=True")
+    stresses, forces, dipoles = {}, {}, {}
+    for st in setup.states:
+        at = setup.strained_atoms(st)
+        at.calc = calc
+        if relax_ions:
+            from ase.optimize import BFGS
+            (optimizer or BFGS)(at, logfile=None).run(fmax=fmax, steps=steps)
+        # ASE stress: eV/A^3, xx yy zz yz xz xy, positive in tension
+        stresses[st["id"]] = at.get_stress(voigt=True) * EV_PER_A3_IN_GPA
+        forces[st["id"]] = at.get_forces()
+        if dipole is not None:
+            dipoles[st["id"]] = np.asarray(dipole(at), float)
+    return setup.compute(stresses, forces=None if relax_ions else forces, method=method,
+                         polarization=dipoles if dipole is not None else None)

minelastic/cli.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Utkarsh Singh
+"""Command line interface: minelastic info | generate | collect | vasp-tensor.
+
+info prints the symmetry, tensor form and strain set of a structure; generate and collect call
+workflow.generate and workflow.collect; vasp-tensor converts a tensor printed by VASP (IBRION = 6) to GPa in
+Voigt order and adds the Born stability check and the Voigt-Reuss-Hill moduli.
+"""
+import argparse
+import json
+import sys
+
+import numpy as np
+
+from . import __version__
+from .core import ElasticSetup
+from .properties import born_stable, vrh
+from .workflow import CODES, collect, generate, read_structure
+
+
+def _common(p):
+    """Options of the strain set shared by info and generate."""
+    p.add_argument("--scheme", default="minimal", choices=["minimal", "asess"],
+                   help="minimal uncoupled set (default) or the six single-component strains")
+    p.add_argument("--delta", type=float, default=0.01, help="strain step (default 0.01)")
+    p.add_argument("--stencil", default=None, choices=["central", "four-point", "forward"],
+                   help="finite differences: four-point (default; -2, -1, 1, 2 steps) or central (+-1 step; the "
+                        "default with --md) or forward")
+    p.add_argument("--symprec", type=float, default=1e-5, help="spglib tolerance in Angstrom")
+    p.add_argument("--frame", default="auto", choices=["auto", "input", "standard"],
+                   help="orientation in which the strains are applied (default: input if it is standard)")
+
+
+def main(argv=None):
+    """Parse the command line and run the subcommand; returns the exit status 0."""
+    ap = argparse.ArgumentParser(
+        prog="minelastic", epilog="Documentation: https://utksi.github.io/minelastic/",
+        description="Elastic constants from the minimal uncoupled stress-strain sets. info shows the symmetry and "
+                    "the strain set of a structure, generate writes the inputs of the strained cells, collect reads "
+                    "the finished calculations and prints the elastic tensor, and vasp-tensor analyses the tensor "
+                    "that VASP prints for IBRION = 6.")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("info", help="symmetry, tensor form and strain set of a structure")
+    p.add_argument("structure")
+    p.add_argument("--code", default="generic", choices=sorted(CODES),
+                   help="how to read the structure (template dir for vasp/aims/abinit, pw.in for qe)")
+    p.add_argument("--format", default=None, help="ASE format for --code generic")
+    _common(p)
+
+    p = sub.add_parser("generate", help="write the strained inputs")
+    p.add_argument("code", choices=sorted(CODES))
+    p.add_argument("template", help="vasp/aims/abinit: directory with the reference inputs; qe: pw.x input; "
+                                    "generic: structure file")
+    p.add_argument("-o", "--out", default="elastic", help="output directory (default ./elastic)")
+    p.add_argument("--relax-ions", action="store_true", help="relax the ions in each strained cell")
+    p.add_argument("--format", default=None, help="generic: ASE format of the structure files")
+    p.add_argument("--filename", default=None, help="generic: name of the structure file in each directory")
+    p.add_argument("--extra", nargs="*", default=(), help="generic: further files copied into each directory")
+    p.add_argument("--potcar", default="copy", choices=["copy", "link"], help="vasp: copy or symlink POTCAR")
+    p.add_argument("--fix-incar", action="store_true",
+                   help="vasp: apply all recommended settings that the INCAR does not meet (EDIFF, ENCUT, PREC, "
+                        "LREAL); without it they are only reported")
+    p.add_argument("--ionic", action="store_true",
+                   help="also displace the symmetry-irreducible atoms (relaxed-ion tensors, Born charges and "
+                        "piezoelectric response from clamped cells, as VASP IBRION=6)")
+    p.add_argument("--displacement", type=float, default=0.01, help="--ionic: atomic step in Angstrom")
+    p.add_argument("--md", action="store_true",
+                   help="finite T: fixed-cell molecular dynamics in each strained cell, as set up in the template "
+                        "(vasp: IBRION = 0; qe: calculation = 'md')")
+    _common(p)
+
+    p = sub.add_parser("collect", help="elastic constants from the finished calculations")
+    p.add_argument("directory", nargs="?", default="elastic")
+    p.add_argument("--method", default="uncoupled", choices=["uncoupled", "designated", "lstsq"])
+    p.add_argument("--output", default=None, help="name of the output file in each directory")
+    p.add_argument("--format", default=None, help="generic: ASE format of the output file")
+    p.add_argument("--md", action="store_true", help="average the stress over the ionic steps (finite T)")
+    p.add_argument("--skip", type=int, default=0, help="--md: steps discarded for equilibration")
+    p.add_argument("--samples", default=None,
+                   help="glob of per-snapshot sub-directories in each state directory (e.g. 'conf-*'); "
+                        "their stresses are averaged")
+    p.add_argument("--kinetic-temperature", type=float, default=None,
+                   help="add the ideal-gas term n kB T (stresses without kinetic part, e.g. VASP MD)")
+    p.add_argument("--internal-strain", action="store_true", help="print the internal strain tensor")
+    p.add_argument("--piezo", action="store_true",
+                   help="piezoelectric tensor from the Berry-phase dipoles of the strained cells (VASP LCALCPOL)")
+    p.add_argument("--born", default=None, metavar="OUTCAR",
+                   help="Born charges and clamped-ion piezoelectric tensor from a VASP LEPSILON/LCALCEPS run of "
+                        "the reference structure (with --ionic data)")
+    p.add_argument("--stress-measure", default="cauchy", choices=["cauchy", "kirchhoff"],
+                   help="differentiate the Cauchy stress (default) or J*sigma (as VASP IBRION=6)")
+
+    p = sub.add_parser("vasp-tensor", help="analyse the elastic tensor printed by VASP IBRION=6")
+    p.add_argument("outcar")
+    p.add_argument("--which", default="total", choices=["total", "clamped", "ionic"])
+
+    a = ap.parse_args(argv)
+    kw = dict(scheme=a.scheme, delta=a.delta, stencil=a.stencil, symprec=a.symprec, frame=a.frame) \
+        if a.cmd in ("info", "generate") else {}
+
+    if a.cmd == "info":
+        atoms = read_structure(a.code, a.structure, a.format)
+        print(ElasticSetup(atoms, **{**kw, "stencil": a.stencil or "four-point"}).describe())
+    elif a.cmd == "generate":
+        if a.fix_incar and a.code != "vasp":
+            ap.error("--fix-incar is for vasp")
+        extra = dict(potcar=a.potcar, fix_incar=a.fix_incar) if a.code == "vasp" else {}
+        setup, notes = generate(a.code, a.template, a.out, relax_ions=a.relax_ions, fmt=a.format,
+                                filename=a.filename, extra_files=a.extra, ionic=a.ionic,
+                                displacement=a.displacement, md=a.md, **kw, **extra)
+        print(setup.describe())
+        print(f"\n{len(setup.states)} calculations written to {a.out}/ (list in {a.out}/STATES)")
+        for n in notes:
+            print("NOTE:", n)
+    elif a.cmd == "collect":
+        r = collect(a.directory, method=a.method, output=a.output, fmt=a.format, md=a.md, skip=a.skip,
+                    kinetic_temperature=a.kinetic_temperature, samples=a.samples,
+                    stress_measure=a.stress_measure, polarization=a.piezo, born_file=a.born)
+        print(r.summary())
+        if a.internal_strain and r.internal_strain is not None:
+            print("internal strain tensor dF/de (eV/A), columns xx yy zz yz xz xy:")
+            for n, L in enumerate(r.internal_strain):
+                for i, ax in enumerate("xyz"):
+                    print(f"  ion {n + 1:3d} {ax} " + " ".join(f"{v:10.4f}" for v in L[i]))
+        print(f"\nwritten {a.directory}/elastic.json")
+    elif a.cmd == "vasp-tensor":
+        from .io.vasp import read_elastic_tensor
+        which = {"total": "TOTAL ELASTIC MODULI", "clamped": "SYMMETRIZED ELASTIC MODULI",
+                 "ionic": "ELASTIC MODULI CONTR FROM IONIC RELAXATION"}[a.which]
+        C = read_elastic_tensor(a.outcar, which)
+        print(f"{which} (GPa, Voigt xx yy zz yz xz xy):")
+        for row in C:
+            print("  " + " ".join(f"{v:9.2f}" for v in row))
+        if a.which != "ionic":
+            stable, ev = born_stable(C)
+            print(f"Born stable: {stable}")
+            if stable:
+                print(json.dumps({k: round(v, 3) for k, v in vrh(C).items()}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())