1Advanced topics
2===============
3
4Customization
5-------------
6
7Each sub-step of an iteration and all direct calls can be adjusted to
8the user needs. The internal part of the iterative framework is
9organized as follows: all scripts are called using two keywords
10
11.. code:: bash
12
13      csg_call key1 key2
14
15For example, ``csg_call update imc`` calls the ``update`` script for the
16inverse Monte Carlo procedure. The corresponding keywords are listed in
17:ref:`reference_scripts` or can be output directly by calling
18
19.. code:: bash
20
21      csg_call --list
22
23It is advised not to change already implemented scripts. To customize a
24script or add a new one, copy the script to your own directory (set by )
25and redirect its call by creating your own ``csg_table`` file in this
26directory which looks like this
27
28.. code:: bash
29
30      key1 key2 script1 options
31      key3 key4 script2
32
33If the local keys are already in use, the existing call will be
34overloaded.
35
36As an example, we will illustrate how to overload the script which calls
37the sampling package. The script runs from the GROMACS package only on
38one cpu. Our task will be to change the script so that GROMACS uses 8
39cpus, which is basically the same as adding mpirun options in .
40
41First we find out which script calls :
42
43.. code:: bash
44
45      csg_call --list | grep gromacs
46
47The output should look as follows
48
49.. code:: none
50
51      init gromacs initalize_gromacs.sh
52      prepare gromacs prepare_gromacs.sh
53      run gromacs run_gromacs.sh
54      pressure gromacs calc_pressure_gromacs.sh
55      rdf gromacs calc_rdf_gromacs.sh
56      imc_stat gromacs imc_stat_generic.sh
57      convert_potential gromacs potential_to_gromacs.sh
58
59the third line indicates the script we need. If the output of is not
60clear, one can try to find the right script in :ref:`reference_scripts`.
61Alternatively, check the folder
62
63.. code:: none
64
65      <csg-installation>/share/scripts/inverse
66
67for all available scripts.
68
69Analyzing the output of
70
71.. code:: bash
72
73      csg_call --cat run gromacs
74
75we can conclude that this is indeed the script we need as the content
76(in shorted form is):
77
78.. code:: bash
79
80      critical mdrun
81
82Now we can create our own ``SCRIPTDIR``, add a new script there, make it
83executable and overload the call of the script:
84
85.. code:: bash
86
87      mkdir -p SCRIPTDIR
88      cp `csg_call --quiet --show run gromacs` SCRIPTDIR/my_run_gromacs.sh
89      chmod 755 SCRIPTDIR/my_run_gromacs.sh
90      echo "run gromacs my_run_gromacs.sh" >> SCRIPTDIR/csg_table
91
92Please note that ``my_run_gromacs.sh`` is the name of the script and
93``SCRIPTDIR`` is the custom script directory, which can be a global or a
94local path. Now we change the last line of ``my_run_gromacs.sh`` to:
95
96.. code:: bash
97
98      critical mpirun -np 8 mdrun
99
100This completes the customization. Do not forget to add ``SCRIPTDIR`` to
101in the setting XMLfile (see :ref:`reference_settings_file`).
102
103You can check the new script by running:
104
105.. code:: bash
106
107      csg_call --scriptdir SCRIPTDIR --list
108      csg_call --scriptdir SCRIPTDIR --run run gromacs
109
110Finally, do not forget to remove the license infomation and change the
111version number of the script.
112
113Used external packages
114----------------------
115
116GROMACS
117~~~~~~~
118
119`Link to Homepage <https://manual.gromacs.org/documentation/>`
120
121ESPResSo
122~~~~~~~~~~
123
124`Link to Homepage <https://espressomd.org/>`
125
126DL\_POLY
127~~~~~~~~
128
129`Link to Homepage <https://www.scd.stfc.ac.uk/Pages/DL_POLY.aspx>`
130
131Gnuplot
132~~~~~~~
133
134`Link to Homepage <http://www.gnuplot.info/>`
135
136LAMMPS
137~~~~~~
138
139`Link to Homepage <https://lammps.sandia.gov/>`
140
141
142DL\_POLY interface
143------------------
144
145**WARNING: The DL\_POLY interface is still experimental (in development)
146but it does support the Iterative Boltzmann Inversion and Inverse Monte
147Carlo schemes. The Force Matching might work as well, although it has
148not been tested thoroughly.**
149
150
151The DL\_POLY interface fully supports coarse-grain mapping of a full-atom
152system previuosly simulated with any version of DL\_POLY, including
153DL\_POLY-Classic. However, the full optimization of the effective
154potentials with the aid of iterative methods will only become possible
155when the new release of DL\_POLY-4 (4.06) is made public; the reason
156being the incapability of earlier DL\_POLY versions of using
157user-specified tabulated force-fields for intramolecular, aka “bonded”,
158interactions: bonds, angles, dihedral angles (torsions). Below the
159coarse-graining and CG force-field optimization with the aid of the
160latest DL\_POLY-4 version (4.06+) are outlined.
161
162Running VOTCA with DL\_POLY-4 as MD simulation engine is very similar to
163doing so with GROMACS. The three types of required input files in the
164case of DL\_POLY are: CONTROL – containing the simulation directives and
165parameters (instead of ``.mdp`` file for GROMACS), FIELD – the topology
166and force-field specifications (instead of ``.top`` and ``.tpr`` files),
167and CONFIG (instead of ``.gro`` file) – the initial configuration file,
168containing the MD cell matrix and particle coordinates (it can also
169include initial velocities and/or forces); for details see
170DL\_POLY-4 manual. Most of the VOTCA tools and scripts described above in
171the case of using GROMACS will work in the same manner, with the
172following conventional substitutions for the (default) file names used
173in options for VOTCA scripts, as necessary:
174
175.. code:: none
176
177    .dlpf = the topology read from FIELD or written to FIELD_CGV
178    .dlpc = the configuration read from CONFIG or written to CONFIG_CGV
179    .dlph = the trajectory read from HISTORY or written to HISTORY_CGV
180
181It is also possible to specify file names different from the standard
182DL\_POLY convention, in which case the user has to use the corresponding
183dot-preceded extension(s); for example: FA-FIELD.dlpf instead of FIELD
184or CG-HISTORY.dlph instead of HISTORY\_CGV (see
185:ref:`reference_programs`, as well as the man pages or output of
186VOTCA commands, with option ``—help``).
187
188VOTCA follows the DL\_POLY conventions for file names and formats. Thus,
189``csg_dlptopol`` and ``csg_map`` produce the CG topology (FIELD\_CGV by
190default), configuration (CONFIG\_CGV), and/or trajectory (HISTORY\_CGV)
191files fully compatible with and usable by DL\_POLY. **Note that the
192ability of these tools to read and write a plethora of different file
193formats provides means to convert input and output files between the
194simulation packages supported by VOTCA, e.g. GROMACS – DL\_POLY or vice
195versa. The user is, however, strongly advised to check the resulting
196files for consistency before using them).**
197
198Similarly, the distribution analysis and potential/force generation
199utilities, such as ``csg_stat`` and VOTCA scripts, will read and write
200DL\_POLY-formatted files; in particular, the tabulated force-field files
201containing the potential and force/virial data: TABLE – for short-range
202(VdW) “non-bonded” interactions, TABBND, TABANG and TABDIH – for
203“bonded” interations: bonds, bending angles and dihedrals,
204correspondingly (for the format details see DL\_POLY-4 manual). Note,
205however, that the latter three files can only be used by
206DL\_POLY-4 (4.06+).
207
208The user is advised to search for “dlpoly” through the
209``csg_defaults.xml``, ``csg_table`` files and in scripts located in
210``share/votca/scripts/inverse/`` in order to find out about the xml-tags
211and options specific for DL\_POLY; see also :ref:`reference_settings_file`
212and :ref:`reference_scripts`.
213