Metadata-Version: 2.4
Name: aiida-abacus
Version: 0.3.1
Summary: AiiDA plugin for ABACUS
Project-URL: Source, https://github.com/MCresearch/aiida-abacus
Author: aiida-abacus team
License: MIT License
        
        Copyright (c) 2024 aiida-abacus team.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: aiida,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AiiDA
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Requires-Python: >=3.10
Requires-Dist: aiida-core<3,>=2.5
Requires-Dist: aiida-pseudo~=1.7.2
Requires-Dist: ase
Requires-Dist: pydantic
Requires-Dist: tqdm
Requires-Dist: voluptuous
Provides-Extra: dev
Requires-Dist: ruff>=0.12.12; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: markupsafe>=2.1.1; extra == 'docs'
Requires-Dist: myst-parser~=3.0.0; extra == 'docs'
Requires-Dist: sphinx-autoapi~=3.0.0; extra == 'docs'
Requires-Dist: sphinx-book-theme~=1.0.1; extra == 'docs'
Requires-Dist: sphinx-click~=4.4.0; extra == 'docs'
Requires-Dist: sphinx-copybutton~=0.5.2; extra == 'docs'
Requires-Dist: sphinx-design~=0.6.1; extra == 'docs'
Requires-Dist: sphinxcontrib-contentui; extra == 'docs'
Requires-Dist: sphinxcontrib-details-directive~=0.1.0; extra == 'docs'
Requires-Dist: sphinxemoji; extra == 'docs'
Requires-Dist: sphinx~=6.2.1; extra == 'docs'
Provides-Extra: pre-commit
Requires-Dist: hatch; extra == 'pre-commit'
Requires-Dist: pre-commit~=3.5; extra == 'pre-commit'
Provides-Extra: tutorial
Requires-Dist: aiida-vasp; extra == 'tutorial'
Requires-Dist: ase-weas-widget; extra == 'tutorial'
Requires-Dist: pymatgen; extra == 'tutorial'
Requires-Dist: sumo; extra == 'tutorial'
Description-Content-Type: text/markdown

[![Build Status][ci-badge]][ci-link]
[![Coverage Status][cov-badge]][cov-link]
[![Docs status][docs-badge]][docs-link]
[![PyPI version][pypi-badge]][pypi-link]
[![Binder][binder-badge]][binder-link]

# aiida-abacus

This is the [AiiDA](https://www.aiida.net/) plugin for the ab-initio software package [ABACUS](https://abacus.ustc.edu.cn/main.htm).

## Quick start

Try this plugin with a live JupyterLab server with Binder!

Click the Binder badge [![Binder][binder-badge]][binder-link] to launch a **zero-install** JupyterLab.  
In two minutes you’ll have AiiDA + ABACUS fully set-up—complete with ready-to-run notebooks that let you submit calculations, track provenance, and visualize results right in your browser.

See [Tutorials](https://aiida-abacus.readthedocs.io/en/latest/tutorials/index.html) for installation locally.

## Installation

### Install from PyPI:

```shell
pip install aiida-abacus
```

### Install from source:
First clone the source code:
```bash
git clone https://github.com/MCresearch/aiida-abacus.git
cd aiida-abacus
```
Then install locally:
- install using `pip`
```bash
pip install .
# or pip install -e .
# if you want to make a change to the plugin
```
- install using `uv`
```bash
uv sync # use --extra like [--extra pre-commit] to include optional dependencies
```

We recommend using `aiida-abacus` with [ABACUS LTS (`v3.10.0`)](https://github.com/deepmodeling/abacus-develop/releases/tag/LTSv3.10.0).
This is a Long-Term Supported stable release. The LTS version will only receive essential bug fixes and performance optimization PRs, without introducing code modifications that might affect computational accuracy and precision, nor changes to input parameter names & output formats.
Note that output format changes introduced by the rapidly iterating `develop` branch (for example, `v3.9.0.3` and later `v3.9.0.x` released after `v3.10.0`) are currently not supported by the `aiida-abacus` parser. It is preferable to use ABACUS LTSv3.10.0 rather than `develop` release to produce data and work with `aiida-abacus`.



### Pseudopotentials
We use the [`aiida-pseudo` plugin](https://pypi.org/project/aiida-pseudo/) to install and manage pseudopotentials.
It is easy to install pseudopotentials by `aiida-pseudo` CLI:
```bash
aiida-pseudo install pseudo-dojo -f upf -v 0.4 -x PBE -r SR -p standard 
```
and load the pseudopotential family installed by calling
`load_group` in the launch script.
```py
pseudo_family = load_group('PseudoDojo/0.4/PBE/SR/standard/upf')
```

At least one pseudo potential family should be installed. For more information on pseudo family, please refer to [AiiDA pseudo plugin Documentation](https://aiida-pseudo.readthedocs.io/en/latest/).

## Documentation

See [our online docs](https://aiida-abacus.readthedocs.io/).

- Quick start

We ofter a [quick start tutorial](https://aiida-abacus.readthedocs.io/en/latest/tutorials/index.html) that provides two ways to get started: try Aiida-ABACUS instantly with our live JupyterLab environment powered by Binder, or follow the step-by-step guide to quickly set up a local installation and begin using the plugin.

See the `examples` directory to learn about how to run this plugin with scripts.

- Get started with [AiiDA](https://aiida-tutorials.readthedocs.io/en/latest/sections/getting_started/index.html). It is strongly recommended that the AiiDA setup and basics tutorials should be read and followed to ensure that the environment is set up correctly, while acquiring the relevant basic knowledge and basic concepts in AiiDA & getting to learn about using `verdi` CLI/APIs.

- Documentation for [ABACUS](https://abacus.deepmodeling.com/en/latest/index.html).


## Usage

Here goes a quick demo of how to submit a calculation using this plugin:
```shell
verdi daemon start      # make sure the daemon is running
cd examples
verdi run example_pw_Si2.py     # run example calculation
verdi process list -a   # check record of calculation
```
* Running calculations on a cluster is essentially the same, except that you need to configure the remote computer.
- We provide simple setup demo config files `remote-slurm-ssh-setup.yml` and `localhost-direct-local-setup.yml` in the `examples` dir. You can follow the guide in [How to set up a computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#how-to-set-up-a-computer) to configure a computational resource. Please configure `prepend_text` according to your remote environment if [Intel® oneAPI Toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/toolkits.html) is used to build ABACUS.

- You can also run the interactive Jupyter notebook `binder-example.ipynb` in the `examples` directory locally for a glimpse into `aiida-abacus`.

The plugin also includes verdi commands to inspect its data types:
```shell
verdi data abacus list
verdi data abacus export <PK>
```

## Development

```shell
git clone https://github.com/MCresearch/aiida-abacus .
cd aiida-abacus
pip install --upgrade pip
pip install -e .[pre-commit,testing]  # install extra dependencies
pre-commit install  # install pre-commit hooks
pytest -v  # discover and run all tests
```

### Repository contents

- `src/aiida_abacus`: Main source code of `aiida-abacus` plugin
    - `calculations.py`: The `AbacusCalculation` calcjob class.
    - `parsers.py`: The `abacus.abacus` default parser for `AbacusCalculation`.
- `examples/`: Example of how to submit a calculation using this plugin via a script.
<!-- See [Features](#features) for details. -->
- `tests/`: Basic tests supported by [pytest](https://docs.pytest.org/en/latest/). Install by `pip install -e .[testing]` and run `pytest`.

<!-- See the [developer guide](http://aiida-abacus.readthedocs.io/en/latest/developer_guide/index.html) for more information. -->

<!-- ## Features -->


## License

MIT


[ci-badge]: https://github.com/MCresearch/aiida-abacus/workflows/ci/badge.svg?branch=master
[ci-link]: https://github.com/MCresearch/aiida-abacus/actions
[cov-badge]: https://coveralls.io/repos/github/MCresearch/aiida-abacus/badge.svg?branch=master
[cov-link]: https://coveralls.io/github/MCresearch/aiida-abacus?branch=master
[docs-badge]: https://readthedocs.org/projects/aiida-abacus/badge
[docs-link]: http://aiida-abacus.readthedocs.io/
[pypi-badge]: https://badge.fury.io/py/aiida-abacus.svg
[pypi-link]: https://badge.fury.io/py/aiida-abacus
[binder-badge]: https://mybinder.org/badge_logo.svg
[binder-link]: https://mybinder.org/v2/gh/MCresearch/aiida-abacus/HEAD?urlpath=%2Fdoc%2Ftree%2Fexamples%2Fbinder-example.ipynb
