ffaffurr-dev

Introduction

FFAFFURR is a Python tool, which enables the parametrization of OPLS-AA and CTPOL model. It is shorten for Framework For Adjusting Force Fields Using Regularized Regression.

Requirements

• python 3
• OpenMM 7.7.0
• pyswarm (The installation of pyswarm can be found here)
• Numpy
• Pandas
• scipy
• sklearn

Input Files

• OPLS-AA.xml Because the goal is to "adjust" existing parameters of the OPLS-AA FF, it is reasonable to provide a standardized listing of parameters as input. Thus, parameter file "OPLS-AA.xml" is needed. For any system already set-up with OpenMM, e.g. when using the standard OPLS-AA FF parameters that are distributed with the OpenMM package, the standardized parameters and connectivity list are taken from the inner code of OpenMM by ffaffurr.py.
• input.pdb The "input.pdb" file is the basic coordinate file that OpenMM-readable.
• ffaffurr.input The input file "ffaffurr.input" contains the "switches" that control the behavior of the framework, e.g. what kind of parameters are to be "adjusted" or what regression model to use.
• ffaffurr.input.FHI-aims-logfiles the input file "ffaffurr.input.FHI-aims-logfiles" contains a list of FHI-aims-specific (https://fhi-aims.org/) output files produced when calculating single-point DFT energies. Obviously, these files must be produced for a set of conformers that serves as training data.
  • resp.chrg If RESP charges are specified in "ffaffurr.input", a seperate file 'resp.chrg' containing atomic RESP charges for each conformer should be included in the folders listed in ffaffurr.input.FHI-aims-logfiles.
  • energies_inter_DFT.dat and energies_minusIon_FF.dat If interaction energy is specified in "ffaffurr.input", a file 'energies_inter_DFT.dat' containing DFT interaction energy, and a file 'energies_minusIon_FF.dat' containing force filed energies of structures without ion.

Example Usage

An example of the usage of FFAFFURR is in the workingExample-AcCysNMe folder. The example should be run with the following command:

cd workingExample-AcCysNMe
python ../ffaffurr.py

List of input keywords

All the available keywords and their descriptions in ffaffurr.input are listed below. In ffaffurr.input, lines starting with “#” is a comment.

Choose original parameters

• Tag: readparamsfromffaffurr
  • Usage: readparamsfromffaffurr True/False
  • Purpose:

    • choose original parameters from
    • OPLS-AA.xml
    • (use: readparamsfromffaffurr False)
    • OR ffaffurr-oplsaa.xml.This is used to optimize parameters step by step.
    • (use: readparamsfromffaffurr True)

Choose the fitting type (Weighted or unweighted)

• Tag: boltzmann_weighted_fitting

  • Usage: boltzmann_weighted_fitting True/False
  • Purpose:

    • Boltzmann factors are of form: A * exp( - Ei_QM / RT)
    • A = normalization constant
    • Ei_QM = QM relative energy
    • RT = temperature factor
    • Boltzmann weighted fitting can be used
    • (use: readparamsfromffaffurr False)
    • OR unweighted fitting
    • (use: readparamsfromffaffurr False)

• Tag: temperature_factor

  • Usage: temperature_factor value
  • Purpose:

    • only if boltzmann_weighted_fitting = True:
    • set temperature factor (e.g. 32)

Keywords for bond parametrization

• Tag: fine_tune_r0
  • Usage: fine_tune_r0 True/False
  • Purpose:

    • bonding terms are of form: 0.5 kB (r-r0)^2^
    • kB = spring constant parameter
    • -> original FF parameters are used
    • (parameters not altered)
    • r0 = equlibrium bond length parameter between pair of atoms
    • -> original FF parameters can be used (parameters not altered)
    • (use: fine_tune_r0 False)
    • OR an average distance over all FHI-aims input logfiles is computed to estimate (fine-tune) r0
    • (use: fine_tune_r0 True)
    • -> this makes ONLY sense if geometrically optimized structures have been used in high-level input logfiles

Keywords for angle parametrization

• Tag: fine_tune_theta0
  • Usage: fine_tune_theta0 True/False
  • Purpose:

    • angles bending terms are of form: 0.5 Ktheta (theta-theta0)^2^
    • ktheta = spring constant parameter
    • -> original FF parameters are used
    • (parameters not altered)
    • theta0 = equlibrium angle parameter between triplet of atoms
    • -> original FF parameters can be used (parameters not altered)
    • (use: fine_tune_theta0 False)
    • OR an average angle over all FHI-aims input logfiles is computed to estimate (fine-tune) theta0
    • (use: fine_tune_theta0 True)
    • -> this makes ONLY sense if geometrically optimized
    • structures have been used in FHI-aims input logfiles

Keywords for torsion parametrization

• Tag: fine_tune_torsionalV

  • Usage: fine_tune_torsionalV False/Regression
  • Purpose:

    • torsion (dihedral angles) terms are of form: V * ( 1+cos( nθ − θ0) )
    • V = torsional parameter
    • -> original FF parameters can be used (parameters not altered)
    • (use: fine_tune_torsionalV False)
    • OR parameters can be assigned using regression from energies of FHI-aims input logfiles
    • (use: fine_tune_torsionalV Regression)
    • (n = periodicity, θ0 = phase offset, θ = dihedral angle)

• Tag: RegressionTorsionalVall

  • Usage: RegressionTorsionalVall True/False
  • Purpose:

    • only if fine_tune_torsionalV = Regression:
    • either ALL torsional parameters (V1, V2, V3) are considered in regrssion
    • (use: RegressionTorsionalVall True)
    • OR only torsional parameters are considered that are non-zero in original FF
    • (use: RegressionTorsionalVall False)
    • Note: cases for which V1 = V2 = V3 = 0 are never taken into account (those cases are usually quadruples that contain a hydrogen atom)

• Tag: Regression_torsionalV_Method

  • Usage: Regression_torsionalV_Method LinearRegression/Ridge/Lasso
  • Purpose:

    • only if fine_tune_torsionalV = Regression:
    • use linear regression
    • OR Ridge regression
    • OR Lasso regression

• Tag: regularization_parameter_torsionalV

  • Usage: regularization_parameter_torsionalV value
  • Purpose:

    • only if fine_tune_torsionalV = Regression AND Regression_torsionalV_Method = {Ridge/Lasso}:
    • set regularization parameter (e.g. 0.1)

Keywords for improper torsion parametrization

• Tag: fine_tune_imptorsionalV

  • Usage: fine_tune_imptorsionalV False/Regression
  • Purpose:

    • improper torsion terms are of form: V2imp ( 1+cos(2θ − θ0) )
    • V2imp = improper torsional parameter
    • -> original FF parameters are used (parameters not altered)
    • (use: fine_tune_imptorsionalV False)
    • OR parameters can be assigned using regression from energies of FHI-aims input logfiles
    • (use: fine_tune_imptorsionalV Regression)

• Tag: Regression_imptorsionalV_Method

  • Usage: Regression_imptorsionalV_Method LinearRegression/Ridge/Lasso
  • Purpose:

    • only if fine_tune_imptorsionalV = Regression:
    • use linear regression
    • OR Ridge regression
    • OR Lasso regression

• Tag: regularization_parameter_imptorsionalV

  • Usage: regularization_parameter_imptorsionalV value
  • Purpose:

    • only if fine_tune_imptorsionalV = Regression AND Regression_imptorsionalV_Method = {Ridge/Lasso}:
    • set regularization parameter (e.g. 0.1)

Keywords for LJ parametrization

• Tag: fine_tune_sigma

  • Usage: fine_tune_sigma False/TS
  • Purpose:

    • van der Waals (vdW; Lennard-Jones) terms are of form: 4epsilon f * [ (sigma/r)^12^ - (sigma/r)^6^ ]
    • f = 0 for 1-2-interactions and 1-3-interactions
    • f = 1/2 for 1-4-interactions
    • f = 1 for 1-5-interactions and higher
    • sigma = distance parameter at which the inter-particle potential is zero
    • -> original FF parameters can be used (parameters not altered)
    • (use: fine_tune_sigma False)
    • OR sigma is calculated from FHI-aims input logfiles using the Tkatchenko-Scheffler (TS) method
    • (use: fine_tune_sigma TS)

• Tag: fine_tune_epsilon

  • Usage: fine_tune_epsilon False/TS/RegressionTS/RegressionMBD/RegressionTot
  • Purpose:

    • epsilon = potential well depth parameter
    • -> original FF parameters can be used (parameters not altered)
    • (use: fine_tune_epsilon False)
    • OR epsilon is calculated from FHI-aims input logfiles using the Tkatchenko-Scheffler (TS) method
    • (use: fine_tune_epsilon TS)
    • OR epsilon parameters can be assigned using regression from TS energies of FHI-aims input logfiles
    • (use: fine_tune_epsilon RegressionTS)
    • OR epsilon parameters can be assigned using regression from MBD@rsSCS energies of FHI-aims input logfiles
    • (use: fine_tune_epsilon RegressionMBD)
    • (Note: I don't know if the latter two options are even useful since both those DFT energies are calculated using damping functions that in turn are parameterized against individual exchange-correlation functionals)
    • OR epsilon parameters can be assigned using regression from total energies of FHI-aims input logfiles
    • (use: fine_tune_epsilon RegressionTot)

• Tag: RegressionEpsilonMethod

  • Usage: RegressionEpsilonMethod LinearRegression/Ridge/Lasso
  • Purpose:

    • only if fine_tune_epsilon = Regression{TS/MBD/Tot}:
    • use linear regression
    • OR Ridge regression
    • OR Lasso regression

• Tag:regularization_parameter_epsilon

  • Usage: regularization_parameter_epsilon value
  • Purpose:

    • only if RegressionEpsilonMethod = {Ridge/Lasso}:
    • set regularization parameter (e.g. 0.1)

• Tag: RestrictRegressionEpsilonPositive

  • Usage: RestrictRegressionEpsilonPositive True/False
  • Purpose:

    • only if fine_tune_epsilon = Regression{TS/MBD/Tot} AND RegressionEpsilonMethod = Lasso:
    • restrict regression-fitted epsilon parameters to be positive
    • (use: RestrictRegressionEpsilonPositive True)
    • OR not (use: RestrictRegressionEpsilonPositive False)

• Tag: SetExplicitlyZero_vdW_SigmaEpsilon

  • Usage: SetExplicitlyZero_vdW_SigmaEpsilon True/False
  • Purpose:

    • only if finetune{sigma/epsilon} = TS:
    • some epsilon & sigma parameters might be zero in original FF
    • -> Do you want to also set them explicitly to zero even if you (re-)calculate/assign them using TS?
    • (use SetExplicitlyZero_vdW_SigmaEpsilon True)
    • OR not (use: SetExplicitlyZero_vdW_SigmaEpsilon False)

Keywords for electrostatic parametrization

• Tag: fine_tune_charge

  • Usage: fine_tune_charge False/Hirshfeld/ESP/RESP
  • Purpose:

    • Coulomb terms are of form: f q1q2 / r12
    • f = 0 for 1-2-interactions and 1-3-interactions
    • f = 1/2 for 1-4-interactions
    • f = 1 for 1-5-interactions and higher
    • q1,q2 = partial charge parameters of atoms
    • -> original FF parameters can be used (parameters not altered)
    • (use: fine_tune_charge False)
    • OR partial charge parameters can be assigned using Hirshfeld charges from FHI-aims input logfiles
    • (use: fine_tune_charge Hirshfeld)
    • OR partial charge parameters can be assigned using ESP charges from FHI-aims input logfiles
    • (use: fine_tune_charge ESP)
    • OR partial charge parameters can be assigned using RESP charges from external RESP charge files
    • (use: fine_tune_charge RESP)

• Tag: fine_tune_Coulomb_fudge_factors

  • Usage: fine_tune_Coulomb_fudge_factors True/False
  • Purpose:

    • Coulomb fudge factors are of form (in original OPLS-AA FF):
    • f = 0 for 1-2-interactions and 1-3-interactions
    • f = 1/2 for 1-4-interactions
    • f = 1 for 1-5-interactions and higher
    • -> original fudge factors can be used (fudge factors not altered)
    • (use: fine_tune_Coulomb_fudge_factors False)
    • OR fudge factors can be assigned using linear regression from total energies of FHI-aims input logfiles
    • (use: fine_tune_Coulomb_fudge_factors True)

• Tag: fine_tune_only_f14

  • Usage: fine_tune_only_f14 True/False
  • Purpose:

    • only if fine_tune_Coulomb_fudge_factors = True:
    • general OPLS-AA form: Ecoul = f_14 Ecoul(1-4) + f_15 Ecoul(1-5)
    • --> f_14 = fudge factor for 1-4-interactions (default: 0.5)
    • --> f_15 = fudge factor for 1-5-interactions (default: 1.0)
    • -> estimate f_14 and f_15
    • (use: fine_tune_only_f14 False)
    • OR estimate ONLY f_14
    • (use: fine_tune_only_f14 True)

Keywords for charge transfer parametrization

• Tag: fine_tune_charge_transfer

  • Usage: fine_tune_charge_transfer False/Tot/Inter/ChargeDistr/ESP
  • Purpose:

    • Charge transfers are of form CN * (1/alpha) (a * r + b):
    • CN = coordination number
    • a = slope of charge transfer
    • b = offset of charge transfer
    • -> don't consider charge transfer
    • (use: fine_tune_charge_transfer False)
    • OR fitting charge transfer params to total energies of FHI-aims input logfiles
    • (use: fine_tune_charge_transfer Tot)
    • OR fitting charge transfer params to interaction energies of FHI-aims input logfiles
    • (use: fine_tune_charge_transfer Inter)
    • OR fitting charge transfer params to charge distribution of FHI-aims input logfiles
    • (use: fine_tune_charge_transfer ChargDistr)
    • alpha, a, b are obtained by partical swarm optimizaiton(PSO)
    • OR fitting charge transfer params to electrostatic potentials of FHI-aims outputs
    • (use: fine_tune_charge_transfer ESP)

• Tag: ChargeTransferESPMethod

  • Usage: ChargeTransferESPMethod PSO/Ridge/Lasso
  • Purpose:

    • only if fine_tune_charge_transfer = ESP:
    • use PSO
    • OR Ridge regression
    • OR Lasso regression

• Tag: regularization_parameter_CharTran

  • Usage: regularization_parameter_CharTran value
  • Purpose:

    • only if ChargeTransferESPMethod = {Ridge/Lasso}:
    • set regularization parameter (e.g. 0.1)

• Tag: number_of_pso_CT

  • Usage: number_of_pso_CT value
  • Purpose:

    • only if fine_tune_charge_transfer = Tot/Inter/ChargDistr OR ChargeTransferESPMethod = PSO:
    • set the number of independent PSO running (e.g. 1).

• Tag: number_of_processes_CT

  • Usage: number_of_processes_CT value
  • Purpose:

    • only if fine_tune_charge_transfer = Tot/Inter/ChargDistr OR ChargeTransferESPMethod = PSO:
    • set the number of processes( e.g. 2. if processes > 1, then pso is paralleled)

• Tag: fine_tune_isolated_charges

  • Usage: fine_tune_isolated_charges False/Hirshfeld/ESP/RESP
  • Purpose:

    • only if fine_tune_charge_transfer = Tot/Inter/ChargDistr OR ChargeTransferESPMethod = PSO:
    • charges of atoms before charge transfer:
    • -> original FF parameters can be used
    • (use: fine_tune_isolated_charges False)
    • OR Hirshfeld charges
    • (use: fine_tune_isolated_charges Hirshfeld)
    • OR ESP charges
    • (use: fine_tune_isolated_charges ESP)
    • OR RESP charges
    • (use: fine_tune_isolated_charges RESP)

• Tag: fine_tune_charges_distribution

  • Usage: fine_tune_charges_distribution Hirshfeld/ESP/RESP
  • Purpose:

    • only if fine_tune_charge_transfer = ChargDistr:
    • charges distribution of fhiaims:
    • -> Hirshfeld charges
    • (use: fine_tune_isolated_charges Hirshfeld)
    • OR ESP charges
    • (use: fine_tune_isolated_charges ESP)
    • OR RESP charges
    • (use: fine_tune_isolated_charges RESP)

• Tag: fine_tune_starting_points

  • Usage: fine_tune_starting_points False/file_name
  • Purpose:

    • only if fine_tune_charge_transfer = Tot/ChargDistr OR ChargeTransferESPMethod = PSO:
    • choose starting points of PSO:
    • -> generate random points as starting points
    • (use: fine_tune_starting_points False)
    • OR define some of the starting points
    • (use: fine_tune_starting_points FILE_OF_THE_STARTING_POINTS. e.g. CT_initial)

Keywords for polarization parametrization

• Tag: fine_tune_polarization_energy

  • Usage: fine_tune_polarization_energy True/False
  • Purpose:

    • Polarization terms are of form -0.5 Alpha E * E0 :
    • Alpha = polarizability of atoms
    • E = total electrostatic field produced by atomic charges and induced dipole
    • E0 = electrostatic field produced by charges in the system
    • -> polarization energy can be included in force field
    • (use: fine_tune_polarization_energy True)
    • OR not (use: fine_tune_polarization_energy False)

• Tag: fine_tune_polarizabilities

  • Usage: fine_tune_polarizabilities True/False
  • Purpose:

    • only if fine_tune_polarization_energy = True:
    • atomic polarizabilities:
    • -> polarizabilities can be calculated from FHI-aims
    • (use: fine_tune_polarizabilities False)
    • OR can be assigned using particle swarm optimization
    • (use: fine_tune_polarizabilities True)

• Tag: number_of_pso_POL

  • Usage: number_of_pso_POL value
  • Purpose:

    • only if fine_tune_polarizabilities = True:
    • set the number of independent PSO running (e.g. 1)

• Tag: number_of_processes_POL

  • Usage: number_of_processes_POL value
  • Purpose:

    • only if fine_tune_polarizabilities = True:
    • set the number of processes( e.g. 2. if processes > 1, then pso is paralleled)

Outputs

• ffaffurr-oplsaa.xml "ffaffurr-oplsaa.xml" includes all the parameters in standard OPLS-AA FF.
• CustomForce.xml "CustomForce.xml" includes charge transfer and polarization parameters.

Contact

Any feedback, questions, bug reports should be report through the Issue Tracker.

License

This package is provided under license:

Citation

When using FFAFFURR in published work, please cite the following paper: