2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
5 * Copyright (c) 2001-2004, The GROMACS development team.
6 * Copyright (c) 2013,2014,2015,2016,2017 by the GROMACS development team.
7 * Copyright (c) 2018,2019,2020,2021, by the GROMACS development team, led by
8 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
9 * and including many others, as listed in the AUTHORS file in the
10 * top-level source directory and at http://www.gromacs.org.
12 * GROMACS is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU Lesser General Public License
14 * as published by the Free Software Foundation; either version 2.1
15 * of the License, or (at your option) any later version.
17 * GROMACS is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * Lesser General Public License for more details.
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with GROMACS; if not, see
24 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
25 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
27 * If you want to redistribute modifications to GROMACS, please
28 * consider that scientific software is very special. Version
29 * control is crucial - bugs must be traceable. We will be happy to
30 * consider code for inclusion in the official distribution, but
31 * derived work must not be called official GROMACS. Details are found
32 * in the README & COPYING files - if they are missing, get the
33 * official version at http://www.gromacs.org.
35 * To help us fund GROMACS development, we humbly ask that you cite
36 * the research papers on the package. Check out http://www.gromacs.org.
43 #include "gromacs/commandline/pargs.h"
44 #include "gromacs/fileio/enxio.h"
45 #include "gromacs/fileio/matio.h"
46 #include "gromacs/fileio/trxio.h"
47 #include "gromacs/fileio/xvgr.h"
48 #include "gromacs/gmxana/gmx_ana.h"
49 #include "gromacs/gmxana/gstat.h"
50 #include "gromacs/math/functions.h"
51 #include "gromacs/math/units.h"
52 #include "gromacs/math/vec.h"
53 #include "gromacs/mdlib/energyoutput.h"
54 #include "gromacs/mdtypes/enerdata.h"
55 #include "gromacs/mdtypes/md_enums.h"
56 #include "gromacs/trajectory/energyframe.h"
57 #include "gromacs/utility/arraysize.h"
58 #include "gromacs/utility/cstringutil.h"
59 #include "gromacs/utility/fatalerror.h"
60 #include "gromacs/utility/futil.h"
61 #include "gromacs/utility/smalloc.h"
62 #include "gromacs/utility/strdb.h"
65 static int search_str2(int nstr, char** str, char* key)
68 int keylen = std::strlen(key);
71 while ((n < keylen) && ((key[n] < '0') || (key[n] > '9')))
75 for (i = 0; (i < nstr); i++)
77 if (gmx_strncasecmp(str[i], key, n) == 0)
86 // The non-bonded energy terms accumulated for energy group pairs. These were superseded elsewhere
87 // by NonBondedEnergyTerms but not updated here due to the need for refactoring here first.
97 static const char* egrp_nm[egNR + 1] = { "Coul-SR", "LJ-SR", "Buck-SR", "Coul-14", "LJ-14", nullptr };
100 int gmx_enemat(int argc, char* argv[])
102 const char* desc[] = {
103 "[THISMODULE] extracts an energy matrix from the energy file ([TT]-f[tt]).",
104 "With [TT]-groups[tt] a file must be supplied with on each",
105 "line a group of atoms to be used. For these groups matrix of",
106 "interaction energies will be extracted from the energy file",
107 "by looking for energy groups with names corresponding to pairs",
108 "of groups of atoms, e.g. if your [TT]-groups[tt] file contains::",
114 "then energy groups with names like 'Coul-SR:Protein-SOL' and ",
115 "'LJ:Protein-SOL' are expected in the energy file (although",
116 "[THISMODULE] is most useful if many groups are analyzed",
117 "simultaneously). Matrices for different energy types are written",
118 "out separately, as controlled by the",
119 "[TT]-[no]coul[tt], [TT]-[no]coulr[tt], [TT]-[no]coul14[tt], ",
120 "[TT]-[no]lj[tt], [TT]-[no]lj14[tt], ",
121 "[TT]-[no]bham[tt] and [TT]-[no]free[tt] options.",
122 "Finally, the total interaction energy energy per group can be ",
123 "calculated ([TT]-etot[tt]).[PAR]",
125 "An approximation of the free energy can be calculated using:",
126 "[MATH]E[SUB]free[sub] = E[SUB]0[sub] + kT ",
127 "[LOG][CHEVRON][EXP](E-E[SUB]0[sub])/kT[exp][chevron][log][math], where ",
128 "'[MATH][CHEVRON][chevron][math]'",
129 "stands for time-average. A file with reference free energies",
130 "can be supplied to calculate the free energy difference",
131 "with some reference state. Group names (e.g. residue names)",
132 "in the reference file should correspond to the group names",
133 "as used in the [TT]-groups[tt] file, but a appended number",
134 "(e.g. residue number) in the [TT]-groups[tt] will be ignored",
137 static gmx_bool bSum = FALSE;
138 static gmx_bool bMeanEmtx = TRUE;
139 static int skip = 0, nlevels = 20;
140 static real cutmax = 1e20, cutmin = -1e20, reftemp = 300.0;
141 static gmx_bool bCoulSR = TRUE, bCoul14 = FALSE;
142 static gmx_bool bLJSR = TRUE, bLJ14 = FALSE, bBhamSR = FALSE, bFree = TRUE;
148 "Sum the energy terms selected rather than display them all" },
149 { "-skip", FALSE, etINT, { &skip }, "Skip number of frames between data points" },
154 "with [TT]-groups[tt] extracts matrix of mean energies instead of "
155 "matrix for each timestep" },
156 { "-nlevels", FALSE, etINT, { &nlevels }, "number of levels for matrix colors" },
157 { "-max", FALSE, etREAL, { &cutmax }, "max value for energies" },
158 { "-min", FALSE, etREAL, { &cutmin }, "min value for energies" },
159 { "-coulsr", FALSE, etBOOL, { &bCoulSR }, "extract Coulomb SR energies" },
160 { "-coul14", FALSE, etBOOL, { &bCoul14 }, "extract Coulomb 1-4 energies" },
161 { "-ljsr", FALSE, etBOOL, { &bLJSR }, "extract Lennard-Jones SR energies" },
162 { "-lj14", FALSE, etBOOL, { &bLJ14 }, "extract Lennard-Jones 1-4 energies" },
163 { "-bhamsr", FALSE, etBOOL, { &bBhamSR }, "extract Buckingham SR energies" },
164 { "-free", FALSE, etBOOL, { &bFree }, "calculate free energy" },
169 "reference temperature for free energy calculation" }
171 /* We will define egSP more energy-groups:
172 egTotal (total energy) */
175 gmx_bool egrp_use[egNR + egSP];
179 gmx_enxnm_t* enm = nullptr;
183 gmx_bool bCont, bRef;
184 gmx_bool bCutmax, bCutmin;
185 real ** eneset, *time = nullptr;
186 int * set, i, j, prevk, k, m = 0, n, nre, nset, nenergy;
187 char** groups = nullptr;
188 char groupname[255], fn[255];
190 t_rgb rlo, rhi, rmid;
191 real emax, emid, emin;
192 real *** emat, **etot, *groupnr;
193 double beta, expE, **e, *eaver, *efree = nullptr, edum;
195 char ** ereflines, **erefres = nullptr;
196 real * eref = nullptr, *edif = nullptr;
198 gmx_output_env_t* oenv;
200 t_filenm fnm[] = { { efEDR, "-f", nullptr, ffOPTRD },
201 { efDAT, "-groups", "groups", ffREAD },
202 { efDAT, "-eref", "eref", ffOPTRD },
203 { efXPM, "-emat", "emat", ffWRITE },
204 { efXVG, "-etot", "energy", ffWRITE } };
205 #define NFILE asize(fnm)
207 if (!parse_common_args(
208 &argc, argv, PCA_CAN_VIEW | PCA_CAN_TIME, NFILE, fnm, asize(pa), pa, asize(desc), desc, 0, nullptr, &oenv))
213 for (i = 0; (i < egNR + egSP); i++)
217 egrp_use[egCOULSR] = bCoulSR;
218 egrp_use[egLJSR] = bLJSR;
219 egrp_use[egBHAMSR] = bBhamSR;
220 egrp_use[egCOUL14] = bCoul14;
221 egrp_use[egLJ14] = bLJ14;
222 egrp_use[egTotal] = TRUE;
224 bRef = opt2bSet("-eref", NFILE, fnm);
225 in = open_enx(ftp2fn(efEDR, NFILE, fnm), "r");
226 do_enxnms(in, &nre, &enm);
230 gmx_fatal(FARGS, "No energies!\n");
233 bCutmax = opt2parg_bSet("-max", asize(pa), pa);
234 bCutmin = opt2parg_bSet("-min", asize(pa), pa);
238 /* Read groupnames from input file and construct selection of
239 energy groups from it*/
241 fprintf(stderr, "Will read groupnames from inputfile\n");
242 ngroups = get_lines(opt2fn("-groups", NFILE, fnm), &groups);
243 fprintf(stderr, "Read %d groups\n", ngroups);
244 snew(set, static_cast<size_t>(gmx::square(ngroups) * egNR / 2));
247 for (i = 0; (i < ngroups); i++)
249 for (j = i; (j < ngroups); j++)
251 for (m = 0; (m < egNR); m++)
255 sprintf(groupname, "%s:%s-%s", egrp_nm[m], groups[i], groups[j]);
256 bool foundMatch = false;
257 for (k = prevk; (k < prevk + nre); k++)
259 if (std::strcmp(enm[k % nre].name, groupname) == 0)
269 "WARNING! could not find group %s (%d,%d) "
283 fprintf(stderr, "\n");
286 // Return an error, can't do what the user asked for
288 "None of the specified energy groups were found in this .edr file.\n"
289 "Perhaps you used the wrong groups, the wrong files, or didn't use a .tpr\n"
290 "that was made from an .mdp file that specified these energy groups.\n");
294 snew(eneset, nset + 1);
295 fprintf(stderr, "Will select half-matrix of energies with %d elements\n", n);
297 /* Start reading energy frames */
303 bCont = do_enx(in, fr);
306 timecheck = check_times(fr->t);
308 } while (bCont && (timecheck < 0));
312 #define DONTSKIP(cnt) (skip) ? (((cnt) % skip) == 0) : TRUE
316 fprintf(stderr, "\rRead frame: %d, Time: %.3f", teller, fr->t);
319 if ((nenergy % 1000) == 0)
321 srenew(time, nenergy + 1000);
322 for (i = 0; (i <= nset); i++)
324 srenew(eneset[i], nenergy + 1000);
327 time[nenergy] = fr->t;
329 for (i = 0; (i < nset); i++)
331 eneset[i][nenergy] = fr->ener[set[i]].e;
332 sum += fr->ener[set[i]].e;
336 eneset[nset][nenergy] = sum;
342 } while (bCont && (timecheck == 0));
344 fprintf(stderr, "\n");
347 "Will build energy half-matrix of %d groups, %d elements, "
353 snew(emat, egNR + egSP);
354 for (j = 0; (j < egNR + egSP); j++)
358 snew(emat[j], ngroups);
359 for (i = 0; (i < ngroups); i++)
361 snew(emat[j][i], ngroups);
365 snew(groupnr, ngroups);
366 for (i = 0; (i < ngroups); i++)
382 for (i = 0; (i < ngroups); i++)
387 for (i = 0; (i < ngroups); i++)
389 for (j = i; (j < ngroups); j++)
391 for (m = 0; (m < egNR); m++)
395 for (k = 0; (k < nenergy); k++)
397 emat[m][i][j] += eneset[n][k];
398 e[i][k] += eneset[n][k]; /* *0.5; */
399 e[j][k] += eneset[n][k]; /* *0.5; */
402 emat[egTotal][i][j] += emat[m][i][j];
403 emat[m][i][j] /= nenergy;
404 emat[m][j][i] = emat[m][i][j];
407 emat[egTotal][i][j] /= nenergy;
408 emat[egTotal][j][i] = emat[egTotal][i][j];
415 fprintf(stderr, "Will read reference energies from inputfile\n");
416 neref = get_lines(opt2fn("-eref", NFILE, fnm), &ereflines);
417 fprintf(stderr, "Read %d reference energies\n", neref);
419 snew(erefres, neref);
420 for (i = 0; (i < neref); i++)
423 sscanf(ereflines[i], "%s %lf", erefres[i], &edum);
427 snew(eaver, ngroups);
428 for (i = 0; (i < ngroups); i++)
430 for (k = 0; (k < nenergy); k++)
436 beta = 1.0 / (gmx::c_boltz * reftemp);
437 snew(efree, ngroups);
439 for (i = 0; (i < ngroups); i++)
442 for (k = 0; (k < nenergy); k++)
444 expE += std::exp(beta * (e[i][k] - eaver[i]));
446 efree[i] = std::log(expE / nenergy) / beta + eaver[i];
449 n = search_str2(neref, erefres, groups[i]);
452 edif[i] = efree[i] - eref[n];
458 "WARNING: group %s not found "
459 "in reference energies.\n",
470 emid = 0.0; /*(emin+emax)*0.5;*/
471 egrp_nm[egTotal] = "total";
472 for (m = 0; (m < egNR + egSP); m++)
478 for (i = 0; (i < ngroups); i++)
480 for (j = i; (j < ngroups); j++)
482 if (emat[m][i][j] > emax)
484 emax = emat[m][i][j];
486 else if (emat[m][i][j] < emin)
488 emin = emat[m][i][j];
495 "Matrix of %s energy is uniform at %f "
496 "(will not produce output).\n",
502 fprintf(stderr, "Matrix of %s energy ranges from %f to %f\n", egrp_nm[m], emin, emax);
503 if ((bCutmax) || (emax > cutmax))
507 if ((bCutmin) || (emin < cutmin))
511 if ((emax == cutmax) || (emin == cutmin))
513 fprintf(stderr, "Energy range adjusted: %f to %f\n", emin, emax);
516 sprintf(fn, "%s%s", egrp_nm[m], ftp2fn(efXPM, NFILE, fnm));
517 sprintf(label, "%s Interaction Energies", egrp_nm[m]);
518 out = gmx_ffopen(fn, "w");
538 else if (emax <= emid)
582 snew(etot, egNR + egSP);
583 for (m = 0; (m < egNR + egSP); m++)
585 snew(etot[m], ngroups);
586 for (i = 0; (i < ngroups); i++)
588 for (j = 0; (j < ngroups); j++)
590 etot[m][i] += emat[m][i][j];
595 out = xvgropen(ftp2fn(efXVG, NFILE, fnm), "Mean Energy", "Residue", "kJ/mol", oenv);
596 xvgr_legend(out, 0, nullptr, oenv);
598 if (output_env_get_print_xvgr_codes(oenv))
600 char str1[STRLEN], str2[STRLEN];
601 if (output_env_get_xvg_format(oenv) == XvgFormat::Xmgr)
603 sprintf(str1, "@ legend string ");
608 sprintf(str1, "@ s");
609 sprintf(str2, " legend ");
612 for (m = 0; (m < egNR + egSP); m++)
616 fprintf(out, "%s%d%s \"%s\"\n", str1, j++, str2, egrp_nm[m]);
621 fprintf(out, "%s%d%s \"%s\"\n", str1, j++, str2, "Free");
625 fprintf(out, "%s%d%s \"%s\"\n", str1, j++, str2, "Diff");
627 fprintf(out, "@TYPE xy\n");
628 fprintf(out, "#%3s", "grp");
630 for (m = 0; (m < egNR + egSP); m++)
634 fprintf(out, " %9s", egrp_nm[m]);
639 fprintf(out, " %9s", "Free");
643 fprintf(out, " %9s", "Diff");
647 for (i = 0; (i < ngroups); i++)
649 fprintf(out, "%3.0f", groupnr[i]);
650 for (m = 0; (m < egNR + egSP); m++)
654 fprintf(out, " %9.5g", etot[m][i]);
659 fprintf(out, " %9.5g", efree[i]);
663 fprintf(out, " %9.5g", edif[i]);
672 "While typing at your keyboard, suddenly...\n"
673 "...nothing happens.\nWARNING: Not Implemented Yet\n");
675 out=ftp2FILE(efMAT,NFILE,fnm,"w");
678 for (k=0; (k<nenergy); k++) {
679 for (i=0; (i<ngroups); i++)
680 for (j=i+1; (j<ngroups); j++)
681 emat[i][j]=eneset[n][k];
682 sprintf(label,"t=%.0f ps",time[k]);
683 write_matrix(out,ngroups,1,ngroups,groupnr,emat,label,emin,emax,nlevels);