libatoms / pymatnext

Python Nested Sampling for Materials, the Next Generation

Overview

pymatnext is a Python package for doing nested sampling (NS) which was developed as a complete rewrite of pymatnest. While it is coded with some generalizability in mind, it is designed for atomistic materials science applications, and currently supports single atomic configurations with the ASE atoms object.

Features

Nested Sampling

• Sample on potential energy $E$, with or without enthalpy term $+ P V$ for fixed pressure and chemical potential term $- \sum_i \mu_i N_i$ for variable composition (but constant total number of atoms, i.e. semi-grand-canonical ensemble).

• Output arbitrary sampled quantities, including NS quantity ($E + \delta_V P V - \delta_N \sum_i \mu_i N_i$), as well as configuration-type-specific quantities such as cell volume and composition.

• Output sampled configurations, for postprocessed computation at any temperature of any quantity that can be computed from the configurations.

• Save snapshots of population and random number generator states for restarts

• One sample culled per NS iteration

Parallelization

• Optionally parallelized with MPI by distributing configurations among $N_p$ MPI tasks and walking one configuration per task for a shorter trajectory length $L' = L / N_p$.

Configurations

• Periodic or nonperiodic cells containing atoms of any chemical species. Use an extended version of the ase.atoms.Atoms class, which stores all important data in two np.ndarray objects, so that MPI parallelized runs can communicate them without having to pack/unpack the data each time.

Energy calculators

• ASE ase.calculators.Calculator, with random walks carried out by Python code within pymatnext.

• LAMMPS potentials with random walks carried out inside LAMMPS with a custom set of fixes.

Random walks

Walks consist of blocks of a several steps of a single type (position or cell or species).

Positions

• Positions sampled with Galilean Monte Carlo, i.e. walking in a straight line in $3 N$ dimensional positions space until energy exceeds NS maximum, then reflecting specularly, and accepting or rejecting entire trajectory depending on on final energy.

Cell

• Cell shape and size sampled with Monte Carlo moves. Volume may be sampled from a $V^{N}$ prior, which is the correct one for ensemble averages, or with a flat prior, which requires reweighting of the sampled configurations during analysis.

Species

• Atom species sampled with Monte Carlso swap or semi-grand-canonical (total atom number conserving at an applied chemical potential) moves.

Usage

see here

complete parameters list

Analysis

see here

Using LAMMPS

LAMMPS compiled with cmake

To use lammps, set the env var LAMMPS_DIR to the top of the LAMMPS source directory, above src/ and cmake/, and do

cd $LAMMPS_DIR
patch_file=$( python3 -c 'import pymatnext; from pathlib import Path; print(str(Path(pymatnext.__file__).parent) + "/extras/lammps.patch")' )
patch -p1 < $patch_file

The NS package must then be added to enable the fix ns/* commands, and LAMMPS must be recompiled without MPI support. The LAMMPS python interface must then be installed.

If using cmake, this can be done by adding NS to the section set(STANDARD_PACKAGES... (the patch file in pymatnext/extras/lammps.patch should do this), and adding -D PKG_NS=ON to the cmake command (in addition to

-D BUILD_MPI=OFF
-D BUILD_SHARED_LIBS=ON
-D LAMMPS_EXCEPTIONS=ON

and whatever other options are needed). Installing the python package is most easily done with make install-python after the regular make.

TODO

(in order of priority?)

• refactor <prefix>.NS_samples and <prefix>.traj.<suffix> truncation code (minor)
• create ABC for NSConfig (med)
• sample positions with TE-HMC (major)

Done

• restart from snapshots
• refactor NSConfig.n_quantities to be a class rather than instance attribute (minor)

pymatnext's Issues

Emax is not always monotonic decreasing

There exist input files and run configurations (LAMMPS, 256 atoms, 8192 walkers, 128 MPI tasks) where the max energy goes up from one iteration to the next. This was only detected when the Z_of_T loop exit condition ended the run very early, because when the energy when up the contribution of the current iteration to the Z sum dropped by order of magnitude (due to the Boltzmann factor on the current higher energy).

entropy calculation

confirm that entropy calculation is OK, as recently discussed in https://gaborcsanyi.slack.com/archives/C53HKH341/p1677809789313149 for original pymatnest analysis scripts.

not all configs saved in snapshot have correct step size info

Only configs that originated on root MPI process correctly save step size in snapshot. As a result, restarting will use the wrong step size until the next tuning interval.

TE-HMC

Add support for TE-HMC?

pytests in CI

Add a CI action that runs the tests automatically for every PR (see examples in, e.g. https://github.com/libAtoms/workflow/blob/main/.github/workflows/pytests.yml)

documentation doesn't mention adding NS package to LAMMPS cmake config

Update documentation (and perhaps patch) to discuss changes that need to be made to LAMMPS's cmake/CMakeLists.txt file to add the NS package.

cell aspect ratio

The aspect ratio change of the simulation cell should be limited - what's being done currently? This should probably be a keyword as well, maybe with a sensible default as 0.8?

Pressure keyword

We should have a keyword to set the pressure for the simulation (I think the default is 0.0?)

generate initial random configs in parallel

With large numbers of walkers and atoms, generating the initial configs takes a significant amount of time. It would be helpful if, when possible, these were generated in parallel rather than all generated on the root MPI task and sent to each other MPI task.

The new config generator would need to receive the local rng, and return a logical flag indicating whether the loop should be on the root task over all configs, or a little loop on the generator on each task in parallel.