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, 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.
50 #include "gromacs/commandline/pargs.h"
51 #include "gromacs/fileio/confio.h"
52 #include "gromacs/math/units.h"
53 #include "gromacs/math/vec.h"
54 #include "gromacs/mdlib/force.h"
55 #include "gromacs/pbcutil/pbc.h"
56 #include "gromacs/random/threefry.h"
57 #include "gromacs/random/uniformintdistribution.h"
58 #include "gromacs/topology/index.h"
59 #include "gromacs/topology/topology.h"
60 #include "gromacs/utility/arrayref.h"
61 #include "gromacs/utility/arraysize.h"
62 #include "gromacs/utility/basedefinitions.h"
63 #include "gromacs/utility/cstringutil.h"
64 #include "gromacs/utility/fatalerror.h"
65 #include "gromacs/utility/futil.h"
66 #include "gromacs/utility/smalloc.h"
69 /*! \brief Return whether any atoms of two groups are below minimum distance.
71 * \param[in] pbc the periodic boundary conditions
72 * \param[in] x the coordinates
73 * \param[in] smallerGroupIndices the atom indices of the first group to check
74 * \param[in] largerGroupIndices the atom indices of the second group to check
75 * \param[in] minimumDistance the minimum required distance betwenn any atom in
76 * the first and second group
77 * \returns true if any distance between an atom from group A and group B is
78 * smaller than a minimum distance.
80 static bool groupsCloserThanCutoffWithPbc(t_pbc* pbc,
82 gmx::ArrayRef<const int> smallerGroupIndices,
83 gmx::ArrayRef<const int> largerGroupIndices,
86 const real minimumDistance2 = minimumDistance * minimumDistance;
87 for (int aIndex : largerGroupIndices)
89 for (int bIndex : smallerGroupIndices)
92 pbc_dx(pbc, x[aIndex], x[bIndex], dx);
93 if (norm2(dx) < minimumDistance2)
102 /*! \brief Calculate the solvent molecule atom indices from molecule number.
104 * \note the solvent group index has to be continuous
106 * \param[in] solventMoleculeNumber the number of the solvent molecule
107 * \param[in] numberAtomsPerSolventMolecule how many atoms each solvent molecule contains
108 * \param[in] solventGroupIndex continuous index of solvent atoms
110 * \returns atom indices of the specified solvent molecule
112 static std::vector<int> solventMoleculeIndices(int solventMoleculeNumber,
113 int numberAtomsPerSolventMolecule,
114 gmx::ArrayRef<const int> solventGroupIndex)
116 std::vector<int> indices(numberAtomsPerSolventMolecule);
117 for (int solventAtomNumber = 0; solventAtomNumber < numberAtomsPerSolventMolecule; ++solventAtomNumber)
119 indices[solventAtomNumber] =
120 solventGroupIndex[numberAtomsPerSolventMolecule * solventMoleculeNumber + solventAtomNumber];
125 static void insert_ion(int nsa,
126 std::vector<int>* solventMoleculesForReplacement,
128 gmx::ArrayRef<const int> index,
136 std::vector<int>* notSolventGroup)
138 std::vector<int> solventMoleculeAtomsToBeReplaced =
139 solventMoleculeIndices(solventMoleculesForReplacement->back(), nsa, index);
143 // check for proximity to non-solvent
144 while (groupsCloserThanCutoffWithPbc(pbc, x, solventMoleculeAtomsToBeReplaced, *notSolventGroup, rmin)
145 && !solventMoleculesForReplacement->empty())
147 solventMoleculesForReplacement->pop_back();
148 solventMoleculeAtomsToBeReplaced =
149 solventMoleculeIndices(solventMoleculesForReplacement->back(), nsa, index);
153 if (solventMoleculesForReplacement->empty())
155 gmx_fatal(FARGS, "No more replaceable solvent!");
158 fprintf(stderr, "Replacing solvent molecule %d (atom %d) with %s\n",
159 solventMoleculesForReplacement->back(), solventMoleculeAtomsToBeReplaced[0], ionname);
161 /* Replace solvent molecule charges with ion charge */
162 notSolventGroup->push_back(solventMoleculeAtomsToBeReplaced[0]);
163 repl[solventMoleculesForReplacement->back()] = sign;
165 // The first solvent molecule atom is replaced with an ion and the respective
166 // charge while the rest of the solvent molecule atoms is set to 0 charge.
167 atoms->atom[solventMoleculeAtomsToBeReplaced.front()].q = q;
168 for (auto replacedMoleculeAtom = solventMoleculeAtomsToBeReplaced.begin() + 1;
169 replacedMoleculeAtom != solventMoleculeAtomsToBeReplaced.end(); ++replacedMoleculeAtom)
171 atoms->atom[*replacedMoleculeAtom].q = 0;
173 solventMoleculesForReplacement->pop_back();
177 static char* aname(const char* mname)
182 str = gmx_strdup(mname);
183 i = std::strlen(str) - 1;
184 while (i > 1 && (std::isdigit(str[i]) || (str[i] == '+') || (str[i] == '-')))
193 static void sort_ions(int nsa,
196 gmx::ArrayRef<const int> index,
204 int i, j, k, r, np, nn, starta, startr, npi, nni;
209 /* Put all the solvent in front and count the added ions */
213 for (i = 0; i < nw; i++)
218 for (k = 0; k < nsa; k++)
220 copy_rvec(x[index[nsa * i + k]], xt[j++]);
235 /* Put the positive and negative ions at the end */
236 starta = index[nsa * (nw - np - nn)];
237 startr = atoms->atom[starta].resind;
241 for (i = 0; i < nw; i++)
248 copy_rvec(x[index[nsa * i]], xt[j]);
249 atoms->atomname[j] = paptr;
250 atoms->atom[j].resind = k;
251 atoms->resinfo[k].name = pptr;
256 j = starta + np + nni;
257 k = startr + np + nni;
258 copy_rvec(x[index[nsa * i]], xt[j]);
259 atoms->atomname[j] = naptr;
260 atoms->atom[j].resind = k;
261 atoms->resinfo[k].name = nptr;
265 for (i = index[nsa * nw - 1] + 1; i < atoms->nr; i++)
267 j = i - (nsa - 1) * (np + nn);
268 atoms->atomname[j] = atoms->atomname[i];
269 atoms->atom[j] = atoms->atom[i];
270 copy_rvec(x[i], xt[j]);
272 atoms->nr -= (nsa - 1) * (np + nn);
274 /* Copy the new positions back */
275 for (i = index[0]; i < atoms->nr; i++)
277 copy_rvec(xt[i], x[i]);
283 static void update_topol(const char* topinout, int p_num, int n_num, const char* p_name, const char* n_name, char* grpname)
286 char buf[STRLEN], buf2[STRLEN], *temp, **mol_line = nullptr;
287 int line, i, nmol_line, sol_line, nsol_last;
289 char temporary_filename[STRLEN];
291 printf("\nProcessing topology\n");
292 fpin = gmx_ffopen(topinout, "r");
293 std::strncpy(temporary_filename, "temp.topXXXXXX", STRLEN);
294 fpout = gmx_fopen_temporary(temporary_filename);
301 while (fgets(buf, STRLEN, fpin))
304 std::strcpy(buf2, buf);
305 if ((temp = std::strchr(buf2, '\n')) != nullptr)
313 if ((temp = std::strchr(buf2, '\n')) != nullptr)
318 if (buf2[std::strlen(buf2) - 1] == ']')
320 buf2[std::strlen(buf2) - 1] = '\0';
323 bMolecules = (gmx_strcasecmp(buf2, "molecules") == 0);
325 fprintf(fpout, "%s", buf);
327 else if (!bMolecules)
329 fprintf(fpout, "%s", buf);
333 /* Check if this is a line with solvent molecules */
334 sscanf(buf, "%s", buf2);
335 if (gmx_strcasecmp(buf2, grpname) == 0)
337 sol_line = nmol_line;
338 sscanf(buf, "%*s %d", &nsol_last);
340 /* Store this molecules section line */
341 srenew(mol_line, nmol_line + 1);
342 mol_line[nmol_line] = gmx_strdup(buf);
352 "No line with moleculetype '%s' found the [ molecules ] section of file '%s'",
355 if (nsol_last < p_num + n_num)
359 "The last entry for moleculetype '%s' in the [ molecules ] section of file '%s' "
360 "has less solvent molecules (%d) than were replaced (%d)",
361 grpname, topinout, nsol_last, p_num + n_num);
364 /* Print all the molecule entries */
365 for (i = 0; i < nmol_line; i++)
369 fprintf(fpout, "%s", mol_line[i]);
373 printf("Replacing %d solute molecules in topology file (%s) "
374 " by %d %s and %d %s ions.\n",
375 p_num + n_num, topinout, p_num, p_name, n_num, n_name);
376 nsol_last -= p_num + n_num;
379 fprintf(fpout, "%-10s %d\n", grpname, nsol_last);
383 fprintf(fpout, "%-15s %d\n", p_name, p_num);
387 fprintf(fpout, "%-15s %d\n", n_name, n_num);
392 make_backup(topinout);
393 gmx_file_rename(temporary_filename, topinout);
396 /*! \brief Return all atom indices that do not belong to an index group.
397 * \param[in] nrAtoms the total number of atoms
398 * \param[in] indexGroup the index group to be inverted. Note that a copy is
399 * made in order to sort the group indices
400 * \returns the inverted group indices
402 static std::vector<int> invertIndexGroup(int nrAtoms, std::vector<int> indexGroup)
404 // Add the indices -1 and nrAtoms, so that all intervals 0 .. firstofIndexGroup
405 // as well as lastOfIndexGroup .. nrAtoms are covered for the inverted indexgroup
406 indexGroup.push_back(-1);
407 indexGroup.push_back(nrAtoms);
408 std::sort(indexGroup.begin(), indexGroup.end());
410 // construct the inverted index group by adding all indicies between two
411 // indices of indexGroup
412 std::vector<int> invertedGroup;
413 for (auto indexGroupIt = std::begin(indexGroup); indexGroupIt != std::end(indexGroup) - 1; ++indexGroupIt)
415 const int firstToAddToInvertedGroup = *indexGroupIt + 1;
416 const int numIndicesToAdd = *(indexGroupIt + 1) - firstToAddToInvertedGroup;
417 if (numIndicesToAdd > 0)
419 invertedGroup.resize(invertedGroup.size() + numIndicesToAdd);
420 std::iota(std::end(invertedGroup) - numIndicesToAdd, std::end(invertedGroup),
421 firstToAddToInvertedGroup);
425 return invertedGroup;
428 int gmx_genion(int argc, char* argv[])
430 const char* desc[] = {
431 "[THISMODULE] randomly replaces solvent molecules with monoatomic ions.",
432 "The group of solvent molecules should be continuous and all molecules",
433 "should have the same number of atoms.",
434 "The user should add the ion molecules to the topology file or use",
435 "the [TT]-p[tt] option to automatically modify the topology.[PAR]",
436 "The ion molecule type, residue and atom names in all force fields",
437 "are the capitalized element names without sign. This molecule name",
438 "should be given with [TT]-pname[tt] or [TT]-nname[tt], and the",
439 "[TT][molecules][tt] section of your topology updated accordingly,",
440 "either by hand or with [TT]-p[tt]. Do not use an atom name instead!",
441 "[PAR]Ions which can have multiple charge states get the multiplicity",
442 "added, without sign, for the uncommon states only.[PAR]",
443 "For larger ions, e.g. sulfate we recommended using [gmx-insert-molecules]."
445 const char* bugs[] = {
446 "If you specify a salt concentration existing ions are not taken into "
447 "account. In effect you therefore specify the amount of salt to be added.",
449 int p_num = 0, n_num = 0, p_q = 1, n_q = -1;
450 const char *p_name = "NA", *n_name = "CL";
451 real rmin = 0.6, conc = 0;
453 gmx_bool bNeutral = FALSE;
455 { "-np", FALSE, etINT, { &p_num }, "Number of positive ions" },
456 { "-pname", FALSE, etSTR, { &p_name }, "Name of the positive ion" },
457 { "-pq", FALSE, etINT, { &p_q }, "Charge of the positive ion" },
458 { "-nn", FALSE, etINT, { &n_num }, "Number of negative ions" },
459 { "-nname", FALSE, etSTR, { &n_name }, "Name of the negative ion" },
460 { "-nq", FALSE, etINT, { &n_q }, "Charge of the negative ion" },
461 { "-rmin", FALSE, etREAL, { &rmin }, "Minimum distance between ions and non-solvent" },
462 { "-seed", FALSE, etINT, { &seed }, "Seed for random number generator (0 means generate)" },
467 "Specify salt concentration (mol/liter). This will add sufficient ions to reach up to "
468 "the specified concentration as computed from the volume of the cell in the input "
469 "[REF].tpr[ref] file. Overrides the [TT]-np[tt] and [TT]-nn[tt] options." },
474 "This option will add enough ions to neutralize the system. These ions are added on top "
475 "of those specified with [TT]-np[tt]/[TT]-nn[tt] or [TT]-conc[tt]. " }
485 int nw, nsa, nsalt, iqtot;
486 gmx_output_env_t* oenv = nullptr;
487 t_filenm fnm[] = { { efTPR, nullptr, nullptr, ffREAD },
488 { efNDX, nullptr, nullptr, ffOPTRD },
489 { efSTO, "-o", nullptr, ffWRITE },
490 { efTOP, "-p", "topol", ffOPTRW } };
491 #define NFILE asize(fnm)
493 if (!parse_common_args(&argc, argv, 0, NFILE, fnm, asize(pa), pa, asize(desc), desc,
494 asize(bugs), bugs, &oenv))
498 output_env_done(oenv);
503 /* Check input for something sensible */
504 if ((p_num < 0) || (n_num < 0))
506 gmx_fatal(FARGS, "Negative number of ions to add?");
509 if (conc > 0 && (p_num > 0 || n_num > 0))
511 fprintf(stderr, "WARNING: -conc specified, overriding -nn and -np.\n");
514 /* Read atom positions and charges */
515 read_tps_conf(ftp2fn(efTPR, NFILE, fnm), &top, &pbcType, &x, nullptr, box, FALSE);
518 /* Compute total charge */
520 for (int i = 0; (i < atoms.nr); i++)
522 qtot += atoms.atom[i].q;
524 iqtot = gmx::roundToInt(qtot);
529 /* Compute number of ions to be added */
531 nsalt = gmx::roundToInt(conc * vol * AVOGADRO / 1e24);
532 p_num = abs(nsalt * n_q);
533 n_num = abs(nsalt * p_q);
537 int qdelta = p_num * p_q + n_num * n_q + iqtot;
539 /* Check if the system is neutralizable
540 * is (qdelta == p_q*p_num + n_q*n_num) solvable for p_num and n_num? */
541 int gcd = std::gcd(n_q, p_q);
542 if ((qdelta % gcd) != 0)
545 "Can't neutralize this system using -nq %d and"
565 char* pptr = gmx_strdup(p_name);
566 char* paptr = aname(p_name);
567 char* nptr = gmx_strdup(n_name);
568 char* naptr = aname(n_name);
570 if ((p_num == 0) && (n_num == 0))
572 fprintf(stderr, "No ions to add, will just copy input configuration.\n");
576 char* grpname = nullptr;
578 printf("Will try to add %d %s ions and %d %s ions.\n", p_num, p_name, n_num, n_name);
579 printf("Select a continuous group of solvent molecules\n");
581 std::vector<int> solventGroup;
583 int* index = nullptr;
585 get_index(&atoms, ftp2fn_null(efNDX, NFILE, fnm), 1, &nwa, &index, &grpname);
586 solventGroup.assign(index, index + nwa);
590 for (gmx::index i = 1; i < gmx::ssize(solventGroup); i++)
592 if (solventGroup[i] != solventGroup[i - 1] + 1)
595 "The solvent group %s is not continuous: "
596 "index[%d]=%d, index[%d]=%d",
597 grpname, int(i), solventGroup[i - 1] + 1, int(i + 1), solventGroup[i] + 1);
601 while ((nsa < gmx::ssize(solventGroup))
602 && (atoms.atom[solventGroup[nsa]].resind == atoms.atom[solventGroup[nsa - 1]].resind))
606 if (solventGroup.size() % nsa != 0)
608 gmx_fatal(FARGS, "Your solvent group size (%td) is not a multiple of %d",
609 gmx::ssize(solventGroup), nsa);
611 nw = solventGroup.size() / nsa;
612 fprintf(stderr, "Number of (%d-atomic) solvent molecules: %d\n", nsa, nw);
613 if (p_num + n_num > nw)
615 gmx_fatal(FARGS, "Not enough solvent for adding ions");
618 if (opt2bSet("-p", NFILE, fnm))
620 update_topol(opt2fn("-p", NFILE, fnm), p_num, n_num, p_name, n_name, grpname);
624 set_pbc(&pbc, pbcType, box);
629 // For now we make do with 32 bits to avoid changing the user input to 64 bit hex
630 seed = static_cast<int>(gmx::makeRandomSeed());
632 fprintf(stderr, "Using random seed %d.\n", seed);
635 std::vector<int> notSolventGroup = invertIndexGroup(atoms.nr, solventGroup);
637 std::vector<int> solventMoleculesForReplacement(nw);
638 std::iota(std::begin(solventMoleculesForReplacement), std::end(solventMoleculesForReplacement), 0);
640 // Randomly shuffle the solvent molecules that shall be replaced by ions
641 // then pick molecules from the back of the list as replacement candidates
642 gmx::DefaultRandomEngine rng(seed);
643 std::shuffle(std::begin(solventMoleculesForReplacement),
644 std::end(solventMoleculesForReplacement), rng);
646 /* Now loop over the ions that have to be placed */
649 insert_ion(nsa, &solventMoleculesForReplacement, repl, solventGroup, x, &pbc, 1, p_q,
650 p_name, &atoms, rmin, ¬SolventGroup);
654 insert_ion(nsa, &solventMoleculesForReplacement, repl, solventGroup, x, &pbc, -1, n_q,
655 n_name, &atoms, rmin, ¬SolventGroup);
657 fprintf(stderr, "\n");
661 sort_ions(nsa, nw, repl, solventGroup, &atoms, x, &pptr, &nptr, &paptr, &naptr);
668 sfree(atoms.pdbinfo);
669 atoms.pdbinfo = nullptr;
670 write_sto_conf(ftp2fn(efSTO, NFILE, fnm), *top.name, &atoms, x, nullptr, pbcType, box);
678 output_env_done(oenv);