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 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 v9.3 or higher
- icpx/icx v2020 or higher [optional]
- FFTW libraries
- Read the entire README before doing anything!
The following requirements are optional, depending on how you plan to use MBX:
- MPI compilers [sometimes used for MBX+LAMMPS]
- GSL libraries [needed only for normal_modes executable]
MBX 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
git clone https://github.com/paesanilab/MBX.git
cd MBX/
autoreconf -fi
./configure
make && make install
export MBX_HOME=$(pwd) # optional./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=icpxorCXX=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],
"realspace_cutoff" : 9.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.realspace_cutoffis the distance at which the dispersion, Lennard-Jones, and electrostatics interactions will switch from the real space to the reciprocal space (Particle-Mesh Ewald). Usually a value of about9.0is good for calculations in periodic boundary conditions. In gas phase calculations, this should be set to a large number that exceeds the farthest interatomic distance in your system so that all interactions are computed in the real space. For backwards compatibility reasons, ifrealspace_cutoffis not specified, then it will be set to thetwobody_cutoff.twobody_cutoffis the cutoff for the 2-body polynomials. If only water is used, one can set that to6.5, but if alkali metal ions or halides are used, it should be set to the maximum cutoff in any of the dimers used (9.0).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: "h2o" (O H H)
- MB-nrg PEFs for alkali-metal ions in water: "li+, "na+, "k+, "rb+, "cs+"
- MB-nrg PEFs for halide ions in water: "f-, "cl-, "br-, "i-"
- 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: "co2" (C O O)
- MB-nrg PEFs for CH4 and CH4/H2O mixtures: "ch4" (C H H H H)
- MB-nrg PEF for N2O5 in water: "n2o5" (O N N O O O O)
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 is an official LAMMPS package (https://docs.lammps.org/pair_mbx.html), and needs to be installed using the LAMMPS CMake build-chain:
git clone -b develop https://github.com/lammps/lammps.git
cd lammps
cmake -S cmake -B build -C ./cmake/presets/basic.cmake -D PKG_MBX=yes -D PKG_EXTRA-PAIR=yes
cmake --build build --parallel 4 # compilation (can use higher --parallel on powerful computers)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 MBX plugins, perform a separate basic installation in a different directory.
Additional LAMMPS build options are available, such as using a different compiler or enabling additional packages. Please refer to the LAMMPS CMake build documentation for more information.
Examples for MBX+LAMMPS simulations are located in $MBX_HOME/plugins/lammps/examples/. Also see the LAMMPS documentation for more information about how to use MBX with LAMMPS: https://docs.lammps.org/pair_mbx.html.
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.
