search

paesanilab / MBX

MBX is an energy and force calculator for data-driven many-body simulations.
Other
30 stars 32 forks source link

readme

MBX testing suite codecov Homepage

MBX v1.2.0

MBX: A many-body energy and force calculator for data-driven many-body simulations. J. Chem. Phys. 159, 054802 (2023)

MBX is a C++ software that can either be used as a standalone software for calculating energies and forces of MB-nrg potential energy functions (PEFs) for the molecular systems of interest or interfaced with external molecular dynamics and Monte Carlo engines to perform classical and quantum simulations of the molecular system of interest across different thermodynamic states and phases, in both periodic and non-periodic conditions, using the corresponding MB-nrg PEFs. The current version of MBX provides interfaces to LAMMPS (https://www.lammps.org) and i-PI (http://ipi-code.org) which allow for performing classical and path-integral molecular dynamics simulations using MB-nrg PEFs. For details on the MB-pol and MB-nrg PEFs, please visit: https://paesanigroup.ucsd.edu/software/mbx.html.

MBX is periodically updated with performance improvements and the addition of other MB-nrg PEFs. For any questions about MBX, installation issues, or general usage inquiries, please use the MBX Google Group: https://groups.google.com/g/mbx-users.

Compilation and Installation

The following requirements need to be fulfilled in order to successfully install the software:

Setup

The home directory of MBX will be referred to as $MBX_HOME. You must set this environment variable, which can be exported either manually or by sourcing sourceme.sh:

git clone https://github.com/paesanilab/MBX.git
cd MBX/
export MBX_HOME=$PWD

Compilation

MBX has different compilation instructions depending on how you plan to use it:

Basic installation of MBX (for use with i-PI, Python, Fortran, or standalone. NOT LAMMPS)

autoreconf -fi
./configure
make && make install

./configure has additional flags and options if you want to customize your installation:

After performing basic installation, you should run the unit tests to make sure everything is working properly.

Alternative installation of MBX_MPI (LAMMPS only)

If you want to use MBX with LAMMPS, instead skip to this section about the LAMMPS plugin. This special installation using MPI is only compatible with LAMMPS and is incompatible with i-PI, Python, Fortran or standalone usage. If you need to use any of these other plugins, perform a separate basic installation in a different directory.

Testing

After basic installation, running the unit tests is highly recommended. Run the following commands to run the tests:

make check

All tests must pass. If you encounter any errors, please report them in the MBX Google Group.

Tests will fail if using an MPI compiler instead of g++/icpc, such as if you performed alternative installation with MBX_MPI with LAMMPS. Please instead perform basic installation first with g++/icpc and then run the tests.

JSON File

To make life easier for you, a JSON configuration file must be used to pass all the information that MBX needs. Usually, one does not need to change anything except a couple of options. In any case, all the options of the json file are explained below.

The JSON file template is the following:

{
   "Note" : "This is a  MBX v1.0.0 configuration file",
   "MBX" : {
       "box" : [21.0,0.0,0.0,0.0,21.0,0.0,0.0,0.0,21.0],
       "twobody_cutoff"   : 9.0,
       "threebody_cutoff" : 7.0,
       "dipole_tolerance" : 1E-08,
       "dipole_max_it"    : 100,
       "dipole_method"     : "cg",
       "alpha_ewald_elec" : 0.6,
       "grid_density_elec" : 2.5,
       "spline_order_elec" : 6,
       "alpha_ewald_disp" : 0.6,
       "grid_density_disp" : 2.5,
       "spline_order_disp" : 6,
       "ignore_2b_poly" : [],
       "ignore_3b_poly" : []
   } ,
   "i-pi" : {
       "localhost" : "localhost3",
       "port" : 34567
   }
}

In this file:

Main executables

After installation, there will be the main executables in $MBX_HOME/bin/.

PEFs implemented

All the PEFs implemented, along with examples of input files and scripts to run various types of simulations, are provided in $MBX_HOME/examples/PEFs. If a surface is not there, its usage is not recommended because it is either not tested or not finalized. Example calls with C++, Fortran and Python are located inside each of the corresponding folders.

Please cite the corresponding manuscript whenever using MBX:

Please cite the following manuscripts if any of the following PEFs is used:

Interfaces

Fortran90 and Python

In ${MBX_HOME}/examples/PEFs there are sample scripts on how to use MBX called from Fortran90 and Python. Please remember to update the LD_LIBRARY_PATH variable and, if using python, the PYTHONPATH variable.

export LD_LIBRARY_PATH=$MBX_HOME/lib/:$LD_LIBRARY_PATH
export PYTHONPATH=${PYTHONPATH}:${MBX_HOME}/plugins/python/mbx

LAMMPS

MBX can interface with LAMMPS using a plugin for LAMMPS. In order to use MBX with LAMMPS, you must first install MBX with MPI compilers. You must use mpicxx or mpiicpc instead of g++ or icpc. This can be done by running the following commands:

# install MBX with MPI
autoreconf -fi
./configure --enable-mpi CXX=mpiicpc
make && make install

This special installation using MPI is only compatible with LAMMPS and is incompatible with i-PI, Python, Fortran or standalone usage. If you need to use any of these other plugins, perform a separate basic installation in a different directory.

After installing MBX, you can then download the stable branch of LAMMPS and then compile it with the MBX plugin:

git clone -b stable https://github.com/lammps/lammps.git LAMMPS-stable
export LAMMPS_HOME=$PWD/LAMMPS-stable

cp -rf $MBX_HOME/plugins/lammps/USER-MBX $LAMMPS_HOME/src
cd $LAMMPS_HOME/src/
make yes-USER-MBX yes-MOLECULE yes-KSPACE yes-RIGID yes-EXTRA-PAIR
make mpi_mbx -j 4 CXX=mpiicpc

After this, a new executable lmp_mpi_mbx in $LAMMPS_HOME/src should appear, and that is the executable you have to use for LAMMPS.

Additional documentation will follow up. For now, please look at the examples in MBX_HOME/plugins/lammps to see how it is run. For any questions, please use the MBX Google Group: https://groups.google.com/g/mbx-users.

i-PI

This software is already interfaced with i-PI. In order to run molecular dynamics using the MB-nrg PEFs, you will need to install i-PI first.

git clone https://github.com/i-pi/i-pi.git

Before continuing with this, make sure i-PI is working. If you have any problems with the i-PI installation, you can ask a question in the i-pi-user forum. If you want to skip the testing (PROCEED AT YOUR OWN RISK), you can skip testing i-PI and assume it works.

After making sure that i-PI is working on your machine and having compiled MBX, you can use the i-PI driver located in $MBX_HOME/bin/ipi_driver to run MD using i-PI. To confirm that the driver is working, go to the i-PI examples folder in MBX:

cd $MBX_HOME/plugins/i-pi/examples/molecular_dynamics/gas_phase/3h2o/100K/1-nvt

This folder contains five files:

These should initialize i-PI and start the simulation. Once the simulation is completed, terminate the i-pi instance and then run the NVE simulation in $MBX_HOME/plugins/i-pi/examples/molecular_dynamics/gas_phase/3h2o/100K/2-nve.

cd $MBX_HOME/plugins/i-pi/examples/molecular_dynamics/gas_phase/3h2o/100K/2-nve
cp ../1-nvt/RESTART ./config.xml
./run_i-pi.sh

There are more tests for other types of simulations, including condensed phase simulations and replica-exchange simulations. For more information about what kind of simulations can i-PI run, please refer to the i-PI user manual.

Coverage

The unit tests implemented should cover a big part of the code. This sunburst graph gives an idea of the coverage from top (center) to bottom (periphery). Our goal is to keep it as green as possible, being green good coverage, and red bad coverage.