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.
The following requirements need to be fulfilled in order to successfully install the software:
- g++/gcc v4.9 or higher
- icpc/icc v2018 or higher [optional but recommended]
- MPI compilers [optional, needed only for LAMMPS]
- FFTW libraries
- GSL libraries [optional, needed only for normal_modes executable]
- Read the entire README before doing anything!
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=$PWDMBX has different compilation instructions depending on how you plan to use it:
- For use with i-PI, Python, Fortran, or standalone, perform a basic installation
- For use with LAMMPS, perform an alternative MBX_MPI installation
autoreconf -fi
./configure
make && make install./configure has additional flags and options if you want to customize your installation:
CXX=if you want to use a different compiler than the system default. Popular options includeCXX=icpcorCXX=g++--enable-sharedif you want to also compile MBX as a shared library. This is required for using MBX with Python.--enable-debugfor debugging using GDB.--enable-verbosewill turn on additional logging to the console.--disable-optimizationwill disable compiler optimizations. This is not recommended unless you are debugging.--helpto see additional configuration options
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.
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.
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:
boxis either a 9 element list, with the 3 vectors of the box:[ax, ay, az, bx, by, bz, cx, cy, cz]or an empty list[]if one wants to run gas-phase calculations.twobody_cutoffis the distance at which the 2-body interactions will be cut in the real space. If you are using polynomials, that should be the largest polynomial cutoff that you are using (usually9.0Angstrom) in periodic boundary conditions. In gas phase calculations, that should be set to a large number so the real space electrostatics and dispersion are properly calculated and fully accounted for.threebody_cutoffis the cutoff for the 3-body polynomials. If only water is used, one can set that to4.5, but if alkali metal ions or halides are used, it should be set to the maximum cutoff in any of the trimers used (7.0).dipole_toleranceis the tolerance accepted for the induced dipoles iterative calculation. From one iteration to the other one, |mu(i,t+1) - mu(i,t)|^2 < dipole tolerance for any i. A value of1E-08is usually small enough. However, if the dipole solver used is aspc, the magnitude of the tolerance may have to be decreased up to1E-10or1E-12. It is recommended to run a few thousand steps using aspc and cg for the dipole solver, and decide which is the dipole tolerance needed.dipole_max_itis the maximum number of iterations allowed in the dipole iterative method calculation. If the number of iterations exceeds this value, MBX will throw an error message saying that the dipoles have diverged.dipole_methodis the method adopted to calculate the induced dipoles. Current options areiter(iterative),cg(conjugate gradient, faster than iter), andaspc(always stable predictor-corrector).aspcis only suitable for simulations. Onlycgandaspcare currently available in LAMMPS.alpha_ewald_{elec/disp}is the alpha used in the reciprocal space. It should be set to0.0when running gas-phase calculations/simulations.grid_density_{elec/disp}is the Ewald grid points density.spline_order_{elec/disp}is the order of the splines used for interpolation.ignore_2b_polya list of 2 element lists with the monomer pairs for which the 2-body polynomials will not be calculated. Example:"ignore_2b_poly" : [["na+","h2o"]]ignore_3b_polyhas a similar format as ignore_2b_poly, but with the difference that the list is a list of 3-element list. If a set of three monomer types is specified in this list, MBX won't calculate the 3-body polynomials for that given trimer. Example:"ignore_3b_poly" : [["na+","h2o","h2o"]]localhostis the name of the socket. It MUST match the name in the XML file, otherwise it will send an error saying that the socket was not found.portis used when interfacing with i-pi. It is the port that will hold the socket. Should be greater than34500.
After installation, there will be the main executables in $MBX_HOME/bin/.
single_pointwill return the energy (Binding Energy) in kcal/mol for a given configuration. One can have multiple systems in the nrg file, and single point will return the energies of each one of them. IfPRINT_GRADSis manually enabled in the source code in ($MBX_HOME/src/main/single_point.cpp) it will also print the gradients.optimizewill optimize a given configuration. You can optimize a single nrg system, or pass an XYZ file with a set of configurations, in which all of them will be optimized.mb_decompwill compute energies for subsystems for the given system(s), then performs many-body decomposition and prints the n-body contribution for all subsystems. If the flag to skip many-body decomposition ("-e") is activated, it instead prints the binding energy for all subsystems.order_frameswill compute the energies for a given list of configurations from the XYZ file, and rearranges the configuration frames in the order of increasing energy.normal_modeswill compute the normal modes for an optimized nrg file. Requires the GSL library.
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:
- MB-pol for water
- MB-nrg PEFs for alkali-metal ions in water
- MB-nrg PEFs for halide ions in water
- J. Chem. Theory Comput. 12, 2698 (2016)
- J. Chem. Phys. 148, 102321 (2018)
- J. Comp. Theory. Comput. 15, 2983 (2019)
- Nat. Chem. 11, 367 (2019)
- J. Phys. Chem. Lett. 10, 2823 (2019)
- J. Phys. Chem. A 123, 2843 (2019)
- Adv. Phys. X 4, 1631212 (2019)
- J. Chem. Phys. 155, 064502 (2021)
- J. Phys. Chem. B 126, 8266 (2022)
- MB-nrg PEFs for CO2 and CO2/H2O mixtures
- MB-nrg PEFs for CH4 and CH4/H2O mixtures
- MB-nrg PEF for N2O5 in water
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/mbxMBX 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 installThis 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=mpiicpcAfter 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.
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.gitBefore 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-nvtThis folder contains five files:
config.xyzis the input for the coordinates for i-PI, whileconfig.nrgis the input format for MBX. These two filesxyzandnrgare related, so if you make any changes to the xyz file you must correspondingly update the nrg file using$MBX_HOME/scripts/format_conversion config.xyzconfig.xmlis the i-PI input file. This simulation will run an NVT MD at 100K. Refer to the i-pi user manual for more information.mbx.jsonis the MBX configuration filerun_i-pi.shwill run the test. Make sure yousource env.shin the i-PI folder before running the test, or most likely it will fail.
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.
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.
