Metadata-Version: 2.4
Name: pymatgen-io-aims
Version: 0.2.1
Summary: pymatgen-io-aims is a pymatgen addon that bridges the gap between FHI-aims and the pymatgen ecosystem
Author-email: Thomas Purcell <purcell@fhi-berlin.mpg.de>, Andrei Sobolev <sobolev@ms1p.org>
Maintainer-email: Thomas Purcell <purcell@fhi-berlin.mpg.de>, Andrei Sobolev <sobolev@ms1p.org>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/FHI-aims-club/pymatgen-io-aims.git
Project-URL: Issues, https://gitlab.com/FHI-aims-club/pymatgen-io-aims/issues
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pymatgen>=2022.0.3
Requires-Dist: pyfhiaims>=1.1.0
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest_parametrize_cases; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

pymatgen-io-aims
================

``pymatgen-io-aims`` is a `pymatgen <https://pymatgen.org>`_ addon that adds
support for `FHI-aims <https://fhi-aims.org>`_, an all-electron full-potential
electronic structure code based on numeric atom-centered orbitals.  The package
follows the same conventions as other ``pymatgen.io`` adapters so that FHI-aims
can be used inside the pymatgen ecosystem — and tools built on top of it such as
`atomate2 <https://github.com/materialsproject/atomate2>`_ — with minimal
additional effort.

Features
--------

* **Input generation** — build ``geometry.in`` and ``control.in`` files from
  ``pymatgen`` ``Structure`` or ``Molecule`` objects via a thin wrapper around
  `pyfhiaims <https://gitlab.com/FHI-aims-club/pyfhiaims>`_.

* **Output parsing** — read FHI-aims standard output into pymatgen objects
  (energies, forces, stresses, structures, magnetic moments, …).

* **Input set generators** for common workflows:

  ============================================  ================================
  Generator                                     Purpose
  ============================================  ================================
  ``StaticSetGenerator``                        Single-point energy
  ``RelaxSetGenerator``                         Geometry relaxation
  ``SocketIOSetGenerator``                      Socket-based driver (i-PI / ASE)
  ``MDSetGenerator``                            Molecular dynamics (NVE / NVT)
  ``BandStructureSetGenerator``                 Band structure along high-symm. k-path
  ``GWSetGenerator`` / ``BSBSESetGenerator``    GW quasiparticle + BSE spectra
  ``MagneticStaticSetGenerator``                Spin-polarised single-point
  ``MagneticRelaxSetGenerator``                 Spin-polarised relaxation
  ============================================  ================================

Installation
------------

The package is available on PyPI::

    pip install pymatgen-io-aims

To install the development version directly from the repository::

    pip install git+https://gitlab.com/FHI-aims-club/pymatgen-io-aims.git

Requirements: Python ≥ 3.10, ``pymatgen ≥ 2022.0.3``, ``pyfhiaims ≥ 1.1.0``.

Quick Start
-----------
First `configure <https://workflows-with-atomate2-fhi-aims-club-tutorials-a0acc2efc2fba83.gitlab.io/Tutorial-2/Pymatgen/#configuration>`_ `pymatgen` to use `pymatgen-io-aims`, and then:

.. code-block:: python

    from pymatgen.core import Structure
    from pymatgen.io.aims.sets.core import StaticSetGenerator

    structure = Structure.from_file("POSCAR")

    gen = StaticSetGenerator(user_params={
        "k_grid": [8, 8, 8],
        "species_dir": "light"
    })
    input_set = gen.get_input_set(structure)
    input_set.write_input("aims_input/")

This writes ``geometry.in`` and ``control.in`` into the ``aims_input/``
directory, ready to be passed to FHI-aims.

Parsing output is equally straightforward:

.. code-block:: python

    from pymatgen.io.aims.outputs import AimsOutput

    output = AimsOutput.from_outfile("aims.out")
    print(output.final_structure)
    print(output.final_energy)

Documentation & Examples
-------------------------

Auto-generated API documentation is available from the repository's GitLab
Pages.  Tutorials and worked examples can be found at:

https://workflows-with-atomate2-fhi-aims-club-tutorials-a0acc2efc2fba83.gitlab.io/Tutorial-2/Pymatgen/

Contributing
------------

Contributions are welcome!  Please read ``CONTRIBUTING.md`` before opening a
merge request.  Bug reports and feature requests go to the
`issue tracker <https://gitlab.com/FHI-aims-club/pymatgen-io-aims/issues>`_.

Contributors
------------

* Thomas A. R. Purcell (@tpurcell90) — creator and maintainer
* Andrei Sobolev (@ansobolev) — creator and maintainer

License
-------

``pymatgen-io-aims`` is released under the MIT License.  See ``LICENSE`` for
details.
