"""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