hfcs-fffit is a repository used for a case study of our machine learning directed force field optimization workflow outlined in this preprint. Here we use the procedure to generate force fields for two hydrofluorocarbons (HFCs), HFC-32 and HFC-125.
This work has been submitted for review. In the meantime, you may cite the preprint as:
BJ Befort, RS DeFever, GM Tow, AW Dowling, and EJ Maginn. Machine learning
directed optimization of classical molecular modeling force fields. arXiv
(2021), https://arxiv.org/abs/2103.03208The non-dominated and "top four" parameter sets for each HFC are
provided under hfcs-fffit/analysis/csv/. The non-dominated
sets are found in r32-pareto.csv and r125-pareto.csv, and
the "top four" sets are found in r32-final-4.csv and
r125-final-4.csv. The parameter values in the csv files are
normalized between 0 and 1 based upon the parameter bounds for each
atom type (see manuscript, or hfcs-fffit/analysis/utils/r32.py
and hfcs-fffit/analysis/utils/r125.py for definitions of
the upper and lower parameter bounds).
All molecular simulations were performed under hfcs-fffit/runs.
Each iteration was managed with signac-flow. Inside of each
directory in runs, you will find all the necessary files to
run the simulations. Note that you may not get the exact same simulation
results due to differences in software versions, random seeds, etc.
Nonetheless, all of the results from our molecular simulations are saved
under hfcs-fffit/analysis/csv/rXX-YY-iterZZ-results.csv, where XX
is the molecule, YY is the stage (liquid density or VLE), and
ZZ is the iteration number.
All of the scripts for the surrogate modeling are provided in
hfcs-fffit/analysis, following the same naming structure as
the csv files.
All scripts required to generate the primary figures in the
manuscript are reported under hfcs-fffit/analysis/final-figs and the
associated PDF files are located under
hfcs-fffit/analysis/final-figs/pdfs.
This package has a number of requirements that can be installed in different ways. We recommend using a conda environment to manage most of the installation and dependencies. However, some items will need to be installed from source or pip.
We recommend starting with a fresh conda environment, then installing
the packages listed under requirements-pip.txt with pip, then
installing the packages listed under requirements-conda.txt with
conda, and finally installing a few items from source
requirements-other.txt. We recommend python3.7 and
taking packages from conda-forge.
Running the simulations will also require an installation of GROMACS. This can be installed separately (see installation instructions here).
WARNING: Cloning the hfcs-fffit repository will take some time
and ~1.5 GB of disk space since it contains the Latin hypercube
that have ~1e6 parameter sets each.
An example of the procedure is provided below:
# First clone hfcs-fffit and install pip/conda available dependencies
# with a new conda environment named hfcs-fffit
git clone git@github.com:dowlinglab/hfcs-fffit.git
cd hfcs-fffit/
conda create --name hfcs-fffit python=3.7 -c conda-forge
conda activate hfcs-fffit
python3 -m pip install -r requirements-pip.txt
conda install --file requirements-conda.txt -c conda-forge
cd ../
# Now clone and install other dependencies
git clone git@github.com:dowlinglab/fffit.git
# Checkout the v0.1 release of fffit and install
cd fffit/
git checkout tags/v0.1
pip install .
cd ../
# Checkout the v0.1 release of block average and install
git clone git@github.com:rsdefever/block_average.git
cd block_average/
git checkout tags/v0.1
pip install .
cd ../NOTE: We use signac and signac flow (https://signac.io/) to manage the setup and execution of the molecular simulations. These instructions assume a working knowledge of that software.
The first iteration of the liquid density simulations were
performed under the hfcs-fffit/runs/r32-density-iter1/.
A Latin hypercube with 200 parameter sets exists under
hfcs-fffit/runs/r32-density-iter1/data/lh_samples_200_r32.txt.
The signac workspace is created by hfcs-fffit/runs/r32-density-iter1/init.py.
cd hfcs-fffit/runs/r32-density-iter1/
python init.pyThe thermodynamic conditions for the simulations and the bounds for each parameter
(LJ sigma and epsilon for C, F, and H) are defined inside init.py.
The simulation workflow is
defined in hfcs-fffit/runs/r32-density-iter1/project.py. The flow operations
defined therein create the simulation input files, perform the simulations,
and run the analysis (calculating the average density). In order to run
these flow operations on a cluster with a job scheduler, it will be
necessary to edit the files under
hfcs-fffit/runs/r32-density-iter1/templates/ to be compatible with
your cluster. The signac documentation contains the necessary details.
Once the first iteration of simulations have completed (i.e., all the flow
operations are done), you can perform analysis. The necessary files are located
under hfcs-fffit/runs/analysis and hfcs-fffit/runs/analysis/r32-density-iter1.
The first step is to extract the results from your signac project into a CSV file
so they can be stored and accessed more easily in the future. This step is
performed by extract_r32_density.py. The script requires the iteration number
as a command line argument.
WARNING: Running this script will overwrite your local copy of our simulation results (stored as CSV files) with the results from your simulations.
To extract the results for iteration 1 run the following:
cd hfcs-fffit/analysis/
python extract_r32_density.py 1The CSV file with the results is saved under
hfcs-fffit/analysis/csv/rXX-YY-iterZZ-results.csv where XX
is the molecule, YY is the stage (liquid density or VLE), and
ZZ is the iteration number.
The analysis is performed within a separate directory for each iteration.
For example, for the first iteration, it is performed under
hfcs-fffit/analysis/r32-density-iter1. The script id-new-samples.py
loads the results from the CSV file, fits the SVM classifier and GP surrogate
models, loads the Latin hypercube with 1e6 prospective parameter sets,
and identifies the 200 new parameter sets to use for molecular simulations in
iteration 2. These parameter sets are saved to a CSV file:
hfcs-fffit/analysis/csv/r32-density-iter2-params.csv.
The second iteration of the liquid density simulations were
performed under the hfcs-fffit/runs/r32-density-iter2/. The procedure
is the same as for iteration 1, but this time the force field parameters
are taken from: hfcs-fffit/analysis/csv/r32-density-iter2-params.csv.
The procedure for analysis is likewise analogous to iteration 1, however,
note that in training the surrogate models,
hfcs-fffit/runs/analysis/r32-density-iter2/id-new-samples.py now uses
the simulation results from both iterations 1 and 2.
The optimization for the vapor-liquid equilibrium iterations is very similar.
The final (iteration 4) liquid density analysis saves the parameters as
hfcs-fffit/analysis/csv/r32-vle-iter1-params.csv. The first VLE iteration
begins with these parameters. Once again, the simulations are performed under:
hfcs-fffit/runs/r32-vle-iter1. The init.py is used to set up the
signac workspace, and project.py defines the simulation workflow
(create the inputs, perform the molecular simulations, and run the analysis).
The results are extracted into the CSV file with
hfcs-fffit/analysis/extract_r32_vle.py. Once again the iteration number
is a command line argument, and the results are saved to a CSV file
hfcs-fffit/analysis/csv/r32-vle-iter1-results.csv.
Each VLE iteration has a folder with the analysis
scripts (e.g., hfcs-fffit/analysis/r32-vle-iter1). The analysis.py
and evaluate-gps.py perform basic analysis and create figures evaluating
the performance of the GP models. The id-new-samples.py loads a Latin
hypercube with 1e6 prospective parameter sets, and identifies the top-performing
parameter sets which will be evaluated with molecular simulations during the
subsequent iteration. For example, the parameter sets to be used for the second
VLE iteration are saved to hfcs-fffit/analysis/csv/r32-vle-iter2-params.csv.
Each subsequent VLE iteration is performed in the same manner.
This work was supported by the National Science Foundation under grant NSF Award Number OAC-1835630 and NSF Award Number CBET-1917474. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.