.. _dl-field:

********
DL_FIELD
********

DL_FIELD is an external tool that can generate classical forcefields. When integrated with ChemShell, it can be used to generate the 
forcefields needed for QM/MM models directly. DL_FIELD is free for academic users and the registration form is available
here https://www.ccp5.ac.uk/dl_field-registration/. Presently, the use of DL_FIELD is only supported in combination with DL_POLY
as the MM theory.

DL_FIELD makes a distinction between organic and inorganic forcefields.

.. py:class:: DL_FIELD


General options
===============

.. py:attribute:: dl_poly

   (default: ``True``) Generate output forcefields in DL_POLY FIELD format

.. py:attribute:: ff

   Forcefield (ff) scheme. The options available will depend on the version of DL_FIELD.

   Allowed values:

   * ``'CHARMM'``: (default) All-atom CHARMM
   * ``'CHARMM22_prot'``: CHRMM22 for proteins
   * ``'CHARMM36_prot'``: CHARMM36 for amino acids, proteins
   * ``'CHARMM36_nucl'``: CHARMM36 for nuclei acids
   * ``'CHARMM36_lipid'``: CHARMM36 for lipids
   * ``'CHARMM36_carb'``: CHARMM36 for carbohydrates
   * ``'CHARMM36_cgenff'``: CHARMM general force field
   * ``'CHARMM19'``: United-atom for CHARMM
   * ``'AMBER'``: All-atom Amber
   * ``'AMBER16_gaff'``: AMBER general force field
   * ``'OPLSAA'``: OPLS-AA
   * ``'OPLS2005'``: OPLS_2005
   * ``'OPLS_AAM'``: OPLS AA/M for proteins
   * ``'OPLS_CL_P'``: CL&P for ionic liquids
   * ``'OPLS_DES'``: OPLS for deep eutectic solvent
   * ``'DREIDING'``: DREIDING
   * ``'PCFF'``: Polymer consistent force field
   * ``'CVFF'``: Consistent Valence Force Field
   * ``'COMPASS'``: COMPASS force field
   * ``'TRAPPE_EH'``: Transferable potentials (explicit hydrogen) for phase equilibria
   * ``'TRAPPE_UA'``: Transferable potentials (united atom) for phase equilibria
   * ``'G54A7'``: Gromos united atom G54A7
   * ``'INORGANIC_binary_oxide'``: Inorganic FF for binary oxides
   * ``'INORGANIC_ternary_oxide'``: Inorganic FF for ternary oxides
   * ``'INORGANIC_binary_halide'``: Inorganic FF for binary halides
   * ``'IORGANIC_glass'``: Inorganic FF for glass
   * ``'INORGANIC_clay'``: Inorganic FF for clay
   * ``'INORGANIC_zeolite'``: Inorganic FF for zeolite
   * ``'INORGANIC_zeolite_HS'``: Zeolite Hill-Sauer
   * ``'MISC_FF'``: Non-specific, miscellaneous FF
   * ``'multiple'``: Multiple potential

   .. note:: This list is for version 4.12 of DL_FIELD

.. py:attribute:: unit

   Energy unit for the output forcefield file
   
   Allowed values:

   * ``'kcal/mol'``: (default) Kilocalorie per mole
   * ``'eV'``: Electron volts
   * ``'kJ/mol'``: Kilojoule per mol
   * ``'K'``: Kelvin

.. note This option is only relevant for forcefields written in DL_POLY format

.. py:attribute:: conversion

   DL_FIELD determines the bond connections of a molecule based on atomic     distance criteria, where a bond is identified if two atoms are within a 
   certain minimum distance.

   Allowed values:

   * ``'normal'``: (default) Default distance criteria used to identify bonds.
   * ``'strict'``: Distance for bond indentification is reduced by 0.01 Å.
   * ``'loose'``: Distance for bond indentification is increased by 0.01 Å.

.. py:attribute:: udff

   (default: ``None``) Name of User-defined Force Field (udff) file, as described in the DL_FIELD manual. DL_FIELD udff files are used to
   add new paramaters and molecular templates to DL_FIELD, and will overwrite information in DL_FIELD's internal library files.

.. py:attribute:: verbosity

   (default: ``True``) Verbosity mode. When this is switched on, DL_FIELD will display detailed conversion process information, 
   including the converted atom types.

.. py:attribute:: input

.. py:attribute:: output

.. py:attribute:: optimise

   (default: ``True``) If the output forcefield file should be optimised by DL_FIELD.
   
   .. note This option is only relevant for forcefields written in DL_POLY format

.. py:attribute:: override_builtin

   (default: ``False``) Specifies whether user-defined parameters should override those of the standard forcefield.

.. py:attribute:: atom_display

   ATOM_KEY display format. This setting allows user to select the display format for the ATOM_KEYs in FF files generated by DL_FIELD.

   Allowed values:

   * ``'standard'``: (default) standard format according to the type of potential scheme selected
   * ``'dl_field'``: dl_f_notation atom notation

.. py:attribute:: vdw_format

   (default ``'12-6'``)

.. py:attribute:: eps_org

   (default ``'arithmatic'``)

.. py:attribute:: sig_org

   (default ``'arithmatic'``)

.. py:attribute:: eps_diff

   (default ``''arithmatic'``)

.. py:attribute:: sig_diff

   (default ``''arithmatic'``)

.. py:attribute:: extra_info

   (default ``False``)  Display additional information (for DL_POLY FF files only). This setting allows the 
   option to display additional information in a PDB file in dl_poly.CONFIG and 
   dl_poly.FIELD files, such as the amino acid residue sequence obtained from the user’s protein PDB file.

.. py:attribute:: freeze

.. py:attribute:: tether

.. py:attribute:: constrain

.. py:attribute:: rigid_body

.. py:attribute:: pbc

   (default: 0) Periodic boundary conditions.

.. py:attribute:: scale_coul

   (default:``'default'``) 1-4 scaling for coulombic interaction

.. py:attribute:: scale_vdw

.. py:attribute:: recentre

.. py:attribute:: distance

.. py:attribute:: min_distance

.. py:attribute:: mm_energy

.. py:attribute:: cutoff_coulomb

.. py:attribute:: cutoff_vdw

.. path_lib Not implemented yet

.. path_sol Not implemented yet

.. path_out Not implemented yet

.. py:attribute:: filename

   (default: ``'_dl_field.pdb'``)

.. py:attribute:: exclude

   (default: ``[]``)

.. py:attribute:: qmatoms

   (default: ``[]``)

.. py:attribute:: solvents

   (default: ``[]``)

.. py:attribute:: remove_unused_definitions

   (default: ``True``) Remove unused residue entries.

.. py:attribute:: original_tip3p

   (default: ``False``) Use the original TIP3P water model (rather than the default, TIP3P modified for CHARMM)

.. py:attribute:: directory

   (default: ``'_dl_field'``) Archive directory name for DL_FIELD inputs and outputs.

.. py:attribute:: field_by_chemsh

   (default: ``True``) We deal with the QM/MM special treatments with ChemShell instead of DL_FIELD

.. py:attribute:: run_only_once

   (default: ``True``) Run DL_FIELD only for the first step of an optimisation (otherwise DL_FIELD will be run every step). This option should be
   used when the forcefield is not expected to be updated as atoms move in the simulation.

.. py:attribute:: patch_target

   (default: ``{}``) Dictionary containing targets for patching fragments.

.. charges_by_chemsh TD 03/10/2025: Does this work? Doesn't look connected to me, but I could be wrong

Organic ff options
==================

.. py:attribute:: sig_org

    Specify mixing rule for the parameter sigma (steric parameter) for LJ12-6 between two atoms.

   Allowed values:

   * ``'arithmatic'``: (default)
   * ``'geometric'``:
   * ``'default'``: 


Inorganic ff options
====================

The following options only apply to DL_FIELD's inorganic forcefields

.. py:attribute:: eps_inorg

   Specify mixing rule for the parameter epsilon (potential well-depth) for LJ12-6 between two atoms. 

   Allowed values:

   * ``'geometric'``: (default) 
   * ``'arithmatic'``:

.. py:attribute:: sig_inorg

   Specify mixing rule for the parameter sigma (steric parameter) for LJ12-6 between two atoms.

   * ``'geometric'``: (default) 
   * ``'arithmatic'``:


Dreiding ff options
===================

The following options are specific to the Dreiding forcefield.

.. py:attribute:: bond

   Dreiding bond type.

   Allowed values:

   * ``'harmonic'``: (default) Harmonic bond
   * ``'morse'``: Morse bond

.. py:attribute:: angle

   Dreiding angle type.

   Allowed values:

   * ``'harmonic'``: (default) Harmonic angle
   * ``'cos'``: Harmonic cos angle


Initial velocities options
==========================
   
.. py:attribute:: velocity

   (default: ``False``) Assign initial Gaussian random velocities, scaled to a temperature, to every atom in the output dl_poly.CONFIG file.

.. py:attribute:: temperature

   (default: ``300.0``) Temperature for initial velocities.


Solvation options
=================

The following options only apply to DL_FIELD's solvation functionality

.. warning:: The solvation features of DL_FIELD are not supported by ChemShell

.. py:attribute:: solvent

.. py:attribute:: solution

   Solution Maker on/off

.. py:attribute:: solution_den

   Solution Maker density

.. py:attribute:: solution_unit

   Solution Maker unit

.. py:attribute:: solution_cutoff

   Solution Maker cutoff

.. py:attribute:: counterions

   Add counter ions