Published a deprecation policy.
Updated the release notes to refer also to previously deprecated
features.
Announced intent to change some functionality:
* gmx mdrun -membed options (but not feature)
* gmx mdrun -rerun option (but not feature)
* integrator .mdp field will contain only integrators
* gmx do_dssp to be replaced by gmx dssp
* gmx trjconv and friends to be split and rewritten
List of newly deprecated functionality:
* conversion of aromatic rings to virtual sites
* gmx mdrun -table options (but not feature)
* gmx mdrun -gcom option and feature
* gmx mdrun -nsteps option and feature
* gmx mdrun -nsteps -resetstep -resethway moved to
a gmx benchmark tool
* gmx mdrun -confout removed
Also updated release notes for functionality removed in GROMACS 2019.
Refs #2495, #1781
Fixes #2569, #1925
Change-Id: I1d00859d0f15409a472984f5a65347a50c71ad17
release-notes/performance.rst
release-notes/tools.rst
release-notes/bugs-fixed.rst
- release-notes/removed-features.rst
+ release-notes/deprecated-functionality.rst
+ release-notes/removed-functionality.rst
release-notes/portability.rst
release-notes/miscellaneous.rst
release-notes/2018/2018.4.rst
# manual or without.
user-guide/cmdline.rst
user-guide/cutoff-schemes.rst
+ user-guide/deprecation-policy.rst
user-guide/environment-variables.rst
user-guide/faq.rst
user-guide/floating-point.rst
in the process of including it in the main source tree.
.. _developer mailing list: https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx-developers
+
+Removing functionality
+----------------------
+
+This is occasionally necessary, and there is :ref:`policy for such
+occasions <deprecation policy>`. For users, there are also lists of
+:ref:`anticipated changes <anticipated changes>` and :ref:`deprecated
+functionality <deprecated functionality>`.
All modifications described in this section can be performed using the
|Gromacs| topology building tool :ref:`pdb2gmx <gmx pdb2gmx>`. Separate options exist to
increase hydrogen masses, virtualize all hydrogen atoms, or also
-virtualize all aromatic residues. **Note** that when all hydrogen atoms
+virtualize the aromatic rings in standard residues. **Note** that when all hydrogen atoms
are virtualized, those inside the aromatic residues will be virtualized
as well, *i.e.* hydrogens in the aromatic residues are treated
-differently depending on the treatment of the aromatic residues.
+differently depending on the treatment of the aromatic residues. Note
+further that the virtualization of aromatic rings is deprecated.
Parameters for the virtual site constructions for the hydrogen atoms are
inferred from the force-field parameters (*vis*. bond lengths and
--- /dev/null
+.. _anticipated changes:
+
+Changes anticipated to GROMACS 2019 functionality
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``gmx mdrun -membed``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+The feature for embedding a protein in a membrane will be retained,
+but probably in a different form, such as ``gmx membed``.
+
+``gmx mdrun -rerun``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+The feature for computing potential energy quantities from a
+trajectory will be retained, but probably in a different form, such as
+``gmx rerun`` and ``gmx test-particle-insertion``.
+
+Integrator .mdp options will only contain dynamical integrators
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Energy minimization will be accessed in a differt form, perhaps with
+``gmx minimize`` and interpret an .mdp field for which minimizer to
+use. Normal-mode analysis may be accessed with e.g. ``gmx
+normal-modes``. The command-line help for these tools will thenx
+be better able to document which functionality is supported when.
+
+Much functionality in ``trjconv``, ``editconf``, ``eneconv`` and ``trjcat``
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+The functionality in such tools is being separated to make it
+available in composable modules, that we plan to make available as
+simpler tools, and eventually via the GROMACS API that is under
+development.
+
+``gmx do_dssp`` to be replaced
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+This tool is deprecated, because it is problematic for some users to
+obtain and install a separate DSSP binary, so we plan to replace the
+implementation at some point with a native implementation, likely
+based upon xssp, and make it available under a new gmx tool name.
+
+.. _deprecated functionality:
+
+Functionality deprecated in GROMACS 2019
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Generation of virtual sites to replace aromatic rings in standard residues
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+These are thought to produce artefacts under some circumstances
+(unpublished results), were never well tested, are not widely used,
+and we need to simplify pdb2gmx.
+
+``gmx mdrun -gcom``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+This feature sometimes overrides the effects of various .mdp settings
+in a way that is difficult to understand and report. A user who wants
+to do communication between PP ranks less often should choose their
+``nst*`` mdp options accordingly.
+
+Benchmarking options only available with ``gmx benchmark``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Options such as ``-confout``, ``-resethway``, ``-resetstep`` are not
+intended for use by regular mdrun users, so making them only available
+with a dedicated tool is more clear. Also, this permits us to customize
+defaults for e.g. writing files at the end of a simulation part in ways
+that suit the respective mdrun and benchmark use cases, so ``-confout``
+will no longer be required.
+
+``gmx mdrun -nsteps``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+The number of simulation steps described by the .tpr file can be
+changed with ``gmx convert-tpr``, or altered in .mdp file before the
+call to ``gmx grompp``. The convenience of this mdrun option was
+outweighted by the doubtful quality of its implementation, no clear
+record in the log file, and lack of maintenance.
+
+Functionality deprecated before GROMACS 2019
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This functionality has been declared as deprecated in previous versions
+of |Gromacs|, but has not yet been removed.
+
+The group cutoff scheme
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+All remaining aspects of the group cutoff scheme will be removed, once
+a few remaining features (e.g. tabulated interactions, energy-group
+exclusions, and vacuum simulations) are available with the Verlet
+scheme. Deprecated in GROMACS 5.1
performance
tools
bugs-fixed
- removed-features
+ deprecated-functionality
+ removed-functionality
portability
miscellaneous
+++ /dev/null
-Removed features
-^^^^^^^^^^^^^^^^
-
-NVML support removed on NVIDIA GPUs
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-NVML support (for reporting GPU application clocks or changing these
-for higher throughput) is no longer available. It was only ever supported on
-high-end hardware and changing clocks is on recent generations of hardware only
-useful when root permissions were available to the user. It may become less useful
-as GROMACS evolves, complicated the GROMACS code, and wasn't regularly tested or maintained.
-It might return if some of these conditions change.
--- /dev/null
+Removed functionality
+^^^^^^^^^^^^^^^^^^^^^
+
+NVML support removed on NVIDIA GPUs
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+NVML support (for reporting GPU application clocks or changing these
+for higher throughput) is no longer available. It was only ever supported on
+high-end hardware and changing clocks is on recent generations of hardware only
+useful when root permissions were available to the user. It may become less useful
+as GROMACS evolves, complicated the GROMACS code, and wasn't regularly tested or maintained.
+It might return if some of these conditions change.
+
+Contrib directory removed
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+This code had not been maintained in years, so likely didn't work, and
+has been removed. The git history retains its memory if anybody needs
+it.
+
+BlueGene support removed
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+As most of these machines are now retired, and the ports have not been actively
+maintained since |Gromacs| 5.1, the support for BlueGene and QPX SIMD has been
+removed.
+
+Implicit solvent support removed
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Since |Gromacs|-4.6, the SIMD and multi-threading support has been
+mostly broken. Since nobody wants to fix it, the feature has been
+removed. Old force field files with parameters for such simulations can still be
+read, but the values are ignored.
+
+Removed ``gmx mdrun -multi``
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+The implementation of ``gmx mdrun -multidir`` is more reliable and works with more
+features. Nobody was willing to maintain the duplicate functionality.
--- /dev/null
+.. _deprecation policy:
+
+Policy for deprecating |Gromacs| functionality
+==============================================
+
+Occasionally functionality ceases being useful, is unable to be fixed
+or maintained, or its user interface needs to be improved. The
+development team does this sparingly. Broken functionality might be
+removed without notice if nobody willing to fix it can be found.
+Working functionality will be changed only after announcing in the
+previous major release the intent to remove and/or change the form of
+such functionality. Thus there is typically a year for users and
+external tool providers to prepare for such changes, and contact the
+|Gromacs| developers to see how they might be affected and how best to
+adapt. There is a :ref:`current list <deprecated functionality>` of
+deprecated functionality.
terminology
environment-variables
floating-point
+ deprecation-policy
(`Yesylevskyy S.O., J Chem Inf Model 47(5) (2007) 1986-94`_) and
later implemented in |Gromacs| as g_membed tool (`Wolf et al, J Comp Chem 31 (2010) 2169-2174`_).
Currently the functionality of g_membed is available in mdrun if
-``-membed`` option is specified (see below).
+``-membed`` option is specified (see below). This approach is
+unsuitable, and may be deprecated and replaced in future, e.g. with
+``gmx membed``.
.. _Yesylevskyy S.O., J Chem Inf Model 47(5) (2007) 1986-94: https://dx.doi.org/10.1021/ci600553y
.. _Wolf et al, J Comp Chem 31 (2010) 2169-2174: http://onlinelibrary.wiley.com/doi/10.1002/jcc.21507/full
#include "gromacs/utility/cstringutil.h"
#include "gromacs/utility/fatalerror.h"
#include "gromacs/utility/gmxassert.h"
+#include "gromacs/utility/logger.h"
#include "gromacs/utility/smalloc.h"
#include "gromacs/utility/strconvert.h"
/* Init routine for ED and flooding. Calls init_edi in a loop for every .edi-cycle
* contained in the input file, creates a NULL terminated list of t_edpar structures */
std::unique_ptr<gmx::EssentialDynamics> init_edsam(
+ const gmx::MDLogger &mdlog,
const char *ediFileName,
const char *edoFileName,
const gmx_mtop_t *mtop,
gmx_fatal(FARGS, "The checkpoint file you provided is from an essential dynamics or flooding\n"
"simulation. Please also set the .edi file on the command line with -ei.\n");
}
+
}
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Activating essential dynamics via files passed to "
+ "gmx mdrun -edi will change in future to be files passed to "
+ "gmx grompp and the related .mdp options may change also.");
/* Open input and output files, allocate space for ED data structure */
auto edHandle = ed_open(mtop->natoms, oh, ediFileName, edoFileName, bAppend, oenv, cr);
PrivateImplPointer<Impl> impl_;
};
+class MDLogger;
} // namespace gmx
/*! \brief Applies essential dynamics constrains as defined in the .edi input file.
/*! \brief Initializes the essential dynamics and flooding module.
*
+ * \param mdlog Logger.
* \param ediFileName Essential dynamics input file.
* \param edoFileName Output file for essential dynamics data.
* \param mtop Molecular topology.
* \returns A pointer to the ED data structure.
*/
std::unique_ptr<gmx::EssentialDynamics> init_edsam(
+ const gmx::MDLogger &mdlog,
const char *ediFileName,
const char *edoFileName,
const gmx_mtop_t *mtop,
{
return 0;
}
+ fprintf(stdout, "Note that major changes are planned in future for "
+ "editconf, to improve usability and utility.");
bIndex = opt2bSet("-n", NFILE, fnm) || bNDEF;
bMead = opt2bSet("-mead", NFILE, fnm);
{
return 0;
}
+ fprintf(stdout, "Note that major changes are planned in future for "
+ "eneconv, to improve usability and utility.");
+
tadjust = 0;
nremax = 0;
nset = 0;
{
return 0;
}
+ fprintf(stdout, "Note that major changes are planned in future for "
+ "trjcat, to improve usability and utility.");
+
auto timeUnit = output_env_get_time_unit(oenv);
bIndex = ftp2bSet(efNDX, NFILE, fnm);
{
return 0;
}
+ fprintf(stdout, "Note that major changes are planned in future for "
+ "trjconv, to improve usability and utility.");
top_file = ftp2fn(efTPS, NFILE, fnm);
"position relative to neighboring atoms. Additionally, all atoms in the",
"aromatic rings of the standard amino acids (i.e. PHE, TRP, TYR and HIS)",
"can be converted into virtual sites, eliminating the fast improper dihedral",
- "fluctuations in these rings. [BB]Note[bb] that in this case all other hydrogen",
+ "fluctuations in these rings (but this feature is deprecated).",
+ "[BB]Note[bb] that in this case all other hydrogen",
"atoms are also converted to virtual sites. The mass of all atoms that are",
"converted into virtual sites, is added to the heavy atoms.[PAR]",
"Also slowing down of dihedral motion can be done with [TT]-heavyh[tt]",
}
if (bVsites)
{
+ if (bVsiteAromatics)
+ {
+ fprintf(stdout, "The conversion of aromatic rings into virtual sites is deprecated "
+ "and may be removed in a future version of GROMACS");
+ }
/* determine which atoms will be vsites and add dummy masses
also renumber atom numbers in plist[0..F_NRE]! */
do_vsites(nrtp, rtp, atype, atoms, tab, x, plist,
gmx_bool rerun = FALSE;
//! Re-construct virual sites durin a rerun simulation
gmx_bool rerunConstructVsites = FALSE;
- //! Request to do global communication at this interval in steps, -1 is determine from inputrec
+ //! Request to do global communication at this interval in steps, -1 is determine from inputrec (deprecated).
int globalCommunicationInterval = -1;
//! Try to make the simulation binary reproducible
gmx_bool reproducible = FALSE;
if (MASTER(cr))
{
+ fprintf(fplog, "Note: it is expected that in future gmx mdrun -membed will not be the "
+ "way to access this feature, perhaps changing to e.g. gmx membed.");
/* get input data out membed file */
try
{
if (PAR(cr))
{
- gmx_input("Sorry, parallel g_membed is not yet fully functional.");
+ gmx_input("Sorry, parallel membed is not yet fully functional.");
}
if (*cpt >= 0)
if (opt2bSet("-ei", nfile, fnm) || observablesHistory->edsamHistory != nullptr)
{
/* Initialize essential dynamics sampling */
- ed = init_edsam(opt2fn_null("-ei", nfile, fnm), opt2fn("-eo", nfile, fnm),
+ ed = init_edsam(mdlog,
+ opt2fn_null("-ei", nfile, fnm), opt2fn("-eo", nfile, fnm),
top_global,
ir, cr, constr,
state_global, observablesHistory,
int m, step, nminstep;
auto mdatoms = mdAtoms->mdatoms();
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Note that activating conjugate gradient energy minimization via the "
+ "integrator .mdp option and the command gmx mdrun may "
+ "be available in a different form in a future version of GROMACS, "
+ "e.g. gmx minimize and an .mdp option.");
+
step = 0;
if (MASTER(cr))
int mdof_flags;
auto mdatoms = mdAtoms->mdatoms();
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Note that activating L-BFGS energy minimization via the "
+ "integrator .mdp option and the command gmx mdrun may "
+ "be available in a different form in a future version of GROMACS, "
+ "e.g. gmx minimize and an .mdp option.");
+
if (PAR(cr))
{
gmx_fatal(FARGS, "L-BFGS minimization only supports a single rank");
int steps_accepted = 0;
auto mdatoms = mdAtoms->mdatoms();
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Note that activating steepest-descent energy minimization via the "
+ "integrator .mdp option and the command gmx mdrun may "
+ "be available in a different form in a future version of GROMACS, "
+ "e.g. gmx minimize and an .mdp option.");
+
/* Create 2 states on the stack and extract pointers that we will swap */
em_state_t s0 {}, s1 {};
em_state_t *s_min = &s0;
bool bIsMaster = MASTER(cr);
auto mdatoms = mdAtoms->mdatoms();
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Note that activating normal-mode analysis via the integrator "
+ ".mdp option and the command gmx mdrun may "
+ "be available in a different form in a future version of GROMACS, "
+ "e.g. gmx normal-modes.");
+
if (constr != nullptr)
{
gmx_fatal(FARGS, "Constraints present with Normal Mode Analysis, this combination is not supported");
// signals, and will use this object to achieve that.
SimulationSignaller nullSignaller(nullptr, nullptr, nullptr, false, false);
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Note that it is planned that the command gmx mdrun -rerun will "
+ "be available in a different form in a future version of GROMACS, "
+ "e.g. gmx rerun -f.");
+
if (ir->bExpanded)
{
gmx_fatal(FARGS, "Expanded ensemble not supported by rerun.");
#include "gromacs/utility/cstringutil.h"
#include "gromacs/utility/fatalerror.h"
#include "gromacs/utility/gmxassert.h"
+#include "gromacs/utility/logger.h"
#include "gromacs/utility/smalloc.h"
#include "integrator.h"
GMX_UNUSED_VALUE(outputProvider);
+ GMX_LOG(mdlog.info).asParagraph().
+ appendText("Note that it is planned to change the command gmx mdrun -tpi "
+ "(and -tpic) to make the functionality available in a different "
+ "form in a future version of GROMACS, e.g. gmx test-particle-insertion.");
+
/* Since there is no upper limit to the insertion energies,
* we need to set an upper limit for the distribution output.
*/
#include "gromacs/commandline/pargs.h"
#include "gromacs/compat/make_unique.h"
#include "gromacs/domdec/domdec.h"
+#include "gromacs/fileio/gmxfio.h"
#include "gromacs/gmxlib/network.h"
#include "gromacs/mdlib/mdrun.h"
#include "gromacs/mdrun/logging.h"
"be given. For the topology to work, a file name given here must match a",
"character sequence before the file extension. That sequence is: an underscore,",
"then a 'b' for bonds, an 'a' for angles or a 'd' for dihedrals,",
- "and finally the matching table number index used in the topology.[PAR]",
+ "and finally the matching table number index used in the topology. Note that,",
+ "these options are deprecated, and in future will be available via grompp.[PAR]",
"The options [TT]-px[tt] and [TT]-pf[tt] are used for writing pull COM",
"coordinates and forces when pulling is selected",
"in the [REF].mdp[ref] file.[PAR]",
"file is written at the first neighbor search step where the run time",
"exceeds [TT]-maxh[tt]\\*0.99 hours. This option is particularly useful in",
"combination with setting [TT]nsteps[tt] to -1 either in the mdp or using the",
- "similarly named command line option. This results in an infinite run,",
+ "similarly named command line option (although the latter is deprecated).",
+ "This results in an infinite run,",
"terminated only when the time limit set by [TT]-maxh[tt] is reached (if any)",
"or upon receiving a signal.",
"[PAR]",
"direction of the corresponding DD cells. Only effective with static "
"load balancing." },
{ "-gcom", FALSE, etINT, {&mdrunOptions.globalCommunicationInterval},
- "Global communication frequency" },
+ "Global communication frequency (deprecated)" },
{ "-nb", FALSE, etENUM, {nbpu_opt_choices},
"Calculate non-bonded interactions on" },
{ "-nstlist", FALSE, etINT, {&nstlist_cmdline},
{ "-append", FALSE, etBOOL, {&bTryToAppendFiles},
"Append to previous output files when continuing from checkpoint instead of adding the simulation part number to all file names" },
{ "-nsteps", FALSE, etINT64, {&mdrunOptions.numStepsCommandline},
- "Run this number of steps, overrides .mdp file option (-1 means infinite, -2 means use mdp option, smaller is invalid)" },
+ "Run this number of steps, overrides .mdp file option (-1 means infinite, -2 means use mdp option, smaller is invalid) (deprecated)" },
{ "-maxh", FALSE, etREAL, {&mdrunOptions.maximumHoursToRun},
"Terminate after 0.99 times this time (hours)" },
{ "-replex", FALSE, etINT, {&replExParams.exchangeInterval},
{ "-rerunvsite", FALSE, etBOOL, {&mdrunOptions.rerunConstructVsites},
"HIDDENRecalculate virtual site coordinates with [TT]-rerun[tt]" },
{ "-confout", FALSE, etBOOL, {&mdrunOptions.writeConfout},
- "HIDDENWrite the last configuration with [TT]-c[tt] and force checkpointing at the last step" },
+ "HIDDENWrite the last configuration with [TT]-c[tt] and force checkpointing at the last step (deprecated)" },
{ "-stepout", FALSE, etINT, {&mdrunOptions.verboseStepPrintInterval},
- "HIDDENFrequency of writing the remaining wall clock time for the run" },
+ "HIDDENFrequency of writing the remaining wall clock time for the run (deprecated)" },
{ "-resetstep", FALSE, etINT, {&mdrunOptions.timingOptions.resetStep},
- "HIDDENReset cycle counters after these many time steps" },
+ "HIDDENReset cycle counters after these many time steps (deprecated)" },
{ "-resethway", FALSE, etBOOL, {&mdrunOptions.timingOptions.resetHalfway},
- "HIDDENReset the cycle counters after half the number of steps or halfway [TT]-maxh[tt]" }
+ "HIDDENReset the cycle counters after half the number of steps or halfway [TT]-maxh[tt] (deprecated)" }
};
int rc;
domdecOptions.numCells[YY] = roundToInt(realddxyz[YY]);
domdecOptions.numCells[ZZ] = roundToInt(realddxyz[ZZ]);
+ if (logFileGuard != nullptr && !mdrunOptions.continuationOptions.appendFiles)
+ {
+ FILE *fplog = gmx_fio_getfp(logFileGuard.get());
+ if (opt2parg_bSet("-gcom", asize(pa), pa))
+ {
+ fprintf(fplog, "Note that gmx mdrun -gcom is deprecated, and will be removed\n"
+ "in a future version of GROMACS.\n\n");
+ }
+ if (opt2bSet("-table", filenames().size(), filenames().data()) ||
+ opt2bSet("-tablep", filenames().size(), filenames().data()) ||
+ opt2bSet("-tableb", filenames().size(), filenames().data()))
+ {
+ fprintf(fplog, "Note that gmx mdrun -table options are deprecated. Table reading\n"
+ "will likely be supported by grompp in a future version of GROMACS.\n\n");
+ }
+ if (opt2parg_bSet("-confout", asize(pa), pa) ||
+ opt2parg_bSet("-resetstep", asize(pa), pa) ||
+ opt2parg_bSet("-resethway", asize(pa), pa))
+ {
+ fprintf(fplog, "Note that gmx mdrun options intended for benchmarking, including\n"
+ "-confout, -resetstep, and -resethway are deprecated. They will\n"
+ "likely be supported by gmx benchmark in a future version of GROMACS.\n\n");
+ }
+ if (opt2parg_bSet("-nsteps", asize(pa), pa))
+ {
+ fprintf(fplog, "Note that gmx mdrun -nsteps is deprecated. Use gmx convert-tpr\n"
+ "or gmx grompp to change the intended number of steps for your\n"
+ "simulation.\n\n");
+ }
+ }
+
/* The Context is a shared resource owned by the client code.
* A more complete design should address handles to resources with appropriate
* lifetimes and invariants for the resources allocated to the client,