Metadata-Version: 2.4
Name: ase-extxyz
Version: 0.1.0
Summary: ASE I/O plugin backed by the libextxyz C parser
Author-email: James Kermode <james.kermode@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
License-File: LICENSE
Requires-Dist: ase>=3.23.0
Requires-Dist: extxyz>=0.3.0
Requires-Dist: numpy>=1.13.0
Requires-Dist: pytest ; extra == "test"
Project-URL: repository, https://github.com/libAtoms/extxyz
Provides-Extra: test

# ase-extxyz

ASE I/O plugin that wires the [`extxyz`](https://github.com/libAtoms/extxyz)
C parser into ASE's `read` / `write` machinery.

## Install

```bash
pip install ase-extxyz
```

This pulls in `extxyz` (the parser, with native binary wheels) and `ase`.

## Use

```python
import ase.io
from ase.build import bulk

atoms = bulk('Cu') * 2
ase.io.write('out.xyz', atoms, format='cextxyz')
back = ase.io.read('out.xyz', format='cextxyz')
```

The plugin registers a format named `cextxyz` (not `extxyz` — that name is
already taken by ASE's built-in regex-based reader). Pass `format='cextxyz'`
explicitly; auto-detection by extension is intentionally disabled to avoid
clashing with the built-in.

## Streaming output during optimization / MD

For long runs you don't want to reopen the file on every step. Use
`ExtXYZTrajectoryWriter` — it opens the libc `FILE*` once and writes
each frame through the C writer directly:

```python
from ase.optimize import LBFGS
from ase_extxyz.io import ExtXYZTrajectoryWriter

with ExtXYZTrajectoryWriter('opt.xyz', atoms=atoms) as traj:
    opt = LBFGS(atoms)
    opt.attach(traj, interval=1)   # opt calls traj() per step
    opt.run(fmax=1e-3)
```

`opt.attach(traj)` works because the writer is callable; `traj()` is
equivalent to `traj.write(atoms)` using the atoms captured at construction.

## What this is *not*

`ase-extxyz` is a thin translation layer between `extxyz.Frame` (a
plain-Python dict + numpy dataclass) and `ase.Atoms`. The fast C parser
lives in the `extxyz` package; install that alone if you don't need ASE.

## License

MIT — same as `extxyz`.

