PiNN: Pair-wise interaction Neural Network

PiNN^1,2 is a pair-wise interaction neural network Python library built on top of TensorFlow. The PiNN library provides elemental layers and abstractions to implement various atomic neural networks. It can be used together with plugins PiNNAcLe for the adaptive learn-on-the-fly workflow and PiNNwall for molecular simulation of electrode/electrolyte interfaces.

This project was initiated by Yunqi Shao. The code is currently maintained by the TeC group at Uppsala University.

Requirements

• Python >= 3.9 and < 3.12
• ASE >= 3.25
• PyYAML ~= 6.0.1
• TensorFlow >= 2.15 and < 2.16^3,4
• NumPy < 2

Installation

We recommend two ways to install PiNN.

1. You need to first create a virtual environment:

git clone https://github.com/Teoroo-CMC/PiNN.git
cd PiNN

conda env create -f environment.yml

After activating the pinn environment, then install PiNN using the following command:

pip install -e .

2. Alternatively, you can use the docker image. The CPU image is based on tensorflow/tensorflow:2.15.0; the GPU image on NVIDIA NGC nvcr.io/nvidia/tensorflow:24.03-tf2-py3 (x86_64 and aarch64/GH200). Both images expose the pinn CLI (Jupyter is no longer bundled).

# published tags (built on Teoroo-CMC/PiNN master / version tags)
singularity build pinn.sif docker://tecatuu/pinn:master-gpu   # or master-cpu
./pinn.sif --help

# or build from this repo (runtime deps come from setup.py)
docker build -t pinn:cpu .
docker build -f Dockerfile.gpu -t pinn:gpu .
# clusters without Docker:
apptainer build /path/on/allowed/fs/pinn-cpu.sif Singularity
apptainer build /path/on/allowed/fs/pinn-gpu.sif Singularity.gpu

Documentation

Since PiNN 1.0 the documentation is hosted on Github pages

Models and datasets

Dataset loaders

• CP2K format
• RuNNer format
• ANI-1 format
• QM9 format
• DeePMD-kit format

Implemented Networks

• Behler-Parrinello Neural Network
• PiNet
• PiNet2

Implemented models

• Interatomic potential model
• Dipole model
• Quadrupole model
• Polarizability model

Community

As an open-source project, the following contributions are highly welcome:

• Reporting bugs
• Proposing new features
• Discussing the current version of the code
• Submitting fixes

We use Github to host code, to track issues and feature requests, as well as to accept pull requests.

Please follow the procedure below before you open a new issue.

• Check for duplicate issues first.
• If you are reporting a bug, include the system information (platform, Python and TensorFlow version etc.).

If you would like to add some new features via pull request, please discuss with us first to see whether it fits the scope and aims of this project.

References and notes

[1] Li, J.; Knijff, L.; Zhang, Z.-Y.; Andersson, L.; Zhang, C. PiNN: Equivariant Neural Network Suite for Modelling Electrochemical Systems. J. Chem. Theory Comput., 2025, 21: 1382.

[2] Shao, Y.; Hellström, M.; Mitev, P. D.; Knijff, L.; Zhang, C. PiNN: A Python Library for Building Atomic Neural Networks of Molecules and Materials. J. Chem. Inf. Model., 2020, 60: 1184.

[3] TensorFlow is not installed by pip install pinn alone. Use the extras: pip install -e '.[cpu]' or pip install -e '.[gpu]' (x86_64 CUDA wheel). There is no aarch64 GPU wheel on PyPI; GH200 / Hopper nodes should use Dockerfile.gpu / Singularity.gpu (NGC TF 2.15).

[4] TF 2.15 is the last release that still ships tf.estimator and the legacy Keras optimizers (removed in 2.16), which PiNN's training loop depends on. See the migration notes.