.. aenet-python documentation master file, created by
   sphinx-quickstart on Tue Feb  8 15:39:20 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

ænet-python Documentation
===========================

The ``aenet-python`` package is a collection of utilities for preparing
input files for, processing output files for, and generally interacting
with the machine-learning interatomic potential (MLIP) software
`ænet <http://ann.atomistic.net>`_.

Common use cases of the package are

* Extraction of structures, energies, and forces from the output of
  first-principles calculations;
* Interconversion of atomic structure formats, especially conversion to
  ænet's XSF format;
* Manipulation of atomic structures, e.g., for generating reference data;
* Operations on the featurized reference data produced by ænet's
  ``generate.x``;
* Training of machine-learning interatomic potentials using ænet's
  ``train.x``;
* Predicting structural energies and interatomic forces using ænet's
  ``predict.x``;
* Analysis of the outputs generated by ænet's ``train.x`` or
  ``predict.x``; and
* Using a PyTorch-based implementation of ænet's featurization and
  training algorithms for GPU-accelerated MLIP training and inference.

Some of the package's functionality is exposed through command-line
tools.  Specifically, the tool ``sconv`` (*structure conversion*) makes
available capabilities for atomic structure modification and
interconversion and ``sfp`` (*structure fingerprints*) can be used to
featurize atomic structures.  In addition, the ``config`` tool can be
used for :doc:`configuration </usage/installation>`.

See :doc:`/usage/commandline` for an overview of the
command-line capabilities.

References
----------

[1] ænet package: N. Artrith and A. Urban,
*Comput. Mater. Sci.* **114**, 2016, 135-150
(`link1 <http://dx.doi.org/10.1016/j.commatsci.2015.11.047>`_).

[2] Chebyshev featurization method: N. Artrith, A. Urban, and G. Ceder,
*Phys. Rev. B* **96**, 2017, 014112
(`link2 <https://doi.org/10.1103/PhysRevB.96.014112>`_).

[3] Tutorial: A. M. Miksch, T. Morawietz, J. Kästner, A. Urban, N. Artrith,
*Mach. Learn.: Sci. Technol.* **2**, 2021, 031001
(`link3 <http://doi.org/10.1088/2632-2153/abfd96>`_).

[4] Global moment representation: V. Gharakhanyan, M. S. Aalto,
A. Alsoulah, N. Artrith, A. Urban, ICLR 2023
(`link4 <https://openreview.net/forum?id=4Hl8bjobpl9>`_)

[5] ænet-PyTorch implementation: J. Lopez-Zorrilla, X. M. Aretxabaleta,
I. W. Yeu, I. Etxebarria, H. Manzano, N. Artrith,
*J. Chem. Phys.* **158**, 2023, 164105
(`link5 <https://doi.org/10.1063/5.0146803>`_)

Getting Started
---------------

.. toctree::
   :maxdepth: 1

   usage/installation
   usage/choosing_implementation


Tools for Data Generation and Acquisition
-----------------------------------------

.. toctree::
   :maxdepth: 2

   usage/structure_manipulation
   usage/transformations_basic
   usage/transformations_advanced
   usage/data_acquisition
   usage/commandline


Python Interface with ænet's Fortran Binaries
---------------------------------------------

Requires compiled Fortran binaries but provides excellent inference
performance for production HPC workflows.

.. toctree::
   :maxdepth: 2

   usage/featurization
   usage/training
   usage/inference
   usage/trainset


PyTorch Implementation
----------------------

Pure Python/PyTorch implementation with GPU support.

.. toctree::
   :maxdepth: 2

   usage/torch_featurization
   usage/torch_training
   usage/torch_datasets
   usage/torch_inference


Developer Documentation
-----------------------

.. toctree::
   :maxdepth: 2

   dev/neighbor_lists
   dev/commandline
   dev/docs_examples
   dev/analytical_gradients
   dev/torch_force_hdf5_cache

API Reference
-------------

.. toctree::
   :maxdepth: 2

   api/index


Indices and tables
--------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`