New Control Files

Introduction

As of DLPOLY 4.11, there is a new refactored form of control (henceforth new-style). The primary motivation behind this change is an overall improvement in consistency of keywords for the purpose of allowing easier automation of DLPOLY jobs. The revisions confer several additional benefits, however, for both users and developers. These include, but are not limited to:

  • More easily extensible hash-table based control

  • New control parameter allows definition of defaults, internal units and a description

  • Searchable keyword help for keyword description

  • Consistent “keyword value unit” scheme for all keywords

  • Automated and generalised unit parsing and conversion scheme

  • More standardised naming scheme

  • Only reads control file once in one location

  • Decomposed reading routines for easier handling and addition of new parameters

  • Writing routines for parameters independent of reading

  • Warnings during reading are directed to the top of output file

  • Restructured indentation-based parameter output for easier parsing

The standard form of the new control is that of:

keyword value [unit]

All new-style control parameters are of this form.

Values are required if a keyword is present. Units are required for non-dimensionless data.

Keywords

Keywords in new-style control only have one value and attempt to only affect one thing, this means that what, in old-style, might be a single keyword will be subdivided into multiple parameters in new-style. An example of this is the ensemble parameter, which previously might be rendered as:

ensemble nvt hoover 1.0

will, in new-style, be rendered:

ensemble nvt
ensemble_method hoover
ensemble_thermostat_coupling 1.0 ps

Value types

New-style control divides control parameters into distinct classes of parameters depending on how they should be handled by the parser. These are scalar types int, float, bool, string, and option, or vector types int, float, and string. These are easily extensible and in future more may be added by developers.

Int

These values, identified by the DATA_INT enumeration, are simple integer values. There is also a special case for unit-converted integer values for steps values (see Section: Units).

vaf_binsize 21

Floats

These values, identified by the DATA_FLOAT enumeration, are generally dimensioned real data and will be converted between input and internal units when read.

analyse_max_dist 2.0 ang

Vector

These values, identified by the DATA_INT_VECTOR, DATA_FLOAT_VECTOR or DATA_STRING_VECTOR enumerations, are connected sets of data which may be either ints, floats, or strings, e.g.

pressure_tensor [ 1.0 2.0 3.0 4.0 5.0 6.0 ] GPa
spme_kvec [ 32 64 32 ]
correlation_observable [v_x-v_x v_y-v_y v_z-v_z]

Vector data may have a particular size requirement, as is the case for pressure_tensor (6), or may be unbounded as is the case for correlation_observable.

Bool

These values, identified by the DATA_BOOL enumeration, are binary options which are set by “On” or “Off”

vdw_force_shift ON

String

These values, identified by the DATA_STRING enumeration, are arbitrary strings of characters usually used for setting filepaths, however, they may have special options such as SCREEN or NONE to specify override their function.

io_file_config CONTROL.new
io_file_output SCREEN

Option

These values, identified by the DATA_OPTION enumeration, would otherwise be indistinguishable from strings, however, they are differentiated by the fact that there are number of expected values to switch between.

coul_method dddp

Units

The automatic units conversion allows the user to enter any dimensionally correct physical unit as input to allow ease and complete flexibility. Units can be entered in a natural manner with decimal prefixes.

Units are case insensitive, however decimal prefixes are case sensitive.

Units can be combined using a full stop (period) [.] for product or slash [/] for quotients or raised to an exponent with a caret [^]

2.0 e.V
1.0 m/s
3.0 ang^3

for 2 electron-volts, 1 metre per second & 3 cubic Ångströms respectively.

Decimal prefixes are applied directly to the unit they affect.

2.0 GPa
3.0 ang/ps

for 2 Gigapascals & 3 Ångströms per picosecond respectively.

The special unit “steps” is derived from the timestep parameter and will be automatically converted to/from to allow consistent run-lengths.

timestep 2.0 fs
time_run 30 steps
time_run 60.0 fs

will mean the calculation will perform 30 steps of 2 fs (60fs) and alternatively 60fs regardless of the timestep.

Adding new keywords

New keywords should be added to the parameters hash in initialise_control in the style:

call table%set("<keyword>", control_parameter( &
     key = "<keyword>", &
     name = "<human-readable-full-name>", &
     val = "<default-value>", &
     units = "<units-of-default>", &
     internal_units = "<units-to-use-internally>", &
     description = "<description-for-help>", &
     data_type = <data-type>))

where values in <> are to be filled in, and data-type is one of DATA_INT, DATA_FLOAT, DATA_STRING, DATA_BOOL, DATA_OPTION, DATA_INT_VECTOR, DATA_FLOAT_VECTOR, DATA_STRING_VECTOR and other relevant data is filled in.

Vector values must either have variable_length=.true. or a specified length in the call to table%set.

If your data is unitless, you can remove the units and internal_units entries and they will default to unitless.

Keywords to be parsed in initialise_control are grouped into named blocks for ease of maintaining these, ensure your keyword is appropriately grouped either into one of these or its own relevant block.

Once the data exists in the parameters table (through initialise_control) it is ready to be read in and searched for through the help functions.

The next step is to retrieve the parsed keyword, there are various functions to subdivide reading to increase maintainability and reduce argument lists to workable levels. Within an appropriate read function, call the following function:

call params%retrieve("<keyword>", <storage>)

where <storage> is the variable (of an appropriate type) to store the data. Any necessary unit or data conversion will be performed by the retrieval automatically. If the keyword is not present in control, it will default to “<default-value> <default-units>” as specified in the table entry.

Note

Only floats, vectors and ints in units of steps will act upon units.

Following this, the information should be added to the write function corresponding to the read function for ease of maintainability. It should be noted that written data should be appropriately indented.

Note

Should you be writing a lot of information, it may be best to hide the information printing behind the print level via:

Call info(message, .true., level=N)

where higher N requires the print_level variable to be a higher value (default=2).

Going from old to new

For most cases to go from old to new, it should be a simple case of using the dlpoly-py tool (Available from: https://gitlab.com/drFaustroll/dlpoly-py/) and using the old2new tool in the tools directory through:

<path-to-old2new>/old2new.py CONTROL

which will create/overwrite CONTROL.new.

Old keyword

New Keyword(s)

l_scr

io_file_output SCREEN

l_tor

io_file_revcon NONE

io_file_revive NONE

l_eng

output_energy ON

l_rout

io_write_ascii_revive ON

l_rin

io_read_ascii_revive ON

l_print

print_level

l_dis

initial_minimum_separation

l_fast

unsafe_comms ON

adf \(i~j\)

adf_calculate ON

adf_frequency \(i\) steps

adf_precision \(j\)

analyse all (sampling) (every) \(f\) nbins \(n\) rmax \(r\)

analyse_all ON

analyse_frequency \(f\) steps

analyse_max_dist \(r\) ang

analayse_num_bins \(n\)

ana (bon \(|\) ang \(|\) dih \(|\) inv) (sampling) (every) \(f\) nbins \(n\)

analyse_(bonds\(|\)angles\(|\)dihedrals\(|\)inversion) ON

analyse_frequency_(bonds\(|\)angles\(|\)dihedrals\(|\)inversion) \(f\) steps

analyse_num_bins_(bonds\(|\)angles\(|\)dihedrals\(|\)inversion) \(n\)

binsize \(f\)

rdf_binsize \(f\) ang

zden_binsize \(f\) ang

cap (forces) \(f\)

equilibration_force_cap \(f\) k_B.temp/ang

close time \(f\)

time_close \(f\) s

job time \(f\)

time_job \(f\) s

Note: Defaults to 1e304

coord \(i~j~f\)

coord_calculate ON

coord_ops (icoord:math:|ccoord\(|\)full)

coord_start \(j\) steps

coord_interval \(f\) steps

collect

record_equilibration

coul\(|\)distan\(|\)reaction\(|\)shift

coul_method (dddp:math:|pairwise\(|\)reaction_field\(|\)force_shifted)

shift damp \(\alpha{}\)

coul_damping \(\alpha{}\) 1/ang

reaction damp \(\alpha{}\)

shift precision \(f\)

coul_precision \(f\)

reaction precision \(f\)

cutoff \(f\) (\(\equiv\) rcut \(f\))

cutoff \(f\) ang

defects \(i~j~f\)

defects_calculate ON

defects_start \(j\) steps

defects_interval \(f\) steps

defects_distance \(f\) ang

delr \(f\) (\(\equiv\) rpad \(4f\))

removed (see: padding)

densvar \(f\)

density_variance \(f\) %

displacements \(i~j~f\)

displacements_calculate ON

displacements_start \(j\) steps

displacements_interval \(f\) steps

displacements_distance \(f\) ang

dump \(n\)

data_dump_frequency \(n\) steps

ensemble (nve\(|\)nvt\(|\)npt\(|\)nst)

ensemble (nve:math:|nvt\(|\)npt\(|\)nst)

evans

ensemble_method evans

langevin \(f\)

ensemble_method langevin

ensemble_thermostat_friction \(f\) 1/ps

andersen \(f_{1}~f_{2}\)

ensemble_method andersen

ensemble_thermostat_coupling \(f_{1}\) ps

ensemble_thermostat_softness \(f_{2}\)

berendsen \(f\)

ensemble_method berendsen

ensemble_thermostat_coupling \(f\) ps

hoover \(f\)

ensemble_method (hoover:math:|nose\(|\)nose-hoover)

ensemble_thermostat_coupling \(f\) ps

gst \(f_{1}~f_{2}\)

ensemble_method (gentle:math:|gst)

ensemble_thermostat_coupling \(f_{1}\) ps

ensemble_thermostat_friction \(f_{2}\) 1/ps

ttm\(|\)inhomo \(f_{1}~f_{2}~f_{3}\)

ensemble_method ttm

ttm_e-phonon_friction \(f_{3}\) 1/ps

ttm_e-stopping_friction \(f_{2}\) 1/ps

ttm_e-stopping_velocity \(f_{3}\) ang/ps

dpd s1 \(gamma\)

ensemble_method dpd

ensemble_dpd_order (1:math:|first)

ensemble_dpd_drag \(gamma\) Da/ps

dpd s2 \(gamma\)

ensemble_method dpd

ensemble_dpd_order (2:math:|second)

ensemble_dpd_drag \(gamma\) Da/ps

epsilon \(f\)

coul_dielectric_constant \(f\)

equilibration (steps) \(f\)

time_equilibration \(f\) steps

spme precision \(f\)

coul_method spme

spme_precision \(f\)

spme (sum) \(\alpha~k_{1}~k_{2}~k_{3}\)

coul_method spme

spme_alpha \(\alpha{}\)

spme_kvec [ \(k_{1}~k_{2}~k_{3}\) ]

exclude

coul_extended_exclusion ON

finish

removed

heat_flux

heat_flux ON

impact \(i~j~~~E~~x~y~z\)

impact_part_index \(i\)

impact_time \(j\) steps

impact_energy \(E\) ke.V

impact_direction [ \(x~y~z\) ]

nfold \(i~j~k\) no elec

coul_method off

no index

ignore_config_indices ON

no strict

strict_checks OFF

no topology

print_topology_info OFF

no vafaveraging

vaf_averaging OFF

no vdw

vdw_method OFF

no vom

fixed_com ON

metal direct

metal_direct ON

metal sqrtrho

metal_sqrtrho ON

minimise string \(n\) \(f\) \(s\)

minimisation_criterion (off:math:|force\(|\)energy\(|\)distance)

optimise string \(f\) \(s\)

minimisation_frequency \(n\) steps

minimisation_tolerance \(f\) (internal_f:math:|internal_e\(|\)ang)

minimisation_step_length \(s\) ang

msdtmp \(i~j\)

msd_calculate ON

msd_start \(i\) steps

msd_interval \(i\) steps

padding \(f\) (\(\equiv\) rpad \(f\))

padding \(f\) ang

plumed string (on:math:|off)

plumed (ON:math:|OFF)

plumed input \(<\)\(filename\)\(>\)

plumed_input \(<\)\(filename\)\(>\)

plumed log \(<\)\(filename\)\(>\)

plumed_log \(<\)\(filename\)\(>\)

plumed precision \(int\)-\(val\)

plumed_precision \(int\)-\(val\)

plumed restart string (yes:math:|no)

plumed_restart (ON:math:|OFF)

polarisation scheme/type thole \(f\)

polarisation_model (charmm:math:|default)

polarisation_thole \(f\)

pressure \(f\)

pressure_hydrostatic \(f\) katm

pressure tensor \(xx~yy~zz~xy~xz~yz\)

pressure_tensor [\(xx~yy~zz~xy~xz~yz\)] katm

pressure_perpendicular \(xx~yy~zz\) katm

pp_dump

write_per_particle ON

print (every) \(n\)

print_frequency \(n\) steps

print analysis

removed

print rdf

rdf_print ON

print vaf

vaf_print ON

print zden

zden_print ON

pseudo string \(f_{1}~f_{2}\)

pseudo_thermostat_method (off:math:|langevin-direct\(|\)langevin\(|\)gaussian\(|\)direct)

pseudo_thermostat_width \(f_{1}\) ang

pseudo_thermostat_temperature \(f_{2}\) K

quaternion (tolerance) \(f\)

removed

rdf (sampling) (every) \(f\)

rdf_frequency \(f\) steps

regauss (every) \(n\)

regauss_frequency \(n\) steps

replay (history)

Now command line option

restart (\(|\)noscale\(|\)scale)

restart (clean:math:|continue\(|\)rescale\(|\)noscale)

rlxtol \(f\) \(s\)

rlx_tol \(f\) internal_f

rlx_cgm_step \(s\) ang

rvdw (cutoff) \(f\)

vdw_cutoff \(f\) ang

scale (temperature) (every) \(f\)

rescale_frequency \(f\) steps

seed \(n_{1}~n_{2}~n_{3}\)

random_seed [\(n_{1}~n_{2}~n_{3}\) ]

slab

removed

stack (size) \(n\)

stack_size \(n\) steps

stats (every) \(n\)

stats_frequency \(n\) steps

steps \(n\)

time_run \(n\) steps

subcelling (threshold) (density) \(f\)

subcell_threshold \(f\)

temperature \(f\)

temperature \(f\) K

trajectory \(i~j~k\)

traj_calculate ON

traj_start \(i\) steps

traj_interval \(j\) steps

traj_key (pos:math:|pos-vel\(|\)pos-vel-force\(|\)compressed)

ttm amin \(n\)

ttm_min_atoms \(n\)

ttm bcs \(Q\)

ttm_boundary_condition (periodic:math:|dirichlet\(|\)neumann\(|\)robin)

ttm_boundary_xy (ON:math:|OFF)

ttm_boundary_heat_flux \(f\) %

ttm ceconst \(f\)

ttm_heat_cap_model (constant:math:|tanh\(|\)linear\(|\)tabulated)

ttm cetab

ttm_heat_cap \(f|f_{1}\) internal_e/amu/K

ttm celin \(f_{1}~f_{2}\)

ttm_fermi_temp \(f_{2}\) K

ttm cetanh \(f_{1}~f_{2}\)

ttm_temp_term \(f_{2}\) K^-1

ttm deconst\(|\)diff \(f\)

ttm_diff_model (constant:math:|reciprocal\(|\)tabulated)

ttm derecip \(f_{1}~f_{2}\)

ttm_diff \(f|f_{1}\) m^2/s

ttm detab

ttm_fermi_temp \(f_{2}\) K

ttm dedx \(f\)

ttm_stopping_power \(f\) e.V/nm

ttm dyndens

ttm_dens_model (constant:math:|dynamic)

ttm atomdens \(f\)

ttm_dens \(f\) ang^-3

ttm keconst \(f\)

ttm_elec_cond_model (infinite:math:|constant\(|\)drude\(|\)tabulated)

ttm kedrude \(f\)

ttm_elec_cond \(f\) W/m/K

ttm keinf

ttm ketab

ttm delta

ttm_temporal_dist delta

ttm pulse \(f\)

ttm_temporal_duration \(f|f_{1}\) ps

ttm gauss \(f_{1}~f_{2}\)

ttm_temporal_cutoff \(f_{2}\) ps

ttm nexp \(f_{1}~f_{2}\)

ttm sflat

ttm_spatial_dist flat

ttm sgauss \(f_{1}~f_{2}\)

ttm_spatial_dist gaussian

ttm sigma \(f_{1}~f_{2}\)

ttm_spatial_sigma \(f_{1}\) nm

ttm_spatial_cutoff \(f_{2}\) nm

ttm laser \(f_{1}~f_{2}\)

ttm_spatial_dist laser

ttm laser \(f_{1}~f_{2}~\textbf{zdep}\)

ttm_laser_type (flat:math:|exponential)

ttm_fluence \(f_{1}\) mJ/cm^2

ttm_penetration_depth \(f_{2}\) nm

ttm metal

ttm_metal ON

ttm nonmetal

ttm_metal OFF

ttm ncit \(n\)

ttm_num_ion_cells \(n\)

ttm ncet \(n_{1}~n_{2}~n_{3}\)

ttm_num_elec_cell [\(n_{1}~n_{2}~n_{3}\)]

ttm offset \(f\)

ttm_time_offset \(f\) ps

ttm elph_cut \(f\)

ttm_e-phonon_cutoff_velocity \(f\) ang/ps

ttm oneway

ttm_oneway ON

ttm redistribute

ttm_redistribute ON

ttm thvelz

ttm_com_correction (full:math:|zdir\(|\)off)

ttm nothvel

ttm stats \(n\)

ttm_stats_frequency \(n\) steps

ttm traj \(n\)

ttm_traj_frequency \(n\) steps

ttm varg homogeneous

ttm_variable_ep homo

ttm varg heterogeneous

ttm_variable_ep hetero

vaf (sampling) (every) \(i\) (bin) (size) \(n\)

vaf_calculate ON

vaf_frequency \(i\) steps

vaf_binsize \(n\)

timestep \(f\)

timestep \(f\) ps

variable timestep \(f\)

timestep \(f\) ps

timestep_variable ON

maxdis \(f\)

timestep_variable_max_dist \(f\) ang

mindis \(f\)

timestep_variable_min_dist \(f\) ang

mxstep \(f\)

timestep_variable_max_delta \(f\) ps

vdw direct

vdw_method (tabulated:math:|direct\(|\)spme\(|\)off)

vdw mixing rule

vdw_mix_method (Lorentz-Berthelot:math:|Fender-Hasley\(|\)Hogervorst\(|\) Waldman-Hagler\(|\)Tang-Toennies\(|\)Functional)

vdw shift

vdw_force_shift ON

zden (sampling) (every) \(f\)

zden_calculate ON

zden_frequency \(f\) steps

zero (fire) (every \(n\))

reset_temperature_interval \(n\) steps