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,2018,2019, by the GROMACS development team, led by
7 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
8 * and including many others, as listed in the AUTHORS file in the
9 * top-level source directory and at http://www.gromacs.org.
11 * GROMACS is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public License
13 * as published by the Free Software Foundation; either version 2.1
14 * of the License, or (at your option) any later version.
16 * GROMACS is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with GROMACS; if not, see
23 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
24 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26 * If you want to redistribute modifications to GROMACS, please
27 * consider that scientific software is very special. Version
28 * control is crucial - bugs must be traceable. We will be happy to
29 * consider code for inclusion in the official distribution, but
30 * derived work must not be called official GROMACS. Details are found
31 * in the README & COPYING files - if they are missing, get the
32 * official version at http://www.gromacs.org.
34 * To help us fund GROMACS development, we humbly ask that you cite
35 * the research papers on the package. Check out http://www.gromacs.org.
39 #include "mdebin_bar.h"
48 #include "gromacs/fileio/enxio.h"
49 #include "gromacs/mdlib/energyoutput.h"
50 #include "gromacs/mdtypes/energyhistory.h"
51 #include "gromacs/mdtypes/inputrec.h"
52 #include "gromacs/mdtypes/md_enums.h"
53 #include "gromacs/trajectory/energyframe.h"
54 #include "gromacs/utility/fatalerror.h"
55 #include "gromacs/utility/gmxassert.h"
56 #include "gromacs/utility/smalloc.h"
58 /* Number of entries in subblock_d preceding the lambda components */
59 constexpr int c_subblockDNumPreEntries = 5;
60 /* Number of entries in subblock_i preceding the lambda components */
61 constexpr int c_subblockINumPreEntries = 2;
63 /* reset the delta_h list to prepare it for new values */
64 static void mde_delta_h_reset(t_mde_delta_h *dh)
70 /* initialize the delta_h list */
71 static void mde_delta_h_init(t_mde_delta_h *dh, int nbins,
72 double dx, unsigned int ndhmax,
73 int type, int derivative, int nlambda,
79 dh->derivative = derivative;
80 dh->nlambda = nlambda;
82 snew(dh->lambda, nlambda);
83 for (i = 0; i < nlambda; i++)
86 dh->lambda[i] = lambda[i];
90 snew(dh->subblock_meta_d, dh->nlambda+1);
92 dh->ndhmax = ndhmax+2;
93 for (i = 0; i < 2; i++)
98 snew(dh->dh, dh->ndhmax);
99 snew(dh->dhf, dh->ndhmax);
101 if (nbins <= 0 || dx < GMX_REAL_EPS*10)
108 /* pre-allocate the histogram */
109 dh->nhist = 2; /* energies and derivatives histogram */
112 for (i = 0; i < dh->nhist; i++)
114 snew(dh->bin[i], dh->nbins);
117 mde_delta_h_reset(dh);
120 static void done_mde_delta_h(t_mde_delta_h *dh)
123 sfree(dh->subblock_meta_d);
126 for (int i = 0; i < dh->nhist; i++)
132 /* Add a value to the delta_h list */
133 static void mde_delta_h_add_dh(t_mde_delta_h *dh, double delta_h)
135 if (dh->ndh >= dh->ndhmax)
137 gmx_incons("delta_h array not big enough!");
139 dh->dh[dh->ndh] = delta_h;
143 /* construct histogram with index hi */
144 static void mde_delta_h_make_hist(t_mde_delta_h *dh, int hi, gmx_bool invert)
146 double min_dh = FLT_MAX;
147 double max_dh = -FLT_MAX;
149 double max_dh_hist; /* maximum binnable dh value */
150 double min_dh_hist; /* minimum binnable dh value */
152 double f; /* energy mult. factor */
154 /* by applying a -1 scaling factor on the energies we get the same as
155 having a negative dx, but we don't need to fix the min/max values
156 beyond inverting x0 */
159 /* first find min and max */
160 for (i = 0; i < dh->ndh; i++)
162 if (f*dh->dh[i] < min_dh)
164 min_dh = f*dh->dh[i];
166 if (f*dh->dh[i] > max_dh)
168 max_dh = f*dh->dh[i];
172 /* reset the histogram */
173 for (i = 0; i < dh->nbins; i++)
179 /* The starting point of the histogram is the lowest value found:
180 that value has the highest contribution to the free energy.
182 Get this start value in number of histogram dxs from zero,
185 dh->x0[hi] = static_cast<int64_t>(floor(min_dh/dx));
187 min_dh_hist = (dh->x0[hi])*dx;
188 max_dh_hist = (dh->x0[hi] + dh->nbins + 1)*dx;
190 /* and fill the histogram*/
191 for (i = 0; i < dh->ndh; i++)
195 /* Determine the bin number. If it doesn't fit into the histogram,
196 add it to the last bin.
197 We check the max_dh_int range because converting to integers
198 might lead to overflow with unpredictable results.*/
199 if ( (f*dh->dh[i] >= min_dh_hist) && (f*dh->dh[i] <= max_dh_hist ) )
201 bin = static_cast<unsigned int>( (f*dh->dh[i] - min_dh_hist)/dx );
207 /* double-check here because of possible round-off errors*/
208 if (bin >= dh->nbins)
212 if (bin > dh->maxbin[hi])
214 dh->maxbin[hi] = bin;
220 /* make sure we include a bin with 0 if we didn't use the full
221 histogram width. This can then be used as an indication that
222 all the data was binned. */
223 if (dh->maxbin[hi] < dh->nbins-1)
230 static void mde_delta_h_handle_block(t_mde_delta_h *dh, t_enxblock *blk)
232 /* first check which type we should use: histogram or raw data */
237 /* We write raw data.
238 Raw data consists of 3 subblocks: an int metadata block
239 with type and derivative index, a foreign lambda block
240 and and the data itself */
241 add_subblocks_enxblock(blk, 3);
246 dh->subblock_meta_i[0] = dh->type; /* block data type */
247 dh->subblock_meta_i[1] = dh->derivative; /* derivative direction if
248 applicable (in indices
249 starting from first coord in
250 the main delta_h_coll) */
252 blk->sub[0].type = xdr_datatype_int;
253 blk->sub[0].ival = dh->subblock_meta_i;
256 for (i = 0; i < dh->nlambda; i++)
258 dh->subblock_meta_d[i] = dh->lambda[i];
260 blk->sub[1].nr = dh->nlambda;
261 blk->sub[1].type = xdr_datatype_double;
262 blk->sub[1].dval = dh->subblock_meta_d;
265 /* check if there's actual data to be written. */
271 blk->sub[2].nr = dh->ndh;
272 /* Michael commented in 2012 that this use of explicit
273 xdr_datatype_float was good for F@H for now.
274 Apparently it's still good enough. */
275 blk->sub[2].type = xdr_datatype_float;
276 for (i = 0; i < dh->ndh; i++)
278 dh->dhf[i] = static_cast<float>(dh->dh[i]);
280 blk->sub[2].fval = dh->dhf;
286 blk->sub[2].type = xdr_datatype_float;
287 blk->sub[2].fval = nullptr;
292 int nhist_written = 0;
296 /* TODO histogram metadata */
297 /* check if there's actual data to be written. */
300 gmx_bool prev_complete = FALSE;
301 /* Make the histogram(s) */
302 for (i = 0; i < dh->nhist; i++)
306 /* the first histogram is always normal, and the
307 second one is always reverse */
308 mde_delta_h_make_hist(dh, i, i == 1);
310 /* check whether this histogram contains all data: if the
311 last bin is 0, it does */
312 if (dh->bin[i][dh->nbins-1] == 0)
314 prev_complete = TRUE;
318 prev_complete = TRUE;
325 /* A histogram consists of 2, 3 or 4 subblocks:
326 the foreign lambda value + histogram spacing, the starting point,
327 and the histogram data (0, 1 or 2 blocks). */
328 add_subblocks_enxblock(blk, nhist_written+2);
331 /* subblock 1: the lambda value + the histogram spacing */
332 if (dh->nlambda == 1)
334 /* for backward compatibility */
335 dh->subblock_meta_d[0] = dh->lambda[0];
339 dh->subblock_meta_d[0] = -1;
340 for (i = 0; i < dh->nlambda; i++)
342 dh->subblock_meta_d[2+i] = dh->lambda[i];
345 dh->subblock_meta_d[1] = dh->dx;
346 blk->sub[0].nr = 2+ ((dh->nlambda > 1) ? dh->nlambda : 0);
347 blk->sub[0].type = xdr_datatype_double;
348 blk->sub[0].dval = dh->subblock_meta_d;
350 /* subblock 2: the starting point(s) as a long integer */
351 dh->subblock_meta_l[0] = nhist_written;
352 dh->subblock_meta_l[1] = dh->type; /*dh->derivative ? 1 : 0;*/
354 for (i = 0; i < nhist_written; i++)
356 dh->subblock_meta_l[k++] = dh->x0[i];
358 /* append the derivative data */
359 dh->subblock_meta_l[k++] = dh->derivative;
361 blk->sub[1].nr = nhist_written+3;
362 blk->sub[1].type = xdr_datatype_int64;
363 blk->sub[1].lval = dh->subblock_meta_l;
365 /* subblock 3 + 4 : the histogram data */
366 for (i = 0; i < nhist_written; i++)
368 blk->sub[i+2].nr = dh->maxbin[i]+1; /* it's +1 because size=index+1
370 blk->sub[i+2].type = xdr_datatype_int;
371 blk->sub[i+2].ival = dh->bin[i];
376 /* initialize the collection*/
377 void mde_delta_h_coll_init(t_mde_delta_h_coll *dhc, const t_inputrec *ir)
381 int ndhmax = ir->nstenergy/ir->nstcalcenergy;
382 t_lambda *fep = ir->fepvals;
384 dhc->temperature = ir->opts.ref_t[0]; /* only store system temperature */
385 dhc->start_time = 0.;
386 dhc->delta_time = ir->delta_t*ir->fepvals->nstdhdl;
387 dhc->start_time_set = FALSE;
389 /* this is the compatibility lambda value. If it is >=0, it is valid,
390 and there is either an old-style lambda or a slow growth simulation. */
391 dhc->start_lambda = ir->fepvals->init_lambda;
392 /* for continuous change of lambda values */
393 dhc->delta_lambda = ir->fepvals->delta_lambda*ir->fepvals->nstdhdl;
395 if (dhc->start_lambda < 0)
397 /* create the native lambda vectors */
398 dhc->lambda_index = fep->init_fep_state;
399 dhc->n_lambda_vec = 0;
400 for (i = 0; i < efptNR; i++)
402 if (fep->separate_dvdl[i])
407 snew(dhc->native_lambda_vec, dhc->n_lambda_vec);
408 snew(dhc->native_lambda_components, dhc->n_lambda_vec);
410 for (i = 0; i < efptNR; i++)
412 if (fep->separate_dvdl[i])
414 dhc->native_lambda_components[j] = i;
415 if (fep->init_fep_state >= 0 &&
416 fep->init_fep_state < fep->n_lambda)
418 dhc->native_lambda_vec[j] =
419 fep->all_lambda[i][fep->init_fep_state];
423 dhc->native_lambda_vec[j] = -1;
431 /* don't allocate the meta-data subblocks for lambda vectors */
432 dhc->native_lambda_vec = nullptr;
433 dhc->n_lambda_vec = 0;
434 dhc->native_lambda_components = nullptr;
435 dhc->lambda_index = -1;
437 /* allocate metadata subblocks */
438 snew(dhc->subblock_d, c_subblockDNumPreEntries + dhc->n_lambda_vec);
439 snew(dhc->subblock_i, c_subblockINumPreEntries + dhc->n_lambda_vec);
441 /* now decide which data to write out */
444 dhc->dh_expanded = nullptr;
445 dhc->dh_energy = nullptr;
446 dhc->dh_pv = nullptr;
448 /* total number of raw data point collections in the sample */
452 gmx_bool bExpanded = FALSE;
453 gmx_bool bEnergy = FALSE;
454 gmx_bool bPV = FALSE;
455 int n_lambda_components = 0;
457 /* first count the number of states */
460 if (fep->dhdl_derivatives == edhdlderivativesYES)
462 for (i = 0; i < efptNR; i++)
464 if (ir->fepvals->separate_dvdl[i])
471 /* add the lambdas */
472 dhc->nlambda = ir->fepvals->lambda_stop_n - ir->fepvals->lambda_start_n;
473 dhc->ndh += dhc->nlambda;
474 /* another compatibility check */
475 if (dhc->start_lambda < 0)
477 /* include one more for the specification of the state, by lambda or
479 if (ir->expandedvals->elmcmove > elmcmoveNO)
484 /* whether to print energies */
485 if (ir->fepvals->edHdLPrintEnergy != edHdLPrintEnergyNO)
492 dhc->ndh += 1; /* include pressure-volume work */
497 snew(dhc->dh, dhc->ndh);
499 /* now initialize them */
500 /* the order, for now, must match that of the dhdl.xvg file because of
501 how g_energy -odh is implemented */
505 dhc->dh_expanded = dhc->dh+n;
506 mde_delta_h_init(dhc->dh+n, ir->fepvals->dh_hist_size,
507 ir->fepvals->dh_hist_spacing, ndhmax,
508 dhbtEXPANDED, 0, 0, nullptr);
513 dhc->dh_energy = dhc->dh+n;
514 mde_delta_h_init(dhc->dh+n, ir->fepvals->dh_hist_size,
515 ir->fepvals->dh_hist_spacing, ndhmax,
516 dhbtEN, 0, 0, nullptr);
520 n_lambda_components = 0;
521 if (fep->dhdl_derivatives == edhdlderivativesYES)
523 dhc->dh_dhdl = dhc->dh + n;
524 for (i = 0; i < efptNR; i++)
526 if (ir->fepvals->separate_dvdl[i])
528 /* we give it init_lambda for compatibility */
529 mde_delta_h_init(dhc->dh+n, ir->fepvals->dh_hist_size,
530 ir->fepvals->dh_hist_spacing, ndhmax,
531 dhbtDHDL, n_lambda_components, 1,
532 &(fep->init_lambda));
534 n_lambda_components++;
540 for (i = 0; i < efptNR; i++)
542 if (ir->fepvals->separate_dvdl[i])
544 n_lambda_components++; /* count the components */
549 /* add the lambdas */
550 dhc->dh_du = dhc->dh + n;
551 snew(lambda_vec, n_lambda_components);
552 for (i = ir->fepvals->lambda_start_n; i < ir->fepvals->lambda_stop_n; i++)
556 for (j = 0; j < efptNR; j++)
558 if (ir->fepvals->separate_dvdl[j])
560 lambda_vec[k++] = fep->all_lambda[j][i];
564 mde_delta_h_init(dhc->dh+n, ir->fepvals->dh_hist_size,
565 ir->fepvals->dh_hist_spacing, ndhmax,
566 dhbtDH, 0, n_lambda_components, lambda_vec);
572 dhc->dh_pv = dhc->dh+n;
573 mde_delta_h_init(dhc->dh+n, ir->fepvals->dh_hist_size,
574 ir->fepvals->dh_hist_spacing, ndhmax,
575 dhbtPV, 0, 0, nullptr);
581 void done_mde_delta_h_coll(t_mde_delta_h_coll *dhc)
587 sfree(dhc->native_lambda_vec);
588 sfree(dhc->native_lambda_components);
589 sfree(dhc->subblock_d);
590 sfree(dhc->subblock_i);
591 for (int i = 0; i < dhc->ndh; ++i)
593 done_mde_delta_h(&dhc->dh[i]);
599 /* add a bunch of samples - note fep_state is double to allow for better data storage */
600 void mde_delta_h_coll_add_dh(t_mde_delta_h_coll *dhc,
610 if (!dhc->start_time_set)
612 dhc->start_time_set = TRUE;
613 dhc->start_time = time;
616 for (i = 0; i < dhc->ndhdl; i++)
618 mde_delta_h_add_dh(dhc->dh_dhdl+i, dhdl[i]);
620 for (i = 0; i < dhc->nlambda; i++)
622 mde_delta_h_add_dh(dhc->dh_du+i, foreign_dU[i]);
624 if (dhc->dh_pv != nullptr)
626 mde_delta_h_add_dh(dhc->dh_pv, pV);
628 if (dhc->dh_energy != nullptr)
630 mde_delta_h_add_dh(dhc->dh_energy, energy);
632 if (dhc->dh_expanded != nullptr)
634 mde_delta_h_add_dh(dhc->dh_expanded, fep_state);
639 /* write the metadata associated with all the du blocks, and call
640 handle_block to write out all the du blocks */
641 void mde_delta_h_coll_handle_block(t_mde_delta_h_coll *dhc,
642 t_enxframe *fr, int nblock)
647 /* add one block with one subblock as the collection's own data */
649 add_blocks_enxframe(fr, nblock);
650 blk = fr->block + (nblock-1);
652 /* only allocate lambda vector component blocks if they must be written out
653 for backward compatibility */
654 if (dhc->native_lambda_components != nullptr)
656 add_subblocks_enxblock(blk, 2);
660 add_subblocks_enxblock(blk, 1);
663 dhc->subblock_d[0] = dhc->temperature; /* temperature */
664 dhc->subblock_d[1] = dhc->start_time; /* time of first sample */
665 dhc->subblock_d[2] = dhc->delta_time; /* time difference between samples */
666 dhc->subblock_d[3] = dhc->start_lambda; /* old-style lambda at starttime */
667 dhc->subblock_d[4] = dhc->delta_lambda; /* lambda diff. between samples */
668 /* set the lambda vector components if they exist */
669 if (dhc->native_lambda_components != nullptr)
671 for (i = 0; i < dhc->n_lambda_vec; i++)
673 dhc->subblock_d[c_subblockDNumPreEntries + i] = dhc->native_lambda_vec[i];
677 blk->sub[0].nr = c_subblockDNumPreEntries + dhc->n_lambda_vec;
678 blk->sub[0].type = xdr_datatype_double;
679 blk->sub[0].dval = dhc->subblock_d;
681 if (dhc->native_lambda_components != nullptr)
683 dhc->subblock_i[0] = dhc->lambda_index;
684 /* set the lambda vector component IDs if they exist */
685 dhc->subblock_i[1] = dhc->n_lambda_vec;
686 for (i = 0; i < dhc->n_lambda_vec; i++)
688 dhc->subblock_i[c_subblockINumPreEntries + i] = dhc->native_lambda_components[i];
690 blk->sub[1].nr = c_subblockINumPreEntries + dhc->n_lambda_vec;
691 blk->sub[1].type = xdr_datatype_int;
692 blk->sub[1].ival = dhc->subblock_i;
695 for (i = 0; i < dhc->ndh; i++)
698 add_blocks_enxframe(fr, nblock);
699 blk = fr->block + (nblock-1);
701 mde_delta_h_handle_block(dhc->dh+i, blk);
705 /* reset the data for a new round */
706 void mde_delta_h_coll_reset(t_mde_delta_h_coll *dhc)
709 for (i = 0; i < dhc->ndh; i++)
711 if (dhc->dh[i].written)
713 /* we can now throw away the data */
714 mde_delta_h_reset(dhc->dh + i);
717 dhc->start_time_set = FALSE;
720 /* set the energyhistory variables to save state */
721 void mde_delta_h_coll_update_energyhistory(const t_mde_delta_h_coll *dhc,
722 energyhistory_t *enerhist)
724 if (enerhist->deltaHForeignLambdas == nullptr)
726 enerhist->deltaHForeignLambdas = std::make_unique<delta_h_history_t>();
727 enerhist->deltaHForeignLambdas->dh.resize(dhc->ndh);
730 delta_h_history_t * const deltaH = enerhist->deltaHForeignLambdas.get();
732 GMX_RELEASE_ASSERT(deltaH->dh.size() == static_cast<size_t>(dhc->ndh), "energy history number of delta_h histograms should match inputrec's number");
734 for (int i = 0; i < dhc->ndh; i++)
736 std::vector<real> &dh = deltaH->dh[i];
737 dh.resize(dhc->dh[i].ndh);
738 std::copy(dh.begin(), dh.end(), dhc->dh[i].dh);
740 deltaH->start_time = dhc->start_time;
741 deltaH->start_lambda = dhc->start_lambda;
746 /* restore the variables from an energyhistory */
747 void mde_delta_h_coll_restore_energyhistory(t_mde_delta_h_coll *dhc,
748 const delta_h_history_t *deltaH)
750 GMX_RELEASE_ASSERT(dhc, "Should have delta_h histograms");
751 GMX_RELEASE_ASSERT(deltaH, "Should have delta_h histograms in energy history");
752 GMX_RELEASE_ASSERT(deltaH->dh.size() == static_cast<size_t>(dhc->ndh), "energy history number of delta_h histograms should match inputrec's number");
754 for (gmx::index i = 0; i < gmx::ssize(deltaH->dh); i++)
756 dhc->dh[i].ndh = deltaH->dh[i].size();
757 for (unsigned int j = 0; j < dhc->dh[i].ndh; j++)
759 dhc->dh[i].dh[j] = deltaH->dh[i][j];
762 dhc->start_time = deltaH->start_time;
763 if (deltaH->start_lambda_set)
765 dhc->start_lambda = deltaH->start_lambda;
767 if (dhc->dh[0].ndh > 0)
769 dhc->start_time_set = TRUE;
773 dhc->start_time_set = FALSE;