README.md

miniFF: a minimal implementation of neural-network force fields. Compute energies and forces of atomic systems with neural networks.

About

This package implements Behler and Parrinello approach to simulating structures and dynamics of atomic systems. You may want to use it if:

• you are interested in structural properties of a system with many atoms such as a molecule or an amorphous material;
• your system is too large for electronic structure treatment (e.g. density functional theory molecular dynamics);
• no empiric potentials for your system exist ...
• ... or the existing empiric potentials are not sufficient to reach the desired tolerances in energies and forces;
• you are interested in machine learning techniques for materials science problems and are looking for a good starting point for your research.

The package is written in Python3.

Built with

• pytorch is the machine learning and autodiff driver for this package;
• cython is used for performance-critical tasks such as computing descriptors and their gradients;
• numpy is the tensor and data engine in addition to torch;
• scipy is used for sparse data, neighbor search and optimization.

In addition,

• matplotlib is used for plotting, and
• numericalunits is used for handling units.

Documentation

Hosted on Read the Docs.

Install

Prerequisites

• Python3
• C compiler: Required for compiling Cython extensions

Examples

• Debian Linux

  apt-get install -y build-essential python3-dev python3-pip

• Fedora

  dnf groupinstall "Development tools" "Development libraries"

• MacOS:

  Install gcc and make sure it is used by default.

  brew install gcc

  Add to .bash_profile path and alias:

  export CC=/usr/local/bin/gcc-10
  alias gcc='gcc-10'

• Windows:

  On Windows, the support for installing a C compiler and compiling cython extensions is cumbersome and outdated as can be inferred from the Cython Wiki. We suggest to use the Windows subsystem for Linux (WSL) in this case. More information on WSL and its installation instructions are here.

Install from git

git clone https://gitlab.kwant-project.org/qt/miniff.git
cd miniff
python setup.py install

Install from pip

pip install miniff

Use

from miniff.ml_util import fit

fit(
    prepare=dict(fn_cells="cells.json"),
    run=dict(n_epochs=1),
)

CLI

miniff support basic command-line interface to most common workflows.

python -m miniff jobs.yml

jobs.yml:

fit:
  prepare:
    fn_cells: cells.json
  run:
    n_epochs: 1

Contributing

See CONTRIBUTING.md for contirbution guidelines

Authors

See AUTHORS.MD for the list of contributors

License

This work is licensed under the BSD 2-Clause License