Metadata-Version: 2.5
Name: pyiron_workflow_assyst
Version: 0.2.1
Summary: A workflow package for ASSYST (Automated Symmetry and Stability Testing) using VASP calculations
Project-URL: Homepage, https://github.com/ligerzero-ai/pyiron_workflow_assyst
Project-URL: Documentation, https://github.com/ligerzero-ai/pyiron_workflow_assyst
Project-URL: Repository, https://github.com/ligerzero-ai/pyiron_workflow_assyst.git
Project-URL: Bug Tracker, https://github.com/ligerzero-ai/pyiron_workflow_assyst/issues
Author-email: pyiron Team <pyiron@mpie.de>
License: BSD-3-Clause
License-File: LICENSE
Keywords: assyst,dft,materials-science,pyiron,structure-testing,vasp,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.11
Requires-Dist: ase>=3.22.0
Requires-Dist: flowrep<0.7,>=0.6
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: pyiron-workflow-vasp<0.3,>=0.2.0
Requires-Dist: pyiron-workflow<0.21,>=0.19
Requires-Dist: pymatgen>=2023.0.0
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: flake8>=4.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: pytest-cov>=2.0; extra == 'dev'
Requires-Dist: pytest>=6.0; extra == 'dev'
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == 'notebook'
Requires-Dist: notebook>=6.0.0; extra == 'notebook'
Provides-Extra: test
Requires-Dist: packaging; extra == 'test'
Requires-Dist: pytest>=6.0; extra == 'test'
Requires-Dist: vaspparser; extra == 'test'
Description-Content-Type: text/markdown

# pyiron_workflow_assyst

A workflow package for ASSYST (Automated Small SYmmetric Structure Training) using VASP calculations, integrated with pyiron_workflow.

## Overview

This package implements the ASSYST methodology as described in:

> Poul, M., Huber, L., & Neugebauer, J. (2024). Automated Generation of Structure Datasets for Machine Learning Potentials and Alloys. [Research Square](https://www.researchsquare.com/article/rs-4732459/v1)

ASSYST is a strategy for generating unbiased and systematically extendable training data for machine learning interatomic potentials (MLIP) for multicomponent alloys. It explores the full space of random crystal structures with space groups, facilitating the construction of training sets for MLIPs in an automatic way without prior knowledge of the material.

## Features

- Automated generation of training structures for MLIPs
- Systematic exploration of crystal structure space
- Integration with VASP for DFT calculations
- Workflow-based implementation using pyiron_workflow
- Support for multicomponent alloys
- Structure validation and filtering

## Installation

```bash
pip install pyiron_workflow_assyst
```

For development installation (with the test dependencies):

```bash
git clone https://github.com/ligerzero-ai/pyiron_workflow_assyst.git
cd pyiron_workflow_assyst
pip install -e ".[test]"
pytest
```

The VASP-facing parts of the workflow read POTCARs through
`pyiron_workflow_vasp`'s `~/.pyiron_vasp_config` (or the file named by
`PYIRON_VASP_CONFIG`); see that package for how to set it up. The test suite
does not need one.

## Dependencies

- numpy>=1.20.0
- pandas>=1.3.0
- pymatgen>=2023.0.0
- ase>=3.22.0
- pyiron_workflow>=0.19,<0.21
- flowrep>=0.6,<0.7
- pyiron_workflow_vasp>=0.2.0,<0.3

## Usage

`run_ASSYST_on_structure` is a [`flowrep`](https://github.com/pyiron/flowrep)
`@fr.workflow` function, not a callable macro object -- under
`pyiron_workflow>=0.19`, it must be wrapped with `pyiron_workflow.node(...)`
and run with keyword arguments, not called or `.run()`-ed directly:

```python
import pyiron_workflow as pwf
from pymatgen.io.vasp.inputs import Incar
from pyiron_workflow_assyst import run_ASSYST_on_structure

incar = Incar.from_dict({"ENCUT": 400, "ISIF": 7, "NSW": 100, ...})

node = pwf.node(run_ASSYST_on_structure)
run = node.run(
    structure=your_structure,      # pymatgen Structure or ase Atoms
    incar=incar,
    potcar_paths=None,             # or an explicit list of POTCAR paths
    job_name="/absolute/path/to/job_dir",
    vasp_command="mpiexec -n 40 vasp_std",
    ionic_steps=100,
    n_stretch_permutations=2,
    n_rattle_permutations=2,
    rattle_displacement=0.1,
)

train_df = run.outputs.train_df  # pandas.DataFrame of accurate-statics results
```

See `examples/example.py` for a complete example (edit its cluster-specific
POTCAR path, output directory and `vasp_command` before running it), and
`tests/test_workflow.py` for the full set of keyword arguments
`run_ASSYST_on_structure` accepts.

## Documentation

For detailed documentation, please refer to the [documentation](https://github.com/ligerzero-ai/pyiron_workflow_assyst).

## Releasing

Releases go to PyPI from GitHub Actions via
[trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API token
is stored anywhere.

1. Bump `__version__` in `pyiron_workflow_assyst/__init__.py` (the only place the version lives) and add
   an entry to [`CHANGELOG.md`](CHANGELOG.md).
2. Open a PR and merge it to `main`. The
   [`release`](.github/workflows/release.yml) workflow builds the sdist and
   wheel and runs `twine check --strict` on every PR as a dry run.
3. Create a GitHub release with tag `v<version>` (e.g. `v0.2.0`). Publishing
   the release builds again, checks that the tag matches the package version
   (a `v` or `pyiron_workflow_assyst-` prefix is stripped), and uploads to
   [PyPI](https://pypi.org/p/pyiron_workflow_assyst).

One-time setup: on PyPI, add a trusted publisher for `pyiron_workflow_assyst` with owner
`ligerzero-ai`, repository `pyiron_workflow_assyst`, workflow `release.yml` and environment
`pypi`, and create a `pypi` environment in the GitHub repository settings
(optionally with required reviewers).

## Contributing

We welcome contributions! Please open an issue or pull request on
[GitHub](https://github.com/ligerzero-ai/pyiron_workflow_assyst).

## License

This project is licensed under the BSD-3-Clause License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use this package in your research, please cite:

```bibtex
@article{poul2024automated,
  title={Automated Generation of Structure Datasets for Machine Learning Potentials and Alloys},
  author={Poul, Marvin and Huber, Liam and Neugebauer, J{\"o}rg},
  journal={Research Square},
  year={2024},
  doi={10.21203/rs.3.rs-4732459/v1}
}
```

## Contact

For questions or support, please contact the pyiron team at pyiron@mpie.de 