diff --git a/interfaces/ASE_interface/README.md b/interfaces/ASE_interface/README.md index 543d4774836..b7288decb9c 100644 --- a/interfaces/ASE_interface/README.md +++ b/interfaces/ASE_interface/README.md @@ -7,7 +7,7 @@ abacuslite is a lightweight plugin for ABACUS (Atomic-orbital Based Ab-initio Co ### Key Features - **Lightweight Design**: Implemented as a plugin, no need to modify ASE core code -- **Version Compatibility**: Supports ASE versions satisfying the package requirement `ase>=3.22` +- **Version Compatibility**: Requires `ase>=3.23`, because ASE 3.22 lacks `ase.calculators.genericfileio`, which this plugin imports - **ASE Integration**: Uses ASE as the running platform, making ABACUS a callable calculator within it - **Function Support**: Provides SCF-based energy, force, and stress evaluations through ASE. ASE can use these evaluations for relaxation, molecular dynamics, NEB, band-structure, and density-of-states workflows. - **Socket Support**: `AbacusSocketIO` provides fixed-cell i-PI socket calculations, with energy always available and forces/stress enabled independently when requested. @@ -39,6 +39,45 @@ Please refer to the example scripts in the `examples` folder. Recommended learni The regular `Abacus` calculator runs one ABACUS calculation for each ASE property evaluation. ASE controls the relaxation, molecular-dynamics, and other workflow steps. The socket calculator reuses one ABACUS process for position updates, while the cell and electronic-structure settings remain fixed for that calculator instance. +## Result collection + +The ASE calculator uses the final parsed frame for SCF, native relaxation, and +native MD. The readers restore ASE atom order using the mapping created when +the calculator writes STRU. The legacy reader can use MD_dump when present, +and the develop reader reads native MD from MD_dump. Each calculator retains +its own LTS/develop reader. + +Both output readers accept paths or named text streams, using the log filename +to locate companion output files. Caller-owned streams remain open and are read +from their current position; seek to the start before rereading. Returned ASE +positions and cells are Cartesian Angstrom values, with Direct and alat +conversions applied once by the reader. Raw trajectory dictionaries retain +their file-native conventions. + +Returned structures represent the simulation box with periodic boundaries in +all directions, including molecules in vacuum and slabs. This changes earlier +SCF output flags; readers do not infer physical isolation from vacuum thickness. +For nonperiodic geometry analysis, make a copy and explicitly set its `pbc` +flags; this does not change the completed calculation's boundary conditions. + +Result parsing does **not read abacus.json**. Missing or malformed JSON does not +affect collection. Writing new input leaves existing JSON files untouched. + +Both ASE `energy` and `free_energy` retain ABACUS's force-consistent +`E_KohnSham`. When an entropy term is present, `energy_without_entropy` is +provided separately; a missing term remains unknown. Noncollinear vector +moments are retained without modifying ASE's global property definitions. +STRU writing preserves representable species masses and converts ASE +velocities to atomic units. Different masses within one ABACUS species are +rejected because one species entry cannot represent them. + +The existing inline tests (`abacuslite/xtest.sh`) and engine integration tests +(`tests/xtest.sh`) are run by the ASE plugin workflow. Standalone offline +regressions and recorded output fixtures are maintained in +[QuantumMisaka/abacuslite](https://github.com/QuantumMisaka/abacuslite). +The calculator and parser corrections were adapted from standalone revisions +`39ab1d5` and `5d3da5d`, with follow-up ASE compatibility fixes. + ## Authors - Yuyang Ji diff --git a/interfaces/ASE_interface/abacuslite/core.py b/interfaces/ASE_interface/abacuslite/core.py index 9d23159ea25..01206210cf0 100644 --- a/interfaces/ASE_interface/abacuslite/core.py +++ b/interfaces/ASE_interface/abacuslite/core.py @@ -1,8 +1,7 @@ # fmt: off ''' -here the ase-abacus implementation is pasted and modified. -Source: +Adapted from the ase-abacus implementation: https://gitlab.com/1041176461/ase-abacus/-/blob/master/ase/calculators/abacus.py This module defines an ASE interface to ABACUS. @@ -26,7 +25,7 @@ Modified on Wed Jun 03 23:00:00 2022 @author: Ji Yu-yang -Refactored from Sun Dec 07 21:41 2025 +Refactored on 2025-12-07 @author: Huang Yi-ke ''' @@ -36,6 +35,7 @@ import shutil import tempfile import unittest +from copy import copy from pathlib import Path from typing import Dict, Optional, List @@ -52,38 +52,60 @@ from ase.io import read from abacuslite.io.generalio import ( + _write_ase_stru, + _write_kpt, file_safe_backup, read_input, read_stru, read_kpt, species_group_indices, write_input, - write_stru, - write_kpt ) __LEGACYIO__ = True +SOCKET_METADATA_SCHEMA = 'abacus.socket.properties.v1' + + +def _schema_compatible_properties(results): + """Project calculator results through ASE's installed Properties schema.""" + from ase.calculators.calculator import Properties, all_outputs + + exported = {} + for name, value in results.items(): + if name not in all_outputs: + continue + candidate = {**exported, name: value} + try: + Properties(candidate) + except (KeyError, TypeError, ValueError): + continue + exported[name] = value + return Properties(exported) + + +def _uses_legacy_io(version: str) -> bool: + """Resolve a format without mutating another calculator's reader.""" + match = re.match( + r'^v(\d+)\.(\d+)\.(\d+)(\.\d+|-(alpha|beta|rc)\.?\d+)?(?:\+[A-Za-z0-9.-]+)?$', + version, + ) + assert match, f'Invalid ABACUS version: {version}' + assert int(match.group(1)) >= 3, 'ABACUS v2.x is not supported' + minor = int(match.group(2)) + return not (minor >= 11 or (minor == 9 and match.group(4) is not None)) + + def switch_io_backend_version(version: str) -> bool: - '''determine if the i/o is in legacy format by the version number, - for detailed discussion, see issue #7260 - ''' + """Set the compatibility default for subsequently created templates. + + Existing calculators retain the format selected from their own profile. + Explicit io.legacyio/io.latestio functions are unaffected by this helper. + """ global __LEGACYIO__ - m = re.match(r'^v(\d+)\.(\d+)\.(\d+)(\.\d+|\-(alpha|beta|rc)\.\d+|\-(alpha|beta|rc)\d+)?$', version) - assert m, f'Invalid format of version number, please check file version.h' - assert int(m.group(1)) >= 3, f'ABACUS v2.x is not supported' - if int(m.group(2)) >= 11: - __LEGACYIO__ = False - elif int(m.group(2)) == 9: - if m.group(4) is not None: - # it is also possible to divide the version more carefully, - # but because 3.9.0.x are all on the develop branch, up to - # now, there is no user submit issue to request such a careful - # division - __LEGACYIO__ = False - else: - __LEGACYIO__ = True + __LEGACYIO__ = _uses_legacy_io(version) return __LEGACYIO__ + class AbacusProfile(BaseProfile): '''AbacusProfile for interacting the ASE with ABACUS that installed in the practical system''' @@ -105,10 +127,14 @@ def __init__(self, `OMP_NUM_THREADS=1 mpirun -np X abacus`. Here please do not set the number of omp threads in `command`, instead, use `nomp=1`. pseudo_dir : str or Path, optional - The directory containing pseudopotential files. + The directory containing pseudopotential files. If ``None`` (the + default), ``ABACUS_PP_PATH`` is used when set; an explicit value, + including an empty string, is preserved. orbital_dir : str or Path, optional The directory containing orbital basis files. This is only necessary - for an ABACUS-LCAO calculation + for an ABACUS-LCAO calculation. If ``None`` (the default), + ``ABACUS_ORB_PATH`` is used when set; an explicit value, including + an empty string, is preserved. omp_num_threads : int, optional The number of omp threads to use. ''' @@ -116,8 +142,14 @@ def __init__(self, # further validation on the command will be in the __init__ of # the base class super().__init__(command, **kwargs) - self.pseudo_dir = pseudo_dir - self.orbital_dir = orbital_dir + # These two community conventions are the only environment fallbacks + # in this package; explicit arguments always take precedence. Only an + # omitted (None) argument falls back, so an explicit empty string is + # preserved instead of being replaced by the environment. + self.pseudo_dir = (pseudo_dir if pseudo_dir is not None + else (os.environ.get("ABACUS_PP_PATH") or None)) + self.orbital_dir = (orbital_dir if orbital_dir is not None + else (os.environ.get("ABACUS_ORB_PATH") or None)) if omp_num_threads is not None: # set the number of omp threads for the present process @@ -160,6 +192,7 @@ def version(self) -> str: cmd_ = [*self._split_command, '--version'] return AbacusProfile.parse_version(read_stdout(cmd_)) + class AbacusTemplate(CalculatorTemplate): implemented_properties = [ @@ -168,6 +201,7 @@ class AbacusTemplate(CalculatorTemplate): _label = 'abacus' def __init__(self): + self._legacyio = __LEGACYIO__ super().__init__( 'abacus', self.implemented_properties @@ -287,25 +321,23 @@ def write_input(self, # copy the `parameters` because later we will modify it parameters = parameters.copy() + stru_file = parameters.get('stru_file', 'STRU') or 'STRU' # STRU - _ = file_safe_backup(directory / parameters.get('stru_file', 'STRU')) - # group atoms by first-occurrence species order. Keep the reverse map - # so that we will recover the order in function read_results() + # group atoms by first-occurrence species order. Keep the reverse map so + # that we will recover the order in function read_results() ind = species_group_indices(atoms.get_chemical_symbols()) self.atomorder = sorted(range(len(atoms)), key=lambda i: ind[i]) # revmap # then we write - _ = write_stru(atoms[ind], - outdir=directory, - pp_file=parameters.get('pseudopotentials'), - orb_file=parameters.get('basissets'), - fname=parameters.get('stru_file', 'STRU')) + _write_ase_stru(atoms[ind], directory, + parameters.get('pseudopotentials'), + parameters.get('basissets'), + stru_file, backup=True) # KPT, if needed if 'kpts' in parameters: - _ = file_safe_backup(directory / parameters.get('kpoint_file', 'KPT')) - _ = write_kpt(parameters['kpts'], - directory / parameters.get('kpoint_file', 'KPT')) + kpt_file = directory / (parameters.get('kpoint_file', 'KPT') or 'KPT') + _write_kpt(parameters['kpts'], kpt_file, backup=True) # should this function be responsible for checking the integrity # of information provided by the user? There may be the case that # user provides incomplete information, such that the ABACUS cannot @@ -334,7 +366,7 @@ def write_input(self, # remove possible key-value pairs whose value is None parameters = {k: v for k, v in parameters.items() if v is not None} - # FIXME: only support the ksdft esolver_type presently + # Limitation: only the ksdft esolver is supported. if parameters.get('esolver_type', 'ksdft') != 'ksdft': raise NotImplementedError( 'ABACUS Lite only supports the ksdft esolver_type presently, ' @@ -404,21 +436,47 @@ def tail(p: Path, n: int) -> str: def read_results(self, directory) -> Dict: '''the function that returns the desired properties in dict''' - read_abacus_out = lambda fn: None - global __LEGACYIO__ - if __LEGACYIO__: + if self._legacyio: from abacuslite.io.legacyio import read_abacus_out else: from abacuslite.io.latestio import read_abacus_out + directory = Path(directory) outdir = directory / f'OUT.{self.suffix}' - # only the last frame - atoms: Optional[Atoms] = read_abacus_out( - outdir / f'running_{self.calculation}.log', - sort_atoms_with=self.atomorder)[-1] + log = outdir / f'running_{self.calculation}.log' + frames = read_abacus_out(log, sort_atoms_with=self.atomorder) + if not frames: + raise RuntimeError(f"no ABACUS running-log frames in {log}") + atoms = frames[-1] assert atoms is not None - return dict(atoms.calc.properties()) + # ASE's Properties schema accepts scalar magnetic moments only, + # although SinglePointDFTCalculator supports vector moments. Project + # other properties through ASE and retain vectors as result metadata, + # without changing ASE's process-global output definitions. + singlepoint = atoms.calc + vector_moments = { + name: singlepoint.results[name] + for name, shape in (('magmom', (3,)), ('magmoms', (len(atoms), 3))) + if name in singlepoint.results + and np.shape(singlepoint.results[name]) == shape + } + if vector_moments: + singlepoint = copy(singlepoint) + singlepoint.results = { + name: value for name, value in singlepoint.results.items() + if name not in vector_moments + } + results = dict(singlepoint.properties()) + results.update(vector_moments) + if vector_moments: + results.setdefault('natoms', len(atoms)) + if 'energy_without_entropy' in atoms.info: + results['energy_without_entropy'] = atoms.info['energy_without_entropy'] + # Keep the existing result alias alongside ASE's standard property. + if 'fermi_level' in results: + results['efermi'] = results['fermi_level'] + return results def load_profile(self, cfg, **kwargs): return AbacusProfile.from_config(cfg, self.name, **kwargs) @@ -467,20 +525,19 @@ def __init__(self, **kwargs: Other parameters to be passed to the ABACUS calculator. ''' - # not recommended :( + # Fallback profile for callers that do not provide one. profile = AbacusProfile('abacus') if profile is None else profile # to be compatible with both the legacy and latest format of i/o, the # switch is needed. - _ = switch_io_backend_version(profile.version()) + template = AbacusTemplate() + template._legacyio = _uses_legacy_io(profile.version()) - # because ABACUS run job in folders, based on the assumption that - # there is only one job in the folder. Therefore once there are already - # files in the folder, will try to create a new one...(seriously?) + # Optional ABACUS INPUT parameters, merged with calculator keywords. inp = kwargs.pop('inp', {}) super().__init__( - template=AbacusTemplate(), + template=template, profile=profile, parameters=kwargs | inp, directory=directory, @@ -497,14 +554,21 @@ def write_input(self, atoms, properties=None, system_changes=None): properties=properties, ) + def export_properties(self): + """Export only values accepted by ASE's versioned Properties schema.""" + return _schema_compatible_properties(self.results) + @classmethod def restart(cls, profile=None, directory='.', **kwargs): '''instantiate one ABACUS calculator from an existing job directory, optionally overwrite some keywords''' directory = Path(directory) inp_read = read_input(directory / 'INPUT') + inp = inp_read | kwargs.pop('inp', {}) - pporb_read = read_stru(directory / 'STRU')['species'] + # The old INPUT names the files to read; overrides apply to the next run. + stru_file = directory / (inp_read.get('stru_file', 'STRU') or 'STRU') + pporb_read = read_stru(stru_file)['species'] pseudopotentials = kwargs.get( 'pseudopotentials', {pporb['symbol']: pporb['pp_file'] for pporb in pporb_read} @@ -522,19 +586,32 @@ def restart(cls, profile=None, directory='.', **kwargs): basissets = {} assert all([forb is not None for forb in basissets.values()]) - kpts = kwargs.get('kpts', read_kpt(directory / inp_read.get('kpoint_file', 'KPT'))) if 'kpts' in kwargs: - del kwargs['kpts'] - - inp = inp_read | kwargs.get('inp', {}) - if 'inp' in kwargs: - del kwargs['inp'] + kpts_kwargs = {'kpts': kwargs.pop('kpts')} + else: + kpt_file = directory / (inp_read.get('kpoint_file', 'KPT') or 'KPT') + if kpt_file.is_file(): + kpts_kwargs = {'kpts': read_kpt(kpt_file)} + else: + gamma_only = str(inp.get('gamma_only', '')).strip().lower() in ( + '1', 'true', 't', '.true.') + raw_spacing = inp.get('kspacing', '') + spacing = (raw_spacing if isinstance(raw_spacing, (list, tuple)) + else str(raw_spacing).split()) + try: + implicit_kpts = gamma_only or bool(spacing) and all( + float(value) > 0 for value in spacing) + except ValueError: + implicit_kpts = gamma_only + if not implicit_kpts: + read_kpt(kpt_file) # preserve the missing/invalid KPT error + kpts_kwargs = {} return cls(profile=profile, directory=directory, pseudopotentials=pseudopotentials, basissets=basissets, - kpts=kpts, + **kpts_kwargs, inp=inp, **kwargs) @@ -578,13 +655,17 @@ def fixed_density(self, # we should overwrite the 'calculation' to 'nscf', and 'init_chg' to 'file' assert symmetry == 'off' - kwargs.setdefault('inp', {}).update({'calculation': 'nscf', - 'init_chg': 'file', - 'symmetry': 0, - 'out_band': 1, - 'kspacing': 0.0, # overwrite - 'gamma_only': False, - 'read_file_dir': 'OUT.ABACUS'}) # overwrite + inp = kwargs.get('inp', {}).copy() + inp.update({'calculation': 'nscf', + 'init_chg': 'file', + 'symmetry': 0, + 'out_band': 1, + 'kspacing': 0.0, # overwrite + 'gamma_only': False}) + source_suffix = getattr(self, 'parameters', {}).get('suffix', 'ABACUS') + if inp.get('read_file_dir') is None: + inp['read_file_dir'] = f'OUT.{source_suffix}' + kwargs['inp'] = inp profile = self.profile if profile is None else profile @@ -860,7 +941,7 @@ def _decode_socket_metadata(raw): raise ValueError('ABACUS socket extras are not valid UTF-8 JSON') from error if not isinstance(metadata, dict): raise ValueError('ABACUS socket extras must be a JSON object') - if metadata.get('schema') != 'abacus.socket.properties.v1': + if metadata.get('schema') != SOCKET_METADATA_SCHEMA: raise ValueError('unsupported ABACUS socket extras schema') present = metadata.get('present') if not isinstance(present, list): @@ -956,7 +1037,6 @@ def _forces_to_input_order(forces, order): reordered[original_index] = forces[sorted_index] return reordered - class TestAbacusCalculator(unittest.TestCase): here = Path(__file__).parent diff --git a/interfaces/ASE_interface/abacuslite/io/generalio.py b/interfaces/ASE_interface/abacuslite/io/generalio.py index c690964a5bb..69bc798cc2c 100644 --- a/interfaces/ASE_interface/abacuslite/io/generalio.py +++ b/interfaces/ASE_interface/abacuslite/io/generalio.py @@ -5,8 +5,8 @@ import tempfile import unittest from pathlib import Path -from io import TextIOWrapper -from typing import Optional, Dict, List, Any +from io import StringIO +from typing import Optional, Dict, List, Any, Mapping, TextIO import numpy as np from ase.atoms import Atoms @@ -15,6 +15,40 @@ from ase.data import chemical_symbols, atomic_masses ATOM_MASS = dict(zip(chemical_symbols, atomic_masses.tolist())) + +def _running_log_geometry(record): + """Convert a running-log geometry record to Cartesian Angstrom.""" + positions = np.asarray(record['coords'], dtype=float) + cell = np.asarray(record['cell'], dtype=float) + coordinate = record['coordinate'] + if coordinate == 'Direct': + positions = positions @ cell + elif coordinate == 'Cartesian': + positions = positions * record['alat_in_angstrom'] + else: + raise ValueError(f'Unknown coordinate system: {coordinate}') + return positions, cell + + +def _energy_without_entropy_metadata(ener: Mapping[str, float]) -> Dict[str, float]: + """Return the no-entropy energy as metadata when the log reports -TS. + + ``E_KohnSham`` already includes ``E_entropy(-TS)`` and remains the + force-consistent ASE energy. The separate no-entropy value is metadata, + not an ASE ``free_energy`` replacement. Missing entropy stays unknown. + + Args: + ener: Frame-local ABACUS energies in eV. + + Returns: + The no-entropy energy in eV when its entropy term is available. + """ + if 'E_entropy(-TS)' not in ener: + return {} + return { + 'energy_without_entropy': float(ener['E_KohnSham']) - float(ener['E_entropy(-TS)']), + } + def load_pseudo(pseudo_dir: str) -> Dict[str, str]: '''load the pseudopotential mapping from the pseudo_dir''' pseudo_dir = Path(pseudo_dir) @@ -232,9 +266,14 @@ def write_stru(stru: Atoms, str The path to the written STRU file. ''' + return _write_ase_stru(stru, outdir, pp_file, orb_file, fname, backup=False) + + +def _write_ase_stru(stru, outdir, pp_file, orb_file, fname, *, backup): from ase.units import ( Bohr as __BOHR__, - Angstrom as __ANGSTROM__ + Angstrom as __ANGSTROM__, + AUT as __AUT__, ) assert isinstance(stru, Atoms) pp_file = pp_file or {} # can be None, for those non-ESolver_KS cases @@ -246,6 +285,11 @@ def write_stru(stru: Atoms, ind = species_group_indices(elem) coords = stru.get_positions()[ind] mobility = _constraint_mobility(stru)[ind] + # ASE velocities are Angstrom / ASE time; STRU v is Bohr / atomic time. + # ABACUS MD writes v / (ANGSTROM_AU * AU_to_FS) as Angstrom/fs. + velocities = (stru.get_velocities()[ind] * __AUT__ / __BOHR__ + if stru.has('momenta') else np.zeros((len(stru), 3))) + masses = stru.get_masses()[ind] elem = [elem[i] for i in ind] # handle the atomic magnetic moment (issue #6516) @@ -255,6 +299,15 @@ def write_stru(stru: Atoms, for m in magmoms] elem_uniq = list(dict.fromkeys(elem)) nat = np.array([elem.count(e) for e in elem_uniq]) + species_masses = [] + start = 0 + for symbol, count in zip(elem_uniq, nat): + values = masses[start:start + count] + if not np.all(values == values[0]): + raise ValueError(f'Different masses for species {symbol} cannot be ' + 'represented by one ABACUS STRU species entry') + species_masses.append(float(values[0])) + start += count stru_dict = { 'coord_type': 'Cartesian', 'lat': { @@ -264,7 +317,7 @@ def write_stru(stru: Atoms, 'species': [ { 'symbol': e, - 'mass': ATOM_MASS[e], + 'mass': species_masses[i], 'pp_file': pp_file.get(e, ''), 'pp_type': '', 'natom': n, @@ -273,7 +326,7 @@ def write_stru(stru: Atoms, magmoms[j] | { 'coord': coords[j].tolist(), # coordinate 'm': mobility[j].tolist(), # mobility - 'v': [0.0, 0.0, 0.0], # velocity + 'v': velocities[j].tolist(), # atomic units of velocity } for j in range(np.sum(nat[:i]), np.sum(nat[:i+1])) ] } @@ -283,10 +336,12 @@ def write_stru(stru: Atoms, if orb_file is not None: for s in stru_dict['species']: s['orb_file'] = orb_file[s['symbol']] - + path = Path(outdir) / fname + if backup: + file_safe_backup(path) _write_stru(outdir, stru_dict, fname) - return (Path(outdir) / fname).resolve().as_posix() + return path.resolve().as_posix() def write_input(data: Dict[str, Any], fn: str) -> str: ''' @@ -313,7 +368,7 @@ def write_input(data: Dict[str, Any], fn: str) -> str: return str(Path(fn).resolve()) -def _write_kline(data: Dict[str, Any], f: TextIOWrapper): +def _write_kline(data: Dict[str, Any], f: TextIO): ''' write the k-point file whose mode is "Line" ''' @@ -324,7 +379,7 @@ def _write_kline(data: Dict[str, Any], f: TextIOWrapper): for k, nk in zip(data['kpoints'], data['nkinterpl']): f.write(f"{k[0]} {k[1]} {k[2]} {nk}\n") -def _write_ksampl_mp(data: Dict[str, Any], f: TextIOWrapper): +def _write_ksampl_mp(data: Dict[str, Any], f: TextIO): ''' write the k-point file whose mode is automatically sampling with Monkhorst-Pack ''' @@ -334,16 +389,21 @@ def _write_ksampl_mp(data: Dict[str, Any], f: TextIOWrapper): f.write(f"{data['nk'][0]} {data['nk'][1]} {data['nk'][2]} " f"{data['kshift'][0]} {data['kshift'][1]} {data['kshift'][2]}\n") -def _write_kpoint(data: Dict[str, Any], f: TextIOWrapper): +def _write_kpoint(data: Dict[str, Any], f: TextIO): ''' write the k-point file whose mode is specifying kpoints one-by-one ''' + kpoints = data['kpoints'] + weights = data.get('weights') + if weights is None: + weights = data.get('nkinterpl', [1] * len(kpoints)) + if len(kpoints) != data['nk'] or len(weights) != len(kpoints): + raise ValueError('Explicit KPT requires one weight per declared k point') f.write('K_POINTS\n') f.write(f"{data['nk']}\n") f.write(f"{data['coordinate'].capitalize()}\n") - nkinterpl = data.get('nkinterpl', [1 for _ in data['kpoints']]) - for k, nk in zip(data['kpoints'], data.get('nkinterpl', nkinterpl)): - f.write(f"{k[0]} {k[1]} {k[2]} {nk}\n") + for (x, y, z), weight in zip(kpoints, weights): + f.write(f"{x} {y} {z} {weight}\n") def read_kpoint_from_running_log(fn: str) -> Dict[str, Any]: '''Read the k-point information from the ABACUS running log file.''' @@ -366,6 +426,10 @@ def write_kpt(data: Dict[str, Any], fn: str) -> str: str the absolute path of the written KPT file ''' + return _write_kpt(data, fn, backup=False) + + +def _write_kpt(data, fn, *, backup): assert 'mode' in data, 'KPT data must contain "mode" key' mywriter = { # 'line': _write_kline, @@ -375,10 +439,16 @@ def write_kpt(data: Dict[str, Any], fn: str) -> str: assert data['mode'] in mywriter, \ f'Invalid KPT mode {data["mode"]}, must be one of ' \ f'{list(mywriter.keys())}' - with open(fn, 'w') as f: + # Validate and format before touching the previous KPT. + with StringIO() as f: mywriter[data['mode']](data, f) + content = f.getvalue() - return str(Path(fn).resolve()) + path = Path(fn) + if backup: + file_safe_backup(path) + path.write_text(content) + return str(path.resolve()) def _parse_coord_line(line): ''' @@ -399,43 +469,64 @@ def _parse_coord_line(line): ''' fields = line.split() - result = { 'coord' : [float(x) for x in fields[0:3]] } - + if len(fields) < 3: + raise ValueError('An atom record requires three coordinate values') + result = {'coord': list(map(float, fields[:3]))} + aliases = {'m': 'm', 'v': 'v', 'vel': 'v', 'velocity': 'v', + 'mag': 'mag', 'magmom': 'mag', 'angle1': 'angle1', + 'angle2': 'angle2'} + options = {} idx = 3 while idx < len(fields): - if fields[idx].isdigit(): # no keyword, 0/1 -> frozen atom - result['m'] = [int(x) for x in fields[idx:idx+3]] - idx += 3 - elif fields[idx] == 'm': # frozen atom - result['m'] = [int(x) for x in fields[idx+1:idx+4]] - idx += 4 - elif fields[idx] in ['v', 'vel', 'velocity']: # initial velocity - result['v'] = [float(x) for x in fields[idx+1:idx+4]] - idx += 4 - elif fields[idx] in ['mag', 'magmom']: - ''' - here we assume that frozen atom info cannot be placed after - a collinear mag info without a keyword - i.e., the following coordinate line - 0.0 0.0 0.0 mag 1.0 0 0 0 - is not allowed; one must explicitly specify 'm' in this case: - 0.0 0.0 0.0 mag 1.0 m 0 0 0 - - ''' - if idx + 2 < len(fields) and fields[idx+2] == 'angle1': - result['mag'] = ('Spherical', - list(map(float, fields[idx+1:idx+6:2]))) - idx += 6 - elif idx + 2 < len(fields) and fields[idx+2][0].isdigit(): - result['mag'] = ('Cartesian', - list(map(float, fields[idx+1:idx+4]))) - idx += 4 - else: # collinear - result['mag'] = float(fields[idx+1]) - idx += 2 - else: - raise ValueError('Error: unknown keyword %s'%fields[idx]) + token = fields[idx] + if token in ('0', '1'): + # Mobility may omit its keyword after a complete property, too. + keyword = 'm' + else: + if token not in aliases: + raise ValueError(f'Unknown atom keyword: {token}') + keyword = aliases[token] + idx += 1 + if keyword in options: + raise ValueError(f'Duplicate atom keyword: {keyword}') + start = idx + while idx < len(fields) and fields[idx] not in aliases: + idx += 1 + values = fields[start:idx] + if keyword == 'mag': + expected = (1, 3) + elif keyword in ('angle1', 'angle2'): + expected = (1,) + else: + expected = (3,) + # A complete property may be followed by the legacy bare triplet. + # For mag, use its vector width so scalar-plus-flags stays ambiguous. + if len(values) == max(expected) + 3 and values[-3] in ('0', '1'): + values = values[:-3] + idx -= 3 + if len(values) not in expected: + raise ValueError(f'{keyword} requires {expected} values, got {len(values)}') + if keyword == 'm': + flags = list(map(int, values)) + if any(flag not in (0, 1) for flag in flags): + raise ValueError('Mobility flags must be 0 or 1') + options[keyword] = flags + else: + options[keyword] = list(map(float, values)) + + for keyword in ('m', 'v'): + if keyword in options: + result[keyword] = options[keyword] + angles = [key in options for key in ('angle1', 'angle2')] + if any(angles): + if not all(angles) or len(options.get('mag', [])) != 1: + raise ValueError('Spherical moments require mag, angle1 and angle2') + result['mag'] = ('Spherical', + options['mag'] + options['angle1'] + options['angle2']) + elif 'mag' in options: + values = options['mag'] + result['mag'] = values[0] if len(values) == 1 else ('Cartesian', values) return result def _atomic_positions_gen(lines): @@ -602,19 +693,27 @@ def _read_kpoint(raw: List[str]) -> Dict[str, Any]: assert raw[2].lower() in ['direct', 'cartesian'], \ f'Invalid KPT file, expected "Direct" or "Cartesian" in the third line, ' \ f'got {raw[2]}' - mymatch = [re.match(r'^(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)\s*' - r'(\d+).*', l) - for l in raw[3:]] - assert all(m for m in mymatch), \ - 'Invalid KPT file, expected the k-points to be in the format ' \ - '"x y z n # comment"' - + points = [] + weights = [] + for line_number, line in enumerate(raw[3:], start=4): + fields = re.split(r'#|//|!', line, maxsplit=1)[0].split() + try: + # ABACUS consumes the first four values and ignores any row label. + x, y, z, weight = map(float, fields[:4]) + except ValueError as exc: + raise ValueError( + f'Invalid explicit KPT row {line_number}: expected x y z weight' + ) from exc + if not np.isfinite([x, y, z, weight]).all(): + raise ValueError(f'Invalid explicit KPT row {line_number}: non-finite value') + points.append((x, y, z)) + weights.append(weight) return { 'mode': 'point', 'coordinate': 'Cartesian' if raw[2].lower() == 'cartesian' else 'Direct', 'nk': int(raw[1]), - 'kpoints': [tuple(map(float, m.groups()[:3])) for m in mymatch], - 'weights': [int(m.groups()[6]) for m in mymatch] + 'kpoints': points, + 'weights': weights, } def read_kpt(fn: str) -> Dict[str, Any]: diff --git a/interfaces/ASE_interface/abacuslite/io/latestio.py b/interfaces/ASE_interface/abacuslite/io/latestio.py index 2b5e4ac39a9..ecf0b20236a 100644 --- a/interfaces/ASE_interface/abacuslite/io/latestio.py +++ b/interfaces/ASE_interface/abacuslite/io/latestio.py @@ -17,6 +17,7 @@ # some output formats are not updated, # for these cases, we import from the legacyio module from abacuslite.io.legacyio import ( + _read_log_source, read_kpoints_from_running_log, read_energies_from_running_log, read_traj_from_md_dump, @@ -24,6 +25,7 @@ is_invalid_arr, find_final_info_with_iter_header ) +from abacuslite.io.generalio import _energy_without_entropy_metadata, _running_log_geometry def read_esolver_type_from_running_log(src: str | Path | List[str]) \ -> str: @@ -125,8 +127,8 @@ def read_band_from_eig_occ(src: str | Path | List[str]) \ k = k.reshape((nframe, nspin, nk, 3)) ekbpat = r'\d+\s+' - ekbpat += r'(-?\d+(\.\d+)?(e[+-]\d+)?)\s+' - ekbpat += r'(\d+(\.\d+)?(e[+-]\d+)?)' + ekbpat += r'(-?\d+(\.\d+)?([eE][+-]?\d+)?)\s+' + ekbpat += r'(-?\d+(\.\d+)?([eE][+-]?\d+)?)' iekb = [i for i, l in enumerate(raw) if re.match(ekbpat, l)] assert len(iekb) > 0, f'No band energy found' assert len(iekb) % (nspin*nk) == 0 @@ -397,21 +399,18 @@ def read_abacus_out(fileobj, -> read_results() -> read_abacus_out() *here* - To use this function as a standalone one, the fileobj should be - the return of the open() function, which is a TextIOWrapper object: - >>> with open(fn) as fileobj: - ... read_abacus_out(fileobj) + Supply a path or a named text stream so companion files can be located: + >>> read_abacus_out(Path("OUT.ABACUS/running_scf.log"), index=-1) Parameters ---------- - fileobj : str | Path | TextIOWrapper - The file object to read. - index : slice + fileobj : str | Path | text stream + Running-log path or open text stream with a filesystem name. + Streams remain owned by the caller and are not closed here. + index : int or slice The index of the frames to read. results_required : bool - Whether the results are required. If True, the results will be - returned. If False, the results will not be returned. This parameter - is not used. + Retained for compatibility; currently has no effect. sort_atoms_with: Optional[List[int]] The sort order of the atoms. If not None, the atoms will be sorted according to the order in the list. @@ -419,16 +418,12 @@ def read_abacus_out(fileobj, Returns ------- atoms : Atoms | List[Atoms] - The atoms object, whose calculator is the `SinglePointDFTCalculator`. + Standard ASE geometry: Cartesian positions and cell in Angstrom, with + the periodic ABACUS simulation box. The attached calculator is a + `SinglePointDFTCalculator`. ''' - assert isinstance(fileobj, Path) - # it is required that the running log file is passed as the Path object - # so that the band structure file ``eig_occ.txt`` can be located as the - # one in the same folder, otherwise the reading of elecstate will be - # invalid and cause the failure - with open(fileobj) as f: - abacus_lines = f.readlines() - + log_path, abacus_lines = _read_log_source(fileobj) + # read the esolver type eslvtyp = read_esolver_type_from_running_log(abacus_lines) # FIXME: implement read_ksdft_esolver_out instead of read_abacus_out to @@ -437,12 +432,12 @@ def read_abacus_out(fileobj, # read the structure, with the cell, elem, etc. (nframe) # if it is MD run, the trajectories will be in the file MD_dump, instead # of the running log - trajectory = read_traj_from_running_log(abacus_lines) \ - if fileobj.name != 'running_md.log' else \ - read_traj_from_md_dump(fileobj.parent / 'MD_dump') + md_calculation = log_path.name == 'running_md.log' + trajectory = read_traj_from_md_dump(log_path.parent / 'MD_dump') \ + if md_calculation else read_traj_from_running_log(abacus_lines) # read the eigenvalues (nframe, nk, nbnd) - elecstate = read_band_from_eig_occ(fileobj.parent / 'eig_occ.txt') + elecstate = read_band_from_eig_occ(log_path.parent / 'eig_occ.txt') # read the atomic forces (nframe, nat, 3) forces = read_forces_from_running_log(abacus_lines) @@ -492,19 +487,27 @@ def read_abacus_out(fileobj, trajectory, elecstate, magmom, forces, stress, energies): # for each frame, a structure can be defined ind = ind or list(range(len(frame['elem']))) + if md_calculation: + # MD_dump lattice vectors use alat; positions are already Angstrom. + cell = frame['cell'] * frame['alat_in_angstrom'] + positions = frame['coords'] + else: + positions, cell = _running_log_geometry(frame) atoms = Atoms(symbols=np.array(frame['elem'])[ind].tolist(), - positions=frame['coords'][ind], - cell=frame['cell'], + positions=positions[ind], + cell=cell, + pbc=True, # ABACUS uses a periodic simulation cell for every run. magmoms=mag[ind]) # from result, a calculator can be assembled # however, sometimes the force and stress is not calculated # in this case, we set them to None frs = None if is_invalid_arr(frs) else frs[ind] strs = None if is_invalid_arr(strs) else full_3x3_to_voigt_6_stress(strs) + atoms.info.update(_energy_without_entropy_metadata(ener)) calc = SinglePointDFTCalculator(atoms=atoms, energy=ener['E_KohnSham'], free_energy=ener['E_KohnSham'], forces=frs, stress=strs, - magmoms=mag[ind], efermi=ener['E_Fermi'], + magmoms=mag[ind], efermi=ener.get('E_Fermi'), ibzkpts=kvecd, dipole=None) # import the eigenvalues and occupations kpoint-by-kpoint calc.kpts = [] @@ -538,6 +541,8 @@ def test_read_abacus_out_reorders_calculator_magmoms(self): [1.0, 0.0, 0.0], [2.0, 0.0, 0.0]]), 'cell': np.eye(3), + 'coordinate': 'Cartesian', + 'alat_in_angstrom': 1.0, } elecstate = [{ 'k': np.zeros((1, 1, 3)), @@ -671,8 +676,8 @@ def test_read_stress_from_running_log(self): def test_read_abacus_out_string(self): fn = self.testfiles / 'pw-symm0-nspin4-gamma-md' - # the case that does not give the instance of Path - with self.assertRaises(AssertionError): + # String paths are accepted; this fixture lacks its companion band file. + with self.assertRaisesRegex(FileNotFoundError, "eig_occ.txt"): read_abacus_out(str(fn)) def test_read_pw_symm0_nspin4_gamma_md(self): diff --git a/interfaces/ASE_interface/abacuslite/io/legacyio.py b/interfaces/ASE_interface/abacuslite/io/legacyio.py index 223a31b52d1..f6a5b3ce0c9 100644 --- a/interfaces/ASE_interface/abacuslite/io/legacyio.py +++ b/interfaces/ASE_interface/abacuslite/io/legacyio.py @@ -1,7 +1,7 @@ import re import shutil import unittest -from io import TextIOWrapper +from io import TextIOBase from pathlib import Path from typing import Dict, List, Tuple, Optional, Any @@ -13,6 +13,7 @@ ) from ase.units import Ry, eV, GPa, bar from ase.stress import full_3x3_to_voigt_6_stress +from abacuslite.io.generalio import _energy_without_entropy_metadata, _running_log_geometry # from ase.utils import reader __all__ = ['read_kpoints_from_running_log', @@ -736,7 +737,7 @@ def read_iter_header_from_running_log(src: str | Path | List[str]) \ raw = [l.strip() for l in raw] raw = [l for l in raw if l] # remove empty lines - HEADER_PAT = r'(LCAO|PW)\s+ALGORITHM\s+-+\s+ION=\s+([0-9]+)\s+ELEC=\s+([0-9]+)' + HEADER_PAT = r'(LCAO|PW)\s+ALGORITHM\s+-+\s+ION=\s*([0-9]+)\s+ELEC=\s*([0-9]+)' res = [re.findall(HEADER_PAT, l) for l in raw] return [(int(pack[0][1]), int(pack[0][2])) for pack in res if pack] @@ -796,6 +797,20 @@ def is_invalid_arr(arr) -> bool: return True return False +def _read_log_source(fileobj): + """Read a path or caller-owned text stream and locate companion output files.""" + if isinstance(fileobj, (str, Path)): + log_path = Path(fileobj) + with log_path.open() as stream: + return log_path, stream.readlines() + if not isinstance(fileobj, TextIOBase): + raise TypeError('Expected a log path or an open text stream') + name = getattr(fileobj, 'name', None) + if not isinstance(name, (str, Path)) or not str(name) or str(name).startswith('<'): + raise ValueError('A log stream needs a filesystem name to locate companion files') + return Path(name), fileobj.readlines() + + # @reader def read_abacus_out(fileobj, index=slice(None), @@ -810,15 +825,15 @@ def read_abacus_out(fileobj, -> read_results() -> read_abacus_out() *here* - To use this function as a standalone one, the fileobj should be - the return of the open() function, which is a TextIOWrapper object: + A running-log path or an open text stream may be supplied: >>> with open(fn) as fileobj: ... read_abacus_out(fileobj) Parameters ---------- - fileobj : str | Path | TextIOWrapper - The file object to read. + fileobj : str | Path | text stream + Running-log path or open text stream with a filesystem name. + Streams remain owned by the caller and are not closed here. index : slice The index of the frames to read. results_required : bool @@ -831,20 +846,34 @@ def read_abacus_out(fileobj, Returns ------- atoms : Atoms | List[Atoms] - The atoms object, whose calculator is the `SinglePointDFTCalculator`. + Standard ASE geometry: Cartesian positions and cell in Angstrom, with + the periodic ABACUS simulation box. The attached calculator is a + `SinglePointDFTCalculator`. ''' - if isinstance(fileobj, (str, Path)): - with open(fileobj) as f: - abacus_lines = f.readlines() - else: # from the `with open(fn) as fileobj:` context - assert isinstance(fileobj, TextIOWrapper) - abacus_lines = fileobj.readlines() - + log_path, abacus_lines = _read_log_source(fileobj) + # read the esolver type eslvtyp = read_esolver_type_from_running_log(abacus_lines) - # read the structure, with the cell, elem, etc. (nframe) - trajectory = read_traj_from_running_log(abacus_lines) + # Prefer MD_dump when present: current LTS running_md.log normally contains + # only the initial structure, but older complete MD logs stand alone. + md_calculation = log_path.name == 'running_md.log' + dump_path = log_path.parent / 'MD_dump' if md_calculation else None + geometry_from_dump = md_calculation and dump_path.exists() + if geometry_from_dump: + if not dump_path.is_file(): + raise ValueError(f'Invalid MD_dump: expected a file at {dump_path}') + try: + trajectory = read_traj_from_md_dump(dump_path) + except (AssertionError, IndexError, ValueError, ZeroDivisionError) as exc: + raise ValueError(f'Invalid or truncated MD_dump: {dump_path}: {exc}') from exc + log_structures = read_traj_from_running_log(abacus_lines) + if log_structures: + symbols = log_structures[0]['elem'] + if any(frame['elem'] != symbols for frame in trajectory): + raise ValueError(f'MD_dump frame atom count/order disagrees with {log_path}') + else: + trajectory = read_traj_from_running_log(abacus_lines) # read the eigenvalues (nframe, nk, nbnd) elecstate = read_band_from_running_log(abacus_lines) # read the atomic forces (nframe, nat, 3) @@ -871,6 +900,12 @@ def read_abacus_out(fileobj, magmom = read_magmom_from_running_log(abacus_lines) # roughly check the integrity of data from their length consistency + if md_calculation and (len(trajectory) != len(energies) + or len(trajectory) != len(elecstate)): + source = 'MD_dump' if geometry_from_dump else 'running_md.log without MD_dump' + raise ValueError(f'{source} geometry frame count {len(trajectory)} != ' + f'energy/electronic frame counts ' + f'{len(energies)}/{len(elecstate)} in {log_path}') assert len(trajectory) == len(energies), \ f'Inconsistent length: {len(trajectory)} != {len(energies)}' assert len(trajectory) == len(elecstate), \ @@ -892,9 +927,16 @@ def read_abacus_out(fileobj, trajectory, elecstate, magmom, forces, stress, energies): # for each frame, a structure can be defined ind = ind or list(range(len(frame['elem']))) + if md_calculation and geometry_from_dump: + # MD_dump lattice vectors use alat; positions are already Angstrom. + cell = frame['cell'] * frame['alat_in_angstrom'] + positions = frame['coords'] + else: + positions, cell = _running_log_geometry(frame) atoms = Atoms(symbols=np.array(frame['elem'])[ind].tolist(), - positions=frame['coords'][ind], - cell=frame['cell'], + positions=positions[ind], + cell=cell, + pbc=True, # ABACUS uses a periodic simulation cell for every run. magmoms=mag[ind]) # from result, a calculator can be assembled @@ -902,10 +944,11 @@ def read_abacus_out(fileobj, # in this case, we set them to None frs = None if is_invalid_arr(frs) else frs[ind] strs = None if is_invalid_arr(strs) else full_3x3_to_voigt_6_stress(strs) + atoms.info.update(_energy_without_entropy_metadata(ener)) calc = SinglePointDFTCalculator(atoms=atoms, energy=ener['E_KohnSham'], free_energy=ener['E_KohnSham'], forces=frs, stress=strs, - magmoms=mag[ind], efermi=ener['E_Fermi'], + magmoms=mag[ind], efermi=ener.get('E_Fermi'), ibzkpts=kvecd, dipole=None) # import the eigenvalues and occupations kpoint-by-kpoint calc.kpts = [] @@ -1027,6 +1070,8 @@ def test_read_abacus_out_reorders_calculator_magmoms(self): [1.0, 0.0, 0.0], [2.0, 0.0, 0.0]]), 'cell': np.eye(3), + 'coordinate': 'Cartesian', + 'alat_in_angstrom': 1.0, } elecstate = [{ 'k': np.zeros((1, 1, 3)), @@ -1245,11 +1290,10 @@ def test_read_iter_header_from_running_log(self): self.assertEqual(header[2], (2,1)) fn = self.testfiles / 'pw-symm0-nspin4-gamma-md_' header = read_iter_header_from_running_log(fn) - self.assertEqual(header[0], (1,1)) - self.assertEqual(header[1], (1,2)) - self.assertEqual(header[2], (1,3)) - self.assertEqual(header[3], (3,2)) - self.assertEqual(header[4], (3,3)) + # Include the compact ION=2/ELEC=1 and ION=3/ELEC=1 headers too. + self.assertEqual( + header, [(1, 1), (1, 2), (1, 3), (2, 1), (3, 1), (3, 2), (3, 3)] + ) def test_find_final_info_with_iter_header(self): info = [1, 2, 3, 4, 5, 6] diff --git a/interfaces/ASE_interface/examples/soc.py b/interfaces/ASE_interface/examples/soc.py index cdbbd04d6e4..8cc091bd406 100644 --- a/interfaces/ASE_interface/examples/soc.py +++ b/interfaces/ASE_interface/examples/soc.py @@ -10,16 +10,6 @@ from ase.atoms import Atoms from abacuslite import Abacus, AbacusProfile -'''SPECIAL: ase does not support the noncolinear spin yet -till 2026/3/24, see ase/outputs.py:L154-155, in which the -magmom cannot be set as the vector, so we release the -datatype of magmom and magmoms by ourself''' -from ase.outputs import _defineprop, all_outputs -del all_outputs['magmom'] -del all_outputs['magmoms'] -_defineprop('magmom', float, shape=3) # re-define the magmom can be set as the vector -_defineprop('magmoms', float, shape=('natoms', 3)) - fe = Atoms(symbols=['Fe'] * 2, scaled_positions=[[0., 0., 0.], [0.5, 0.5, 0.5]], magmoms=np.array([[0, 0, 1], [0, 0, 1]]), @@ -60,4 +50,4 @@ for ife, m in enumerate(fe.calc.results['magmoms']): print(f'Fe{ife}: ({",".join([f"{mi:10.6f}" for mi in m])}) uB') -shutil.rmtree(jobdir) \ No newline at end of file +shutil.rmtree(jobdir) diff --git a/interfaces/ASE_interface/pyproject.toml b/interfaces/ASE_interface/pyproject.toml index 8f84373e0af..dccd29827b5 100644 --- a/interfaces/ASE_interface/pyproject.toml +++ b/interfaces/ASE_interface/pyproject.toml @@ -15,10 +15,10 @@ authors = [ ] requires-python = ">=3.10" dependencies = [ - "ase>=3.22.0", + "ase>=3.23.0", "seekpath" ] [tool.setuptools.packages.find] where = ["."] -include = ["abacuslite*"] \ No newline at end of file +include = ["abacuslite*"]