Metadata-Version: 2.1
Name: jaxip
Version: 0.5.9
Summary: JAX-based Interatomic Potential
Home-page: https://github.com/hghcomphys/jaxip
Author: Hossein Ghorbanfekr
Author-email: hgh.comphys@gmail.com
License: GNU General Public License v3
Keywords: jaxip
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.8
License-File: LICENSE
License-File: AUTHORS.rst


.. .. image:: docs/images/logo.png
..         :alt: logo
        
=====
JAXIP
=====

**JAX-based Interatomic Potential**

.. image:: https://img.shields.io/pypi/v/jaxip.svg
        :target: https://pypi.python.org/pypi/jaxip

.. image:: https://github.com/hghcomphys/jaxip/actions/workflows/python-app.yml/badge.svg
        :target: https://github.com/hghcomphys/jaxip/blob/main/.github/workflows/python-app.yml

.. image:: https://readthedocs.org/projects/jaxip/badge/?version=latest
        :target: https://jaxip.readthedocs.io/en/latest/?version=latest
        :alt: Documentation Status


Description
-----------
Jaxip is an optimized Python library on basis of Google `JAX`_ that enables 
development of emerging machine learning interatomic potentials 
for use in computational physics, chemistry, material science. 
These potentials are necessary for conducting large-scale molecular 
dynamics simulations of complex materials with ab initio accuracy.

.. _JAX: https://github.com/google/jax


See `documentation`_ for more information.

.. _documentation: https://jaxip.readthedocs.io/en/latest/readme.html


Features
--------
* The design of Jaxip is `simple` and `flexible`, which makes it easy to incorporate atomic descriptors and potentials. 
* It uses `autograd` to make defining new descriptors straightforward.
* Jaxip is written purely in Python and optimized with `just-in-time` (JIT) compilation.
* It also supports `GPU-accelerated` computing, which can significantly speed up preprocessing and model training.

.. warning::
        This package is under heavy development and the current focus is on the implementation of high-dimensional 
        neural network potential (HDNNP) proposed by Behler et al. 
        (`2007 <https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.98.146401>`_).


Installation
------------
To install Jaxip, run this command in your terminal:

.. code-block:: console

    $ pip install jaxip

For machines with an NVIDIA **GPU** please follow the installation
`instruction <https://jaxip.readthedocs.io/en/latest/installation.html>`_ 
on the documentation. 


Examples
--------

-----------------------------
Defining an atomic descriptor
-----------------------------
This script demonstrates the process of evaluating an array of atomic-centered symmetry functions (`ACSF`_) 
for a specific element, which can be utilized to evaluate the descriptor values for any structure. 
The resulting values can then be used to construct a machine learning potential.

.. _ACSF: https://aip.scitation.org/doi/10.1063/1.3553717


.. code-block:: python

        from jaxip.datasets import RunnerDataset
        from jaxip.descriptors import ACSF
        from jaxip.descriptors.acsf import CutoffFunction, G2, G3

        # Read atomic structure dataset (e.g. water molecules)
        structures = RunnerDataset('input.data')
        structure = structures[0]

        # Define ACSF descriptor for hydrogen element
        descriptor = ACSF(element='H')

        # Add radial and angular symmetry functions
        cfn = CutoffFunction(r_cutoff=12.0, cutoff_type='tanh')
        descriptor.add( G2(cfn, eta=0.5, r_shift=0.0), 'H')
        descriptor.add( G3(cfn, eta=0.001, zeta=2.0, lambda0=1.0, r_shift=12.0), 'H', 'O')

        # Compute descriptor values
        descriptor(structure)

        # Compute gradient
        descriptor.grad(structure, atom_index=0)


-------------------------------------
Training a machine learning potential
-------------------------------------
This example illustrates how to quickly create a `high-dimensional neural network 
potential` (`HDNNP`_) instance from an in input setting files and train it on input structures. 
The trained potential can then be used to evaluate the energy and force components for new structures.

.. _HDNNP: https://pubs.acs.org/doi/10.1021/acs.chemrev.0c00868


.. code-block:: python

        from jaxip.datasets import RunnerDataset
        from jaxip.potentials import NeuralNetworkPotential

        # Read atomic data
        structures = RunnerDataset("input.data")
        structure = structures[0]

        # Instantiate potential from input settings file
        nnp = NeuralNetworkPotential.create_from_file("input.nn")

        # Fit descriptor scaler and model weights
        nnp.fit_scaler(structures)
        nnp.fit_model(structures)
        nnp.save()

        # Or loading from files
        #nnp.load()

        # Total energy
        nnp(structure)

        # Force components
        nnp.compute_force(structure)


License
-------

This project is licensed under the GNU General Public License (GPL) version 3 - 
see the `LICENSE <https://github.com/hghcomphys/jaxip/blob/main/LICENSE>`_ file for details.
