Source code for diffuse.crystal

"""Reading structures into DISCUS."""

from __future__ import annotations

import os
import shutil
from dataclasses import dataclass, field
from pathlib import Path

import numpy as np

from ._session import DiffuseError, session

# Files that DISCUS reads as an asymmetric unit (then applies the space
# group and builds the supercell) and files it reads as a whole crystal.
_CELL_SUFFIXES = {".cell", ".cif"}
_STRU_SUFFIXES = {".stru"}


[docs] @dataclass(eq=False) class Crystal: """A structure loaded into DISCUS. Create it with :func:`read_structure`. DISCUS holds one structure at a time. A ``Crystal`` remembers how it was made, so a calculation on an older ``Crystal`` reads it in again first. Attributes ---------- path : pathlib.Path The structure file it was read from. supercell : tuple of int or None Number of unit cells along a, b and c, or None for a ``.stru`` file read as it is. natoms : int Number of atoms in the whole crystal. lattice : tuple of float ``(a, b, c, alpha, beta, gamma)`` in Å and degrees. """ path: Path supercell: tuple[int, int, int] | None natoms: int lattice: tuple[float, float, float, float, float, float] # a, b, c, alpha, beta, gamma _atoms: tuple[np.ndarray, np.ndarray] | None = field(default=None, repr=False) @property def a(self) -> float: """Lattice parameter a in Å.""" return self.lattice[0] @property def volume(self) -> float: """Volume of one unit cell in Å^3.""" a, b, c, al, be, ga = self.lattice ca, cb, cg = np.cos(np.radians([al, be, ga])) return float(a * b * c * np.sqrt(1 - ca**2 - cb**2 - cg**2 + 2 * ca * cb * cg))
[docs] def atoms(self) -> tuple[np.ndarray, np.ndarray]: """Atom names and fractional coordinates. Returns ------- names : numpy.ndarray of str, shape (natoms,) Atom names as DISCUS uses them, for example ``"TI4+"``. xyz : numpy.ndarray of float, shape (natoms, 3) Fractional coordinates in units of the unit cell. Notes ----- DISCUS saves the crystal to a ``.stru`` file, which is read back. The result is cached on the ``Crystal``. """ if self._atoms is None: _ensure_loaded(self) s = session() out = s.workdir / "atoms.stru" out.unlink(missing_ok=True) s.run(f"discus\n save\n outfile {out.name}\n write all\n run\n exit\nexit", cwd=s.workdir) lines = out.read_text().splitlines() names, xyz = _parse_stru_atoms(lines) if len(names) != self.natoms: raise DiffuseError(f"saved structure has {len(names)} atoms, expected {self.natoms}") self._atoms = (names, xyz) return self._atoms
[docs] def positions(self) -> np.ndarray: """Fractional coordinates, shape (natoms, 3). See :meth:`atoms`.""" return self.atoms()[1]
def __repr__(self) -> str: cell = ", ".join(f"{v:g}" for v in self.lattice) sc = f", supercell={self.supercell}" if self.supercell else "" return f"Crystal('{self.path.name}'{sc}, natoms={self.natoms}, lattice=({cell}))"
def _parse_stru_atoms(lines: list[str]) -> tuple[np.ndarray, np.ndarray]: """Atom names and coordinates from the atom section of a saved .stru file. The section can contain ``molecule ...`` blocks between the atom lines; an atom line is a name followed by three numbers. """ start = next(i for i, line in enumerate(lines) if line.split()[:1] == ["atoms"]) + 1 names, xyz = [], [] for line in lines[start:]: words = line.replace(",", " ").split() if len(words) < 4 or words[0].lower() == "molecule": continue try: coords = [float(v) for v in words[1:4]] except ValueError: continue names.append(words[0]) xyz.append(coords) return np.array(names), np.array(xyz, dtype=float).reshape(-1, 3)
[docs] def read_structure(path: str | os.PathLike, supercell: tuple[int, int, int] | int | None = None) -> Crystal: """Read a structure file into DISCUS. Parameters ---------- path : str or os.PathLike A ``.cif`` or ``.cell`` file (an asymmetric unit: DISCUS applies the space group) or a ``.stru`` file (a whole crystal). supercell : int or tuple of 3 int, optional Number of unit cells along a, b and c; an int means the same along all three. Default: 1 x 1 x 1 for ``.cif``/``.cell``, and a ``.stru`` file is read as it is. Returns ------- Crystal The structure, now held by DISCUS. Raises ------ FileNotFoundError If ``path`` does not exist. DiffuseError If the file type is not supported. MacroError If DISCUS cannot read the file. Examples -------- >>> import diffuse as dc >>> cr = dc.read_structure("anatase.cif", supercell=(10, 10, 4)) # doctest: +SKIP >>> cr.natoms # doctest: +SKIP 4800 """ path = Path(path).expanduser().resolve() if not path.is_file(): raise FileNotFoundError(path) suffix = path.suffix.lower() if suffix not in _CELL_SUFFIXES | _STRU_SUFFIXES: raise DiffuseError(f"unsupported structure file '{path.name}' " f"(use {', '.join(sorted(_CELL_SUFFIXES | _STRU_SUFFIXES))})") if isinstance(supercell, int): supercell = (supercell,) * 3 if supercell is not None: supercell = tuple(int(n) for n in supercell) if len(supercell) != 3 or min(supercell) < 1: raise ValueError(f"supercell must be three positive integers, not {supercell}") if suffix in _STRU_SUFFIXES and supercell is None: command = f"stru {path.name}" else: nx, ny, nz = supercell or (1, 1, 1) command = f"cell {path.name}, {nx}, {ny}, {nz}" # DISCUS may write files next to the input (a CIF is converted to .stru # first), so read a copy in the session's scratch folder. s = session() inputs = s.workdir / "input" shutil.rmtree(inputs, ignore_errors=True) inputs.mkdir() shutil.copy(path, inputs / ("structure" + suffix)) command = command.replace(path.name, "structure" + suffix, 1) # n[] and lat[] exist only inside the discus section: copy them to the # r[] entries reserved for this package (r[490] ... r[498]). s.run(f""" discus read {command} r[490] = n[1] r[491] = lat[1] r[492] = lat[2] r[493] = lat[3] r[494] = lat[4] r[495] = lat[5] r[496] = lat[6] exit """, cwd=inputs) crystal = Crystal( path=path, supercell=supercell, natoms=int(s.value("r[490]")), lattice=tuple(s.value(f"r[{i}]") for i in range(491, 497)), ) s.current_crystal = crystal return crystal
def _ensure_loaded(crystal: Crystal) -> None: """Make ``crystal`` the structure DISCUS holds, reading it again if needed.""" s = session() if s.current_crystal is crystal: return fresh = read_structure(crystal.path, crystal.supercell) if fresh.natoms != crystal.natoms: raise DiffuseError(f"{crystal.path.name} now gives {fresh.natoms} atoms, " f"not {crystal.natoms}; has the file changed?") s.current_crystal = crystal