Skip to content

Commit 09fb4bb

Browse files
andyclaude
andcommitted
Merge wip/1118-solvate: Solvate as a Builder command, client-side, for every code; GROMACS Prepare skips gmx solvate when solvent is present; the old Solvate window behind Preferences > Advanced (#1118)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LPtdCqiFHmFNbScUSGgzbs
2 parents 076992a + 966305d commit 09fb4bb

26 files changed

Lines changed: 1294 additions & 7 deletions

‎CMakeLists.txt‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2596,6 +2596,15 @@ add_executable(layer_stack_test tests/layerstack/layer_stack_test.C)
25962596
target_link_libraries(layer_stack_test PRIVATE eccetdat ecceutil)
25972597
add_test(NAME layer_stack COMMAND layer_stack_test)
25982598

2599+
# tests/solvate (#1118): solvent placement for the Builder's Solvate, wx-free.
2600+
add_executable(solvate_test tests/solvate/solvate_test.C)
2601+
target_link_libraries(solvate_test PRIVATE eccetdat ecceutil)
2602+
add_executable(solvate_cli tests/solvate/solvate_cli.C)
2603+
target_link_libraries(solvate_cli PRIVATE eccetdat ecceutil)
2604+
add_test(NAME solvate COMMAND solvate_test ${CMAKE_SOURCE_DIR})
2605+
set_tests_properties(solvate PROPERTIES
2606+
ENVIRONMENT "ECCE_HOME=${CMAKE_SOURCE_DIR};ECCE_REALUSER=solvate;ECCE_REALUSERHOME=${CMAKE_BINARY_DIR}/solvate-home")
2607+
25992608
# tests/metal_bonds (#325): Metal bonds need no nubs.
26002609
add_executable(metal_bond_test tests/metal_bonds/metal_bond_test.C)
26012610
target_link_libraries(metal_bond_test PRIVATE eccetdat ecceutil)
@@ -2909,7 +2918,8 @@ add_test(NAME gromacs_lone_ion_names
29092918
set_tests_properties(gromacs_lone_ion_names PROPERTIES TIMEOUT 300 SKIP_RETURN_CODE 77)
29102919
add_test(NAME gromacs_prepare_options
29112920
COMMAND ${PYTHON3_EXECUTABLE}
2912-
${CMAKE_SOURCE_DIR}/tests/gromacs_md/prepare_options_test.py)
2921+
${CMAKE_SOURCE_DIR}/tests/gromacs_md/prepare_options_test.py
2922+
--solvate-cli $<TARGET_FILE:solvate_cli>)
29132923
set_tests_properties(gromacs_prepare_options PROPERTIES TIMEOUT 600 SKIP_RETURN_CODE 77)
29142924
# Every tool a resource type enables has a summary view for its content type.
29152925
add_test(NAME resource_tool_views
@@ -5473,6 +5483,14 @@ if(PYTHON3_EXECUTABLE)
54735483
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/tests/apps)
54745484
set_tests_properties(apps_builder_cut_cluster PROPERTIES TIMEOUT 600
54755485
SKIP_RETURN_CODE 77)
5486+
# Build > Solvate: water round methanol, saved and undone (#1118).
5487+
add_test(NAME apps_builder_solvate
5488+
COMMAND ${PYTHON3_EXECUTABLE}
5489+
${CMAKE_CURRENT_SOURCE_DIR}/tests/apps/builder_solvate_test.py
5490+
--build ${CMAKE_BINARY_DIR}
5491+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/tests/apps)
5492+
set_tests_properties(apps_builder_solvate PROPERTIES TIMEOUT 600
5493+
SKIP_RETURN_CODE 77)
54765494
# No bond orders in building; Clean's derived orders and bond lengths (#439).
54775495
add_test(NAME apps_builder_bond_model
54785496
COMMAND ${PYTHON3_EXECUTABLE}

‎docs/AGENTS.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,23 @@ Angstrom, N from 1; without `center` the selection is the centre). It prints one
9797
caps=M`; undo restores the periodic structure. The geometry is in the wx-free
9898
`tdat/ClusterCut.H`; test `tests/apps/builder_cut_cluster_test.py`.
9999

100+
Build > Solvate (#1118) fills the periodic cell, or a rectangular cell of
101+
the structure's extent plus a margin (structure centred), with a shipped
102+
solvent box (`data/client/solvents/*.xyz`), on the client, for any code.
103+
Builder script: `solvate [solvent NAME] [margin A] [scale S]` (defaults
104+
water216, 10 A, 1.0; scale times the sum of vdW radii is the solute-solvent
105+
cut-off). It prints `BUILDER: solvate molecules=N added=M atoms=T cell=A B C
106+
density=D`; undo removes the solvent. Waters are HOH residues (OW, HW1, HW2),
107+
and GROMACS Prepare skips `gmx solvate` for a structure that has them
108+
(`Solvent already present ...` in its output). The geometry is wx-free in
109+
`tdat/Solvate.H`; `solvate_cli SOLVENT.xyz SOLUTE.xyz|- MARGIN|"a b c"
110+
[SCALE]` (build tree) writes the solvated XYZ to stdout. Tests: ctest
111+
`solvate`, `tests/apps/builder_solvate_test.py`. The old Solvate window
112+
(Condensed Reaction Study) opens only with Preferences > Advanced
113+
"Separate Solvate window" (`ECCE_SOLVATE_WINDOW=1`); otherwise a Solvate
114+
task opens in the Builder and a new Condensed Reaction Study gets no
115+
Solvate task.
116+
100117
For isolated GUI checks, `ECCE_BUILDER_SCRIPT` accepts `list Stress Tensor`,
101118
`stressinfo` (panel summary plus one `label N anchor=x,y,z` line per principal axis; anchors lie outside the cell), `vector STRESS` (the six rendered half-arrows),
102119
and `viewer Stress Tensor` (toggle). `tests/apps/stress_tensor_test.py`
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
type: pitfall
3+
title: "Atoms added to a Fragment that has residues need residues too, or dumpPDB drops them; Build > Solvate gives each water an HOH residue and dumpPDB writes CRYST1"
4+
area: codereg
5+
paths: ["src/viz/sgcommands/SolvateCmd.C", "src/tdat/chemistry/Solvate.C", "include/tdat/Solvate.H", "src/tdat/chemistry/Fragment.C", "scripts/gensub"]
6+
issues: [1118]
7+
---
8+
`Fragment::dumpPDB` writes atoms residue by residue, and only calls
9+
`FragUtil::createResidues` when the fragment has none. Atoms added after
10+
residues exist, with no residue of their own, are silently left out of the
11+
PDB that MD tasks (GROMACS Prepare) receive. `Fragment::operator=` (the copy
12+
undo uses) likewise assumes every atom has a residue and residues follow
13+
atom order. `SolvateCmd` therefore puts a residue-less solute into one
14+
`MOL` residue, then makes one `HOH`
15+
residue per water with atom names ` OW `, ` HW1`, ` HW2` (four characters:
16+
dumpPDB uses the name only when it is exactly four long).
17+
18+
dumpPDB writes `CRYST1` only for a lattice in the PDB frame (a along x, b
19+
in the xy plane); pdb2gmx then carries the box into step1.gro. The Prepare
20+
job (gensub `gromacsPrepare`) counts SOL/HOH/WAT oxygens in step1.gro: with
21+
water and a box it copies step1 to step2 (BOX=cell, editconf wording for the
22+
summary) and skips `gmx solvate`; water without a box still goes through
23+
editconf, but solvate is skipped.

‎docs/claude/codereg/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,7 @@ unit is produced in `ai.<code>`/the `.tpl`, closest to the input deck.
191191
- [Geometry constraints are edited in the Builder and stored with the calculation; the input uses them only for Geometry/GeoVib](geometry-constraints-are-edited-in-the-builder-and-stored-with-the-calculation.md)
192192
- [Gaussian: describe ECCE's support for it; never publish a comparison of Gaussian with another program](what-may-be-published-about-gaussian.md)
193193
- [GROMACS Prepare: gmx goes by file extension (.gmxpdb, .gmxtop are not read), every GROMOS force field draws a grompp warning, and the PDB must name its histidines](gromacs-prepare-gmx-goes-by-file-extension-and-gromos-warns.md)
194+
- [Build > Solvate: added atoms need residues or dumpPDB drops them; HOH residues and CRYST1 let GROMACS Prepare skip gmx solvate](builder-solvate-residues-and-cryst1-1118.md)
194195
- [GROMACS Prepare: how its outputs reach the next task (.gmxtop, .gro, posre.itp, topol_*.itp), and the places that treat a Prepare as NWChem's](gromacs-prepare-outputs-come-back-through-the-monitor-as-job-outputs.md)
195196
- [GROMACS Prepare editor (gmxprepare): MDEdBase assumes an MDCompositeModel, and a tool listed in the wrong resource type opens beside NWChem's](gromacs-prepare-editor-borrows-mdedbase-but-not-its-model.md)
196197
- [GROMACS Prepare results: ECCE-PREPARE lines feed the Progress box and the properties; the property script is found by the first key and must print every key](gromacs-prepare-results-are-echo-lines-the-desc-reads-twice.md)

‎docs/claude/wx-viewer/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,7 @@ Read this before changing any dialog, panel, sizer, grid, ewx control or the Ope
114114
- [A PDB's CRYST1 was never read into the lattice: a GROMACS box opened in the Viewer had no cell; LatticeDef(a,b,c,angles) is not the PDB frame (#930)](pdb-reader-took-no-cell-from-cryst1.md)
115115
- [CRYST1 must not reach a molecular calculation: the cell is drawn around the molecules and every viewAll frames it (#968)](crystal-cell-must-not-reach-a-molecular-calculation-968.md)
116116
- [Layer builder: spacing is along the a-b normal, shifts accumulate, tilt wraps differently from an orthogonal reference, water H 1.5 A from everything (#357)](layer-builder-traps.md)
117+
- [PBCCmd::undo asks PBC to replicate the restored lattice; a command that added the lattice restores none (#1118)](pbccmd-undo-replicate-needs-lattice-1118.md)
117118
- [Depth peeling copies from a multisampled window (#360)](depth-peeling-copies-from-a-multisampled-window.md)
118119
- [Auto-centre after property commands](auto-centre-after-property-commands.md)
119120
- ["1 1 1" in one text field reads "111" in Cantarell: one field per number](space-separated-values-need-one-field-each.md)
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
type: pitfall
3+
title: "PBCCmd::undo asks PBC to replicate the restored lattice; a command that added the lattice restores none"
4+
area: wx-viewer
5+
paths: ["src/viz/sgcommands/PBCCmd.C", "src/viz/sgcommands/SGContainer.C", "src/inv/moiv/ChemDisplayResidues.C", "src/apps/builder/PBC.C", "src/viz/sgcommands/SolvateCmd.C", "src/viz/sgcommands/PBCCreateCmd.C"]
6+
issues: [1118]
7+
---
8+
`PBCCmd::undo` publishes `GeomChange`/`ResidueChange` with value
9+
`replicate` when `shouldAutoReplicateOnUndo()`; `PBC::eventMCB` then calls
10+
`getLattice()->getReplicationFactors()` with no null check. Every PBCCmd
11+
used to start from a fragment with a lattice, so the restored fragment
12+
always had one. Solvate on a molecule is the first PBCCmd that adds the
13+
lattice; its undo segfaulted until `PBCCmd::undo` sent `replicate` only
14+
when the restored fragment has a lattice (otherwise it sends
15+
`LatticeChange`). Create lattice is a `FragCloneCmd` and never had this
16+
path. A new PBCCmd that can add or remove the lattice must be undone with
17+
Edit > Undo in a test.
18+
19+
The same undo then crashed in `ChemDisplay::bBoxResiduesAsRibbons`:
20+
`SGContainer::touchChemDisplay` rebuilt each display's `residueIndex` only
21+
when the fragment had residues, while `computeResidueAttributes` frees
22+
`residueAttributes` when it has none, so an undo from residues (the waters)
23+
to none read a stale index into a NULL array. `residueIndex` is now
24+
emptied when there are no residues.
25+
26+
`tests/apps/builder_edit_bugs_test.runBuilder` loads benzene unless
27+
`structure=None` is passed; a test that builds from SMILES without it
28+
starts from 12 extra atoms.

‎help/src/importing-a-structure.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,31 @@ replaces a different atom; the cluster can therefore reach about two bonds
155155
past the radius. The result replaces the structure,
156156
without a lattice, and **Edit > Undo** brings the periodic structure back.
157157

158+
## Fill a box with solvent
159+
160+
**Build > Solvate...** surrounds the structure with solvent molecules, for any
161+
code: GROMACS, LAMMPS, CP2K or Quantum ESPRESSO boxes, or a cluster model
162+
with explicit solvent for ORCA, xTB or ECCE-QM. It needs no other program.
163+
164+
- **Solvent box** is one of the pre-equilibrated boxes ECCE ships
165+
(water216 and water64, both water at about 0.98 g/cm3). Copies of the box
166+
are laid side by side until the cell is covered.
167+
- If the structure has a periodic cell, that cell is filled and the atoms
168+
stay where they are. Otherwise a rectangular cell is made that is the
169+
structure's extent plus the **Margin** (Å) on each side, and the structure
170+
is moved to its centre.
171+
- A solvent molecule is left out when one of its atoms is closer to an atom
172+
of the structure than the **Overlap scale** times the sum of the two van
173+
der Waals radii (1.0 by default; a smaller value packs the solvent closer).
174+
Where the cell is not a whole number of solvent boxes, molecules that
175+
would clash with the next periodic image are also left out, so the density
176+
near the cell faces is a few percent lower.
177+
178+
Each water becomes its own HOH residue with atoms OW, HW1 and HW2, so
179+
**GROMACS Prepare** takes the waters as they are: it skips `gmx solvate`,
180+
keeps the cell, and its output says so. The result is one step, and
181+
**Edit > Undo** removes the solvent again.
182+
158183
## Select within a distance
159184

160185
**Edit > Select Within Distance...** extends a selection to nearby atoms.

‎include/tdat/Solvate.H‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
/**
2+
* @file
3+
* Fill a periodic cell with copies of a pre-equilibrated solvent box
4+
* (data/client/solvents/*.xyz) around a solute (#1118). Pure geometry on
5+
* coordinate lists: no Fragment, no wx, so it can be tested and driven from
6+
* a CLI. Lengths are Angstrom; the cell's origin is (0,0,0).
7+
*
8+
* A copy of a solvent molecule is kept when its centroid lies in the cell
9+
* and none of its atoms comes closer than scale*(r1+r2) (van der Waals
10+
* radii) to a solute atom, or solventScale*(r1+r2) to an atom of a solvent
11+
* molecule already kept, both by minimum image. The second test removes
12+
* the clashes where a box that is not a whole multiple of the template
13+
* meets its own periodic image.
14+
*/
15+
#ifndef SOLVATE_HH
16+
#define SOLVATE_HH
17+
18+
#include <array>
19+
#include <string>
20+
#include <vector>
21+
22+
namespace solvate {
23+
24+
typedef std::array<double,3> Vec;
25+
typedef double Cell[3][3]; // rows are a, b, c
26+
27+
struct SolventBox {
28+
std::string name;
29+
std::vector<std::string> symbols; // element symbols
30+
std::vector<std::string> types; // atom types as in the file (OW, HW)
31+
std::vector<Vec> xyz;
32+
int molSize; // atoms per molecule
33+
double edge[3]; // orthorhombic template box
34+
SolventBox() : molSize(0) { edge[0] = edge[1] = edge[2] = 0.0; }
35+
int molecules() const { return molSize > 0 ? (int)xyz.size() / molSize : 0; }
36+
};
37+
38+
/// Read "<natoms> <atoms per molecule>", "<a> <b> <c>", then TYPE x y z.
39+
bool readSolventBox(const std::string& path, SolventBox& box,
40+
std::string* err = 0);
41+
/// Names (file stems) of the solvent boxes in a directory, sorted.
42+
std::vector<std::string> solventNames(const std::string& dir);
43+
44+
struct Options {
45+
double scale; // solute-solvent, times the sum of vdW radii
46+
double solventScale; // solvent-solvent across the cell boundary
47+
double margin; // Angstrom around the solute when there is no cell
48+
int maxAtoms; // refuse a fill larger than this
49+
Options() : scale(1.0), solventScale(0.57), margin(10.0), maxAtoms(2000000) {}
50+
};
51+
52+
struct Result {
53+
std::vector<std::string> symbols, types;
54+
std::vector<Vec> xyz;
55+
int molecules;
56+
Result() : molecules(0) {}
57+
};
58+
59+
/// Orthorhombic cell holding the solute's bounding box plus margin on every
60+
/// side; shift is what to add to the solute so it sits in the cell's middle.
61+
void marginCell(const std::vector<Vec>& solute, double margin, Cell out,
62+
Vec& shift);
63+
64+
/// Solvent molecules to add. False and *err on a degenerate cell, an empty
65+
/// template or a fill above opt.maxAtoms.
66+
bool fill(const std::vector<std::string>& soluteSymbols,
67+
const std::vector<Vec>& soluteXyz, const Cell cell,
68+
const SolventBox& box, const Options& opt, Result& out,
69+
std::string* err = 0);
70+
71+
/// Mass density (g/cm3) of the given atoms in the cell.
72+
double density(const std::vector<std::string>& symbols, const Cell cell);
73+
74+
/// Water template (O, H, H per molecule)?
75+
bool isWater(const SolventBox& box);
76+
77+
} // namespace solvate
78+
79+
#endif

‎include/viz/SolvateCmd.H‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#ifndef SOLVATECMD_H
2+
#define SOLVATECMD_H
3+
4+
#include "viz/PBCCmd.H"
5+
6+
/**
7+
* Fill the periodic cell, or a box of `margin` Angstrom around the
8+
* structure when it has none, with a shipped solvent box (#1118).
9+
* Parameters: solvent (file stem in data/client/solvents), margin, scale
10+
* (solute-solvent cut-off, times the sum of vdW radii). The geometry is in
11+
* tdat/Solvate.H.
12+
*/
13+
class SolvateCmd : public PBCCmd
14+
{
15+
public:
16+
SolvateCmd(const string& name, Receiver * receiver, SGFragment *base);
17+
~SolvateCmd();
18+
19+
virtual bool execute();
20+
virtual bool shouldAutoReplicate() const;
21+
virtual bool shouldAutoReplicateOnUndo() const;
22+
23+
// After execute: solvent molecules and atoms added, solvent density.
24+
int molecules() const { return p_molecules; }
25+
int atomsAdded() const { return p_atoms; }
26+
double density() const { return p_density; }
27+
28+
protected:
29+
void init();
30+
31+
private:
32+
int p_molecules;
33+
int p_atoms;
34+
double p_density;
35+
};
36+
#endif

‎scripts/gensub‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1830,8 +1830,28 @@ GENION_RMIN=""
18301830
*) echo "Unknown SOURCE $SOURCE" >> @@OUT@@; exit 1;;
18311831
esac
18321832
1833+
# Solvent placed in the Builder (#1118): its waters came through pdb2gmx
1834+
# as SOL; keep them and the structure's cell, and add no more.
1835+
PRESOLV=`awk 'NR > 2 && substr($0, 6, 5) ~ /^(SOL|HOH|WAT) *$/ && substr($0, 11, 5) ~ /^ *O/ { n++ } END { print n + 0 }' step1.gro`
1836+
PREBOX=`tail -n 1 step1.gro | awk '{ print ($1 > 0 && $2 > 0 && $3 > 0) }'`
18331837
prepStep 2 editconf
1834-
if [ "$SOURCE" = minff ]; then
1838+
if [ "$SOURCE" != minff ] && [ "$PRESOLV" -gt 0 ] && [ "$PREBOX" = 1 ]; then
1839+
cp step1.gro step2.gro
1840+
# the box in editconf's wording, which the summary below reads
1841+
tail -n 1 step2.gro | awk '
1842+
function acosd(x) { return atan2(sqrt(1 - x * x), x) * 180 / 3.14159265358979 }
1843+
{ for (i = NF + 1; i <= 9; i++) $i = 0
1844+
la = sqrt($1 * $1 + $4 * $4 + $5 * $5); lb = sqrt($6 * $6 + $2 * $2 + $7 * $7)
1845+
lc = sqrt($8 * $8 + $9 * $9 + $3 * $3)
1846+
print "Solvent already present in the structure; its cell is kept."
1847+
printf "new box vectors : %.3f %.3f %.3f (nm)\n", la, lb, lc
1848+
printf "new box angles : %.2f %.2f %.2f (degrees)\n",
1849+
acosd(($6 * $8 + $2 * $9 + $7 * $3) / (lb * lc)),
1850+
acosd(($1 * $8 + $4 * $9 + $5 * $3) / (la * lc)),
1851+
acosd(($1 * $6 + $4 * $2 + $5 * $7) / (la * lb)) }' > prep.step
1852+
cat prep.step >> @@OUT@@
1853+
BOX=cell
1854+
elif [ "$SOURCE" = minff ]; then
18351855
# z is the stacking direction: lengthen its component of the cell vector
18361856
# and keep the tilt, which editconf -box would drop
18371857
n=`wc -l < step1.gro | tr -d ' '`
@@ -1869,7 +1889,11 @@ GENION_RMIN=""
18691889
cp prep.step prep.editconf
18701890
18711891
prepStep 3 solvate
1872-
if [ "$SOURCE" = minff ] && [ $MINFF_WATER = 0 ]; then
1892+
if [ "$SOURCE" != minff ] && [ "$PRESOLV" -gt 0 ]; then
1893+
echo "Solvent already present in the structure ($PRESOLV water molecules); gmx solvate skipped." >> @@OUT@@
1894+
echo "Solvent already present in the structure; gmx solvate skipped." >> @@LOG@@
1895+
cp step2.gro step3.gro
1896+
elif [ "$SOURCE" = minff ] && [ $MINFF_WATER = 0 ]; then
18731897
echo "No water layer requested; the mineral keeps its cell and no water is added." >> @@OUT@@
18741898
cp step2.gro step3.gro
18751899
else

0 commit comments

Comments
 (0)