pyadmd 3.3.0__tar.gz → 3.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. {pyadmd-3.3.0/src/pyadmd.egg-info → pyadmd-3.4.0}/PKG-INFO +43 -9
  2. {pyadmd-3.3.0 → pyadmd-3.4.0}/README.md +43 -9
  3. {pyadmd-3.3.0 → pyadmd-3.4.0}/pyproject.toml +1 -1
  4. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/__init__.py +1 -1
  5. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/commands.py +46 -9
  6. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/parser.py +16 -4
  7. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/console.py +1 -1
  8. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/enm/calculator.py +176 -50
  9. pyadmd-3.4.0/src/pyadmd/enm/rtb.py +264 -0
  10. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/modes/exciter.py +24 -5
  11. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/runner.py +18 -1
  12. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/system_builder.py +52 -3
  13. {pyadmd-3.3.0 → pyadmd-3.4.0/src/pyadmd.egg-info}/PKG-INFO +43 -9
  14. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/SOURCES.txt +1 -0
  15. {pyadmd-3.3.0 → pyadmd-3.4.0}/LICENSE +0 -0
  16. {pyadmd-3.3.0 → pyadmd-3.4.0}/setup.cfg +0 -0
  17. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/__main__.py +0 -0
  18. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/analysis/__init__.py +0 -0
  19. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/analysis/analyzer.py +0 -0
  20. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/analysis/completion.py +0 -0
  21. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/charmm/charmm_toppar.zip +0 -0
  22. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/charmm/wrt-nm.mdu +0 -0
  23. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/__init__.py +0 -0
  24. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/main.py +0 -0
  25. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/constants.py +0 -0
  26. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/enm/__init__.py +0 -0
  27. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/enm/analysis.py +0 -0
  28. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/fel/__init__.py +0 -0
  29. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/fel/calculator.py +0 -0
  30. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/fel/completion.py +0 -0
  31. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/geometry.py +0 -0
  32. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/__init__.py +0 -0
  33. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/dcd.py +0 -0
  34. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/namd.py +0 -0
  35. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/openmm_restart.py +0 -0
  36. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/params.py +0 -0
  37. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/state.py +0 -0
  38. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/modes/__init__.py +0 -0
  39. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/modes/projection.py +0 -0
  40. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/__init__.py +0 -0
  41. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/engine.py +0 -0
  42. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/utils.py +0 -0
  43. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/dependency_links.txt +0 -0
  44. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/entry_points.txt +0 -0
  45. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/requires.txt +0 -0
  46. {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyadmd
3
- Version: 3.3.0
3
+ Version: 3.4.0
4
4
  Summary: Adaptive Molecular Dynamics with Excited Normal Modes (aMDeNM) on OpenMM.
5
5
  Author-email: Pedro Túlio Resende-Lara <laraptr@unicamp.br>
6
6
  License-Expression: GPL-3.0-or-later
@@ -54,11 +54,13 @@ The **Adaptive Molecular Dynamics with Excited Normal Modes (aMDeNM)** method ap
54
54
  - [CHARMM Normal Modes Analysis (Optional)](#charmm-normal-modes-analysis-optional)
55
55
  - [ENM Computation](#enm-computation)
56
56
  - [Physical Motivation and Coarse-Graining](#physical-motivation-and-coarse-graining)
57
+ - [Nucleic Acid Support (SBP Model)](#nucleic-acid-support-sbp-model)
57
58
  - [Network Construction](#network-construction)
58
59
  - [The Hessian Matrix](#the-hessian-matrix)
59
60
  - [Normal Mode Analysis and Diagonalization](#normal-mode-analysis-and-diagonalization)
60
61
  - [Rigid-Body Modes and the Null Space](#rigid-body-modes-and-the-null-space)
61
62
  - [Equipartition and the Physical Meaning of Eigenvalues](#equipartition-and-the-physical-meaning-of-eigenvalues)
63
+ - [Rotations-Translations of Blocks (RTB)](#rotations-translations-of-blocks-rtb)
62
64
  - [Uniform Normal Modes Combination](#uniform-normal-modes-combination)
63
65
  - [Problem Definition](#problem-definition)
64
66
  - [Mode Subspace Geometry](#mode-subspace-geometry)
@@ -161,6 +163,20 @@ Elastic Network Models offer a powerful and computationally inexpensive alternat
161
163
 
162
164
  This motivates a **coarse-graining** strategy: instead of representing every atom with a detailed force field, the protein is reduced to a set of representative interaction sites connected by harmonic springs. In the **Cα model** (also called ANM, the Anisotropic Network Model), each residue is represented by a single point placed at its α-carbon. In the **heavy-atom model**, all non-hydrogen atoms are retained, yielding a finer-grained representation at the cost of a larger Hessian matrix. The choice of model involves a tradeoff between computational cost and the resolution of the dynamical description.
163
165
 
166
+ ### Nucleic Acid Support (SBP Model)
167
+
168
+ Protein–nucleic acid complexes (*e.g.* transcription factors, ribonucleoproteins, ion channel–RNA interactions) are supported in both ENM models. In the **heavy-atom model**, nucleic acid heavy atoms (backbone and base) are included exactly like protein heavy atoms — no special handling needed. In the **CA model**, a single α-carbon has no nucleic acid analog, so `pyadmd` represents each nucleotide with a **three-bead SBP (Sugar-Phosphate-Base) model** instead of one point:
169
+
170
+ - **P** — phosphate (backbone)
171
+ - **C1′** — sugar
172
+ - **C2** — nitrogenous base
173
+
174
+ Each bead is assigned the mass of its representative element (phosphorus for P; carbon for C1′ and C2), following the same "uniform mass by representative atom" convention already used for protein Cα (uniform carbon mass). All beads — protein Cα and nucleic P/C1′/C2 alike — are then connected pairwise by the same distance-cutoff rule described in [Network Construction](#network-construction) below, so a protein–nucleic complex is built as one mixed-resolution network, not two separate ones.
175
+
176
+ A 5′-terminal nucleotide (or any other residue) lacking a P atom is common and not an error: that residue simply contributes its C1′/C2 beads only, with a summary warning. A residue missing C1′ or C2 (unexpected — an incomplete or malformed input structure) is warned about separately and likewise contributes whatever beads it has, rather than aborting the calculation.
177
+
178
+ The three-bead SBP representation also interacts favorably with [RTB](#rotations-translations-of-blocks-rtb): unlike a single-point Cα block, a 3-atom SBP block spans a genuine rigid-body subspace, so `--rtb` gives a real dimensionality reduction on nucleic acid residues even under the Cα model.
179
+
164
180
  ### Network Construction
165
181
 
166
182
  Given a set of $`N`$ interaction sites (Cα atoms or heavy atoms) with equilibrium positions $`\mathbf{r}_i^0`$, the elastic network is constructed by connecting every pair of sites $`i`$ and $`j`$ whose equilibrium distance $`r_{ij}^0 = |\mathbf{r}_i^0 - \mathbf{r}_j^0|`$ falls within a specified **cutoff distance** $`r_c`$:
@@ -253,6 +269,20 @@ $$
253
269
 
254
270
  where $`\mathbf{H}^+`$ is the Moore-Penrose pseudo-inverse. This relationship is the foundation for the RMSF and DCCM calculations available via `pyadmd enm` (see [ENM (Standalone Normal Mode Analysis)](#enm-standalone-normal-mode-analysis)).
255
271
 
272
+ ### Rotations-Translations of Blocks (RTB)
273
+
274
+ Direct diagonalization of the full ENM Hessian becomes the dominant computational cost for large systems, particularly the heavy-atom model. **RTB** trades resolution in the highest-frequency modes for a much smaller diagonalization problem: atoms are grouped into rigid **blocks** (fixed at one residue per block in `pyadmd`), and the mass-weighted Hessian is projected onto the 6-DOF-per-block subspace (3 translations + 3 rotations per block) before diagonalizing. The resulting eigenvectors are projected back to full Cartesian space, so every downstream output (mode vectors, trajectories, collectivity, NMA-predicted RMSF/DCCM) is produced identically whether or not RTB was used.
275
+
276
+ Enabled via the **`--rtb`** flag on both `pyadmd run` and `pyadmd enm` (including any `--recalc` ENM recomputation mid-run — see [Excitation Direction Update](#excitation-direction-update)). Two consequences of the fixed one-residue-per-block choice, stated explicitly:
277
+
278
+ - **`-m HEAVY`**: each block contains multiple heavy atoms (backbone + sidechain, protein or nucleic), so it genuinely contributes up to 6 degrees of freedom — the reduced problem has roughly $`6 \times`$ the number of residues degrees of freedom instead of $`3 \times`$ the number of heavy atoms, giving a real speedup for large systems.
279
+ - **`-m CA`, protein residues**: each block is a single Cα atom, which has no meaningful rotation about itself. Each such block therefore contributes only 3 translational degrees of freedom, so a *purely protein* CA system's reduced problem has exactly the same size as the standard, non-RTB Cα Hessian. `--rtb -m CA` on a protein-only system is mathematically equivalent to plain `-m CA` (useful as a correctness check), with no computational benefit.
280
+ - **`-m CA`, nucleic acid residues**: represented by the three-bead SBP block (P, C1′, C2 — see [Nucleic Acid Support (SBP Model)](#nucleic-acid-support-sbp-model)) rather than a single point, so — like a HEAVY block — it genuinely contributes up to 6 degrees of freedom. A protein–nucleic complex run under `-m CA --rtb` therefore *does* see a real reduction on its nucleic portion, even though its protein portion does not. Only a system with no nucleic acid residues at all gets zero benefit from `--rtb` under the CA model.
281
+
282
+ `--rtb` is not compatible with `-m CHARMM`: RTB reduces the ENM Hessian, and CHARMM normal modes are precomputed externally and never diagonalized by `pyadmd`.
283
+
284
+ References: Durand, Trinquier & Sanejouand, *Biopolymers* 1994, 34:759–771; Tama, Gadea, Marques & Sanejouand, *Proteins* 2000, 41:1–7.
285
+
256
286
  ## Uniform Normal Modes Combination
257
287
 
258
288
  The program generates uniformly distributed excitation vectors through a geometry-aware repulsion-based algorithm. The approach builds on a physics-inspired framework where points behave as charged particles confined to a spherical manifold, interacting through a dimensionally-scaled potential function. Unlike naive implementations that operate in an abstract factor space, the algorithm here accounts for the true geometry of the normal mode subspace before distributing the points, guaranteeing that the resulting excitation vectors are genuinely equidistant in the physical Cartesian space that governs the molecular dynamics.
@@ -422,7 +452,7 @@ $$
422
452
 
423
453
  The default value for $`\ell_c`$ is $`0.5 m^{1/2} Å`$ (with $`m`$ being atomic mass unit), and for $`\alpha`$ is $`60°`$.
424
454
 
425
- **Note on `--recalc` and reproducibility:** when `--recalc` is set, reaching this threshold triggers a full ENM recomputation from the current structure (`SimulationRunner._recompute_enm_modes`) followed by a *brand-new random* linear combination of the recomputed modes, rather than the deterministic displacement-based correction above. This random re-combination is independent of the `-seed`/`--seed` flag described in [Uniform Normal Modes Combination](#normal-modes-linear-combination) and is not currently reproducible run-to-run — by design, since its purpose is to re-diversify the excitation direction after the mode subspace itself has changed.
455
+ **Note on `--recalc` and reproducibility:** when `--recalc` is set, reaching this threshold triggers a full ENM recomputation from the current structure (`SimulationRunner._recompute_enm_modes`) followed by a *brand-new random* linear combination of the recomputed modes, rather than the deterministic displacement-based correction above. This random re-combination is independent of the `-seed`/`--seed` flag described in [Uniform Normal Modes Combination](#normal-modes-linear-combination) and is not currently reproducible run-to-run — by design, since its purpose is to re-diversify the excitation direction after the mode subspace itself has changed. When `--rtb` is also set, this ENM recomputation is performed via the RTB reduction (see [Rotations-Translations of Blocks (RTB)](#rotations-translations-of-blocks-rtb)) rather than direct diagonalization.
426
456
 
427
457
  [Back to top ↩](#)
428
458
  * ****
@@ -510,6 +540,8 @@ below into it.
510
540
 
511
541
  - **`--full-ener`**: Write per-term energy decomposition (BOND, ANGLE, DIHED, IMPRP, CMAP, UBREY, NBFIX, NONBONDED, etc.) to `rep{N}_ener_decomp.log` every cycle
512
542
 
543
+ - **`--rtb`**: Use RTB (Rotations-Translations of Blocks) reduction for ENM diagonalization instead of direct full-Hessian diagonalization — see [Rotations-Translations of Blocks (RTB)](#rotations-translations-of-blocks-rtb). Blocks are fixed at one residue each. Only valid with `-m CA` or `-m HEAVY` (not `CHARMM`). Also applies to any `--recalc` ENM recomputation mid-run.
544
+
513
545
  ## Append
514
546
  ### Parameters
515
547
  - **`-t`/`--time`**: Simulation time to append, in ps (**required**)
@@ -552,21 +584,23 @@ Each analysis step can be independently disabled. When skipped, that metric will
552
584
 
553
585
  ## ENM
554
586
  ### Parameters
555
- - **`-i`/`--input`**: Input PDB file (**required**, unless **`-w`/`--write-modes`** is used)
587
+ - **`-i`/`--input`**: Input PDB file (**required**, unless **`-w`/`--write-modes`** is used).
556
588
 
557
- - **`-o`/`--output`**: Output folder name (**optional**. Default: **`output`**)
589
+ - **`-o`/`--output`**: Output folder name (**optional**. Default: **`output`**).
558
590
 
559
591
  - **`-m`/`--model`**: Model type, **`CA`** (Cα-only) or **`HEAVY`** (heavy atoms) (**optional**. Default: **`CA`**). Unlike `run`'s `-m`/`--model`, **`CHARMM`** is not a valid choice here — `enm` only computes ENM normal modes, not CHARMM-derived ones.
560
592
 
561
- - **`-sel`/`--selection`**: Atom selection applied to the input PDB before building the ENM (**optional**. Default: **`"protein"`**). Must be written between quotes if it contains spaces, per [MDAnalysis selection language](https://userguide.mdanalysis.org/1.1.1/selections.html).
593
+ - **`-sel`/`--selection`**: Atom selection applied to the input PDB before building the ENM (**optional**. Default: **`"protein or nucleic"`**). Must be written between quotes if it contains spaces, per [MDAnalysis selection language](https://userguide.mdanalysis.org/1.1.1/selections.html).
594
+
595
+ - **`-c`/`--cutoff`**: Interaction cutoff distance, in Å (**optional**. Default: **`15.0`** for CA, **`12.0`** for HEAVY).
562
596
 
563
- - **`-c`/`--cutoff`**: Interaction cutoff distance, in Å (**optional**. Default: **`15.0`** for CA, **`12.0`** for HEAVY)
597
+ - **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**).
564
598
 
565
- - **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**)
599
+ - **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**).
566
600
 
567
- - **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**)
601
+ - **`--output-modes`**: Number of modes (file-labeled 1 through N, where label 1 is the first non-rigid mode) to write vectors/trajectories for (**optional**. Default: **`10`**).
568
602
 
569
- - **`--output-modes`**: Number of modes (file-labeled 1 through N, where label 1 is the first non-rigid mode) to write vectors/trajectories for (**optional**. Default: **`10`**)
603
+ - **`--rtb`**: Use RTB reduction for diagonalization instead of direct full-Hessian diagonalization (**optional**. Default: disabled).
570
604
 
571
605
  ### Skip Flags
572
606
  Collectivity, contributions, RMSF, DCCM, and mode vector/trajectory writing can each be independently disabled:
@@ -26,11 +26,13 @@ The **Adaptive Molecular Dynamics with Excited Normal Modes (aMDeNM)** method ap
26
26
  - [CHARMM Normal Modes Analysis (Optional)](#charmm-normal-modes-analysis-optional)
27
27
  - [ENM Computation](#enm-computation)
28
28
  - [Physical Motivation and Coarse-Graining](#physical-motivation-and-coarse-graining)
29
+ - [Nucleic Acid Support (SBP Model)](#nucleic-acid-support-sbp-model)
29
30
  - [Network Construction](#network-construction)
30
31
  - [The Hessian Matrix](#the-hessian-matrix)
31
32
  - [Normal Mode Analysis and Diagonalization](#normal-mode-analysis-and-diagonalization)
32
33
  - [Rigid-Body Modes and the Null Space](#rigid-body-modes-and-the-null-space)
33
34
  - [Equipartition and the Physical Meaning of Eigenvalues](#equipartition-and-the-physical-meaning-of-eigenvalues)
35
+ - [Rotations-Translations of Blocks (RTB)](#rotations-translations-of-blocks-rtb)
34
36
  - [Uniform Normal Modes Combination](#uniform-normal-modes-combination)
35
37
  - [Problem Definition](#problem-definition)
36
38
  - [Mode Subspace Geometry](#mode-subspace-geometry)
@@ -133,6 +135,20 @@ Elastic Network Models offer a powerful and computationally inexpensive alternat
133
135
 
134
136
  This motivates a **coarse-graining** strategy: instead of representing every atom with a detailed force field, the protein is reduced to a set of representative interaction sites connected by harmonic springs. In the **Cα model** (also called ANM, the Anisotropic Network Model), each residue is represented by a single point placed at its α-carbon. In the **heavy-atom model**, all non-hydrogen atoms are retained, yielding a finer-grained representation at the cost of a larger Hessian matrix. The choice of model involves a tradeoff between computational cost and the resolution of the dynamical description.
135
137
 
138
+ ### Nucleic Acid Support (SBP Model)
139
+
140
+ Protein–nucleic acid complexes (*e.g.* transcription factors, ribonucleoproteins, ion channel–RNA interactions) are supported in both ENM models. In the **heavy-atom model**, nucleic acid heavy atoms (backbone and base) are included exactly like protein heavy atoms — no special handling needed. In the **CA model**, a single α-carbon has no nucleic acid analog, so `pyadmd` represents each nucleotide with a **three-bead SBP (Sugar-Phosphate-Base) model** instead of one point:
141
+
142
+ - **P** — phosphate (backbone)
143
+ - **C1′** — sugar
144
+ - **C2** — nitrogenous base
145
+
146
+ Each bead is assigned the mass of its representative element (phosphorus for P; carbon for C1′ and C2), following the same "uniform mass by representative atom" convention already used for protein Cα (uniform carbon mass). All beads — protein Cα and nucleic P/C1′/C2 alike — are then connected pairwise by the same distance-cutoff rule described in [Network Construction](#network-construction) below, so a protein–nucleic complex is built as one mixed-resolution network, not two separate ones.
147
+
148
+ A 5′-terminal nucleotide (or any other residue) lacking a P atom is common and not an error: that residue simply contributes its C1′/C2 beads only, with a summary warning. A residue missing C1′ or C2 (unexpected — an incomplete or malformed input structure) is warned about separately and likewise contributes whatever beads it has, rather than aborting the calculation.
149
+
150
+ The three-bead SBP representation also interacts favorably with [RTB](#rotations-translations-of-blocks-rtb): unlike a single-point Cα block, a 3-atom SBP block spans a genuine rigid-body subspace, so `--rtb` gives a real dimensionality reduction on nucleic acid residues even under the Cα model.
151
+
136
152
  ### Network Construction
137
153
 
138
154
  Given a set of $`N`$ interaction sites (Cα atoms or heavy atoms) with equilibrium positions $`\mathbf{r}_i^0`$, the elastic network is constructed by connecting every pair of sites $`i`$ and $`j`$ whose equilibrium distance $`r_{ij}^0 = |\mathbf{r}_i^0 - \mathbf{r}_j^0|`$ falls within a specified **cutoff distance** $`r_c`$:
@@ -225,6 +241,20 @@ $$
225
241
 
226
242
  where $`\mathbf{H}^+`$ is the Moore-Penrose pseudo-inverse. This relationship is the foundation for the RMSF and DCCM calculations available via `pyadmd enm` (see [ENM (Standalone Normal Mode Analysis)](#enm-standalone-normal-mode-analysis)).
227
243
 
244
+ ### Rotations-Translations of Blocks (RTB)
245
+
246
+ Direct diagonalization of the full ENM Hessian becomes the dominant computational cost for large systems, particularly the heavy-atom model. **RTB** trades resolution in the highest-frequency modes for a much smaller diagonalization problem: atoms are grouped into rigid **blocks** (fixed at one residue per block in `pyadmd`), and the mass-weighted Hessian is projected onto the 6-DOF-per-block subspace (3 translations + 3 rotations per block) before diagonalizing. The resulting eigenvectors are projected back to full Cartesian space, so every downstream output (mode vectors, trajectories, collectivity, NMA-predicted RMSF/DCCM) is produced identically whether or not RTB was used.
247
+
248
+ Enabled via the **`--rtb`** flag on both `pyadmd run` and `pyadmd enm` (including any `--recalc` ENM recomputation mid-run — see [Excitation Direction Update](#excitation-direction-update)). Two consequences of the fixed one-residue-per-block choice, stated explicitly:
249
+
250
+ - **`-m HEAVY`**: each block contains multiple heavy atoms (backbone + sidechain, protein or nucleic), so it genuinely contributes up to 6 degrees of freedom — the reduced problem has roughly $`6 \times`$ the number of residues degrees of freedom instead of $`3 \times`$ the number of heavy atoms, giving a real speedup for large systems.
251
+ - **`-m CA`, protein residues**: each block is a single Cα atom, which has no meaningful rotation about itself. Each such block therefore contributes only 3 translational degrees of freedom, so a *purely protein* CA system's reduced problem has exactly the same size as the standard, non-RTB Cα Hessian. `--rtb -m CA` on a protein-only system is mathematically equivalent to plain `-m CA` (useful as a correctness check), with no computational benefit.
252
+ - **`-m CA`, nucleic acid residues**: represented by the three-bead SBP block (P, C1′, C2 — see [Nucleic Acid Support (SBP Model)](#nucleic-acid-support-sbp-model)) rather than a single point, so — like a HEAVY block — it genuinely contributes up to 6 degrees of freedom. A protein–nucleic complex run under `-m CA --rtb` therefore *does* see a real reduction on its nucleic portion, even though its protein portion does not. Only a system with no nucleic acid residues at all gets zero benefit from `--rtb` under the CA model.
253
+
254
+ `--rtb` is not compatible with `-m CHARMM`: RTB reduces the ENM Hessian, and CHARMM normal modes are precomputed externally and never diagonalized by `pyadmd`.
255
+
256
+ References: Durand, Trinquier & Sanejouand, *Biopolymers* 1994, 34:759–771; Tama, Gadea, Marques & Sanejouand, *Proteins* 2000, 41:1–7.
257
+
228
258
  ## Uniform Normal Modes Combination
229
259
 
230
260
  The program generates uniformly distributed excitation vectors through a geometry-aware repulsion-based algorithm. The approach builds on a physics-inspired framework where points behave as charged particles confined to a spherical manifold, interacting through a dimensionally-scaled potential function. Unlike naive implementations that operate in an abstract factor space, the algorithm here accounts for the true geometry of the normal mode subspace before distributing the points, guaranteeing that the resulting excitation vectors are genuinely equidistant in the physical Cartesian space that governs the molecular dynamics.
@@ -394,7 +424,7 @@ $$
394
424
 
395
425
  The default value for $`\ell_c`$ is $`0.5 m^{1/2} Å`$ (with $`m`$ being atomic mass unit), and for $`\alpha`$ is $`60°`$.
396
426
 
397
- **Note on `--recalc` and reproducibility:** when `--recalc` is set, reaching this threshold triggers a full ENM recomputation from the current structure (`SimulationRunner._recompute_enm_modes`) followed by a *brand-new random* linear combination of the recomputed modes, rather than the deterministic displacement-based correction above. This random re-combination is independent of the `-seed`/`--seed` flag described in [Uniform Normal Modes Combination](#normal-modes-linear-combination) and is not currently reproducible run-to-run — by design, since its purpose is to re-diversify the excitation direction after the mode subspace itself has changed.
427
+ **Note on `--recalc` and reproducibility:** when `--recalc` is set, reaching this threshold triggers a full ENM recomputation from the current structure (`SimulationRunner._recompute_enm_modes`) followed by a *brand-new random* linear combination of the recomputed modes, rather than the deterministic displacement-based correction above. This random re-combination is independent of the `-seed`/`--seed` flag described in [Uniform Normal Modes Combination](#normal-modes-linear-combination) and is not currently reproducible run-to-run — by design, since its purpose is to re-diversify the excitation direction after the mode subspace itself has changed. When `--rtb` is also set, this ENM recomputation is performed via the RTB reduction (see [Rotations-Translations of Blocks (RTB)](#rotations-translations-of-blocks-rtb)) rather than direct diagonalization.
398
428
 
399
429
  [Back to top ↩](#)
400
430
  * ****
@@ -482,6 +512,8 @@ below into it.
482
512
 
483
513
  - **`--full-ener`**: Write per-term energy decomposition (BOND, ANGLE, DIHED, IMPRP, CMAP, UBREY, NBFIX, NONBONDED, etc.) to `rep{N}_ener_decomp.log` every cycle
484
514
 
515
+ - **`--rtb`**: Use RTB (Rotations-Translations of Blocks) reduction for ENM diagonalization instead of direct full-Hessian diagonalization — see [Rotations-Translations of Blocks (RTB)](#rotations-translations-of-blocks-rtb). Blocks are fixed at one residue each. Only valid with `-m CA` or `-m HEAVY` (not `CHARMM`). Also applies to any `--recalc` ENM recomputation mid-run.
516
+
485
517
  ## Append
486
518
  ### Parameters
487
519
  - **`-t`/`--time`**: Simulation time to append, in ps (**required**)
@@ -524,21 +556,23 @@ Each analysis step can be independently disabled. When skipped, that metric will
524
556
 
525
557
  ## ENM
526
558
  ### Parameters
527
- - **`-i`/`--input`**: Input PDB file (**required**, unless **`-w`/`--write-modes`** is used)
559
+ - **`-i`/`--input`**: Input PDB file (**required**, unless **`-w`/`--write-modes`** is used).
528
560
 
529
- - **`-o`/`--output`**: Output folder name (**optional**. Default: **`output`**)
561
+ - **`-o`/`--output`**: Output folder name (**optional**. Default: **`output`**).
530
562
 
531
563
  - **`-m`/`--model`**: Model type, **`CA`** (Cα-only) or **`HEAVY`** (heavy atoms) (**optional**. Default: **`CA`**). Unlike `run`'s `-m`/`--model`, **`CHARMM`** is not a valid choice here — `enm` only computes ENM normal modes, not CHARMM-derived ones.
532
564
 
533
- - **`-sel`/`--selection`**: Atom selection applied to the input PDB before building the ENM (**optional**. Default: **`"protein"`**). Must be written between quotes if it contains spaces, per [MDAnalysis selection language](https://userguide.mdanalysis.org/1.1.1/selections.html).
565
+ - **`-sel`/`--selection`**: Atom selection applied to the input PDB before building the ENM (**optional**. Default: **`"protein or nucleic"`**). Must be written between quotes if it contains spaces, per [MDAnalysis selection language](https://userguide.mdanalysis.org/1.1.1/selections.html).
566
+
567
+ - **`-c`/`--cutoff`**: Interaction cutoff distance, in Å (**optional**. Default: **`15.0`** for CA, **`12.0`** for HEAVY).
534
568
 
535
- - **`-c`/`--cutoff`**: Interaction cutoff distance, in Å (**optional**. Default: **`15.0`** for CA, **`12.0`** for HEAVY)
569
+ - **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**).
536
570
 
537
- - **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**)
571
+ - **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**).
538
572
 
539
- - **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**)
573
+ - **`--output-modes`**: Number of modes (file-labeled 1 through N, where label 1 is the first non-rigid mode) to write vectors/trajectories for (**optional**. Default: **`10`**).
540
574
 
541
- - **`--output-modes`**: Number of modes (file-labeled 1 through N, where label 1 is the first non-rigid mode) to write vectors/trajectories for (**optional**. Default: **`10`**)
575
+ - **`--rtb`**: Use RTB reduction for diagonalization instead of direct full-Hessian diagonalization (**optional**. Default: disabled).
542
576
 
543
577
  ### Skip Flags
544
578
  Collectivity, contributions, RMSF, DCCM, and mode vector/trajectory writing can each be independently disabled:
@@ -957,4 +991,4 @@ If you experience a bug or have a suggestion, please contact:
957
991
 
958
992
  *[laraptr [at] unicamp.br](mailto:laraptr@unicamp.br)*
959
993
 
960
- [Back to top ↩](#)
994
+ [Back to top ↩](#)
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pyadmd"
7
- version = "3.3.0"
7
+ version = "3.4.0"
8
8
  description = "Adaptive Molecular Dynamics with Excited Normal Modes (aMDeNM) on OpenMM."
9
9
  readme = "README.md"
10
10
  license = "GPL-3.0-or-later"
@@ -9,4 +9,4 @@ environmental resistance. Importantly, aMDeNM requires only an initial structure
9
9
  target states, distinguishing it from many biased sampling techniques that rely on predefined target conformations.
10
10
  """
11
11
 
12
- __version__ = "3.3.0"
12
+ __version__ = "3.4.0"
@@ -8,6 +8,7 @@ import traceback
8
8
  from typing import Any
9
9
 
10
10
  import numpy as np
11
+ from openmm import unit
11
12
 
12
13
  from pyadmd.console import ConsoleConfig
13
14
  from pyadmd.io.dcd import find_last_completed_cycle
@@ -22,6 +23,7 @@ from pyadmd.io.state import (
22
23
  )
23
24
  from pyadmd.enm.calculator import ENMCalculator
24
25
  from pyadmd.enm.analysis import ENMAnalyzer
26
+ from pyadmd.enm.rtb import build_blocks, project_and_diagonalize
25
27
  from pyadmd.modes.exciter import ModeExciter
26
28
  from pyadmd.simulation.runner import SimulationRunner
27
29
  from pyadmd.fel.calculator import FreeEnergyCalculator, export_cluster
@@ -147,6 +149,7 @@ def cmd_run(args: Any, console: ConsoleConfig, cwd: str, input_dir: str,
147
149
  energy = args.energy
148
150
  sim_time = args.time
149
151
  replicas = args.replicas
152
+ use_rtb = getattr(args, 'rtb', False)
150
153
 
151
154
  # Derive base_name for ENM output directory naming.
152
155
  # NAMD: coorfile prefix; OPENMM: rstfile prefix.
@@ -157,9 +160,9 @@ def cmd_run(args: Any, console: ConsoleConfig, cwd: str, input_dir: str,
157
160
 
158
161
  # Store in args for SimulationRunner access
159
162
  if args.no_correc:
160
- n_steps = 1000 # MD steps per excitation cycle (2 fs/step → 2.0 ps/cycle)
163
+ n_steps = 1000 # MD steps per excitation cycle (2 fs/step → 2.0 ps/cycle)
161
164
  else:
162
- n_steps = 100 # MD steps per excitation cycle (2 fs/step → 0.2 ps/cycle)
165
+ n_steps = 50 # MD steps per excitation cycle (2 fs/step → 0.1 ps/cycle)
163
166
  args.n_steps = n_steps
164
167
  end_loop = int(sim_time / (n_steps * 0.002))
165
168
 
@@ -169,13 +172,13 @@ def cmd_run(args: Any, console: ConsoleConfig, cwd: str, input_dir: str,
169
172
  f"{console.STD}{console.HGH} and writing normal mode vectors "
170
173
  f"{console.EXT}{modes}{console.STD}.")
171
174
  enm_calculator.compute_enm(init_pos_ang, base_name, nm_type,
172
- nm_parsed, input_dir, psffile)
175
+ nm_parsed, input_dir, psffile, rtb=use_rtb)
173
176
  elif nm_type == "heavy":
174
177
  print(f"\n{console.PGM_NAM}{console.HGH}Computing {console.EXT}Heavy atoms ENM"
175
178
  f"{console.STD}{console.HGH} and writing normal mode vectors "
176
179
  f"{console.EXT}{modes}{console.STD}.")
177
180
  enm_calculator.compute_enm(init_pos_ang, base_name, nm_type,
178
- nm_parsed, input_dir, psffile)
181
+ nm_parsed, input_dir, psffile, rtb=use_rtb)
179
182
  elif nm_type == "charmm":
180
183
  print(f"\n{console.PGM_NAM}Writing {console.EXT}CHARMM{console.STD} "
181
184
  f"normal mode vectors {console.EXT}{modes}{console.STD}.")
@@ -594,14 +597,20 @@ def cmd_enm(args: Any, console: ConsoleConfig, enm_calculator: ENMCalculator) ->
594
597
 
595
598
  - ``-w/--write-modes`` set: re-derive vector/trajectory files from a
596
599
  previously completed run's saved arrays, without recomputing the
597
- ENM (``ENMAnalyzer.write_modes_from_files``).
600
+ ENM (``ENMAnalyzer.write_modes_from_files``). ``--rtb`` has no
601
+ effect on this path (no diagonalization is performed here) and a
602
+ warning is printed if both are given.
598
603
  - Otherwise: run a full ENM computation from ``-i/--input``, save
599
604
  the filtered mode/frequency arrays plus the reduced structure
600
605
  PDB (both written by ``ENMCalculator.create_system``/
601
606
  ``compute_normal_modes``), then delegate to the same
602
607
  ``write_modes_from_files`` path used by ``-w`` for the actual
603
608
  vector/trajectory writing -- so the two paths always agree on
604
- file format, and the logic is written once.
609
+ file format, and the logic is written once. When ``--rtb`` is
610
+ set, diagonalization is routed through the RTB block-projection
611
+ reduction (``pyadmd.enm.rtb``) instead of direct diagonalization
612
+ of the full Hessian, mirroring ``ENMCalculator.compute_enm``'s
613
+ own ``rtb`` branch.
605
614
 
606
615
  Args:
607
616
  args: Parsed CLI arguments for the ``enm`` subcommand.
@@ -613,6 +622,9 @@ def cmd_enm(args: Any, console: ConsoleConfig, enm_calculator: ENMCalculator) ->
613
622
 
614
623
  # -w / --write-modes: post-hoc path, no recomputation needed
615
624
  if args.write_modes is not None:
625
+ if getattr(args, 'rtb', False):
626
+ print(f"{console.PGM_WRN}--rtb has no effect with -w/--write-modes "
627
+ "(no diagonalization is performed on this path); ignoring.")
616
628
  print(f"{console.PGM_NAM}{console.TLE}Write ENM modes from a previous run{console.STD}\n")
617
629
  try:
618
630
  mode_numbers = analyzer.parse_mode_string(args.write_modes)
@@ -640,6 +652,11 @@ def cmd_enm(args: Any, console: ConsoleConfig, enm_calculator: ENMCalculator) ->
640
652
  output_prefix = os.path.join(output_folder, base_name)
641
653
  model_type = args.model.lower()
642
654
  prefix = "ca" if model_type == "ca" else "heavy"
655
+ use_rtb = getattr(args, 'rtb', False)
656
+
657
+ if use_rtb:
658
+ print(f"{console.PGM_NAM}RTB (Rotations-Translations of Blocks) "
659
+ f"{console.EXT}enabled{console.STD} (1 residue per block).")
643
660
 
644
661
  # System build + Hessian + diagonalization
645
662
  try:
@@ -653,9 +670,29 @@ def cmd_enm(args: Any, console: ConsoleConfig, enm_calculator: ENMCalculator) ->
653
670
  )
654
671
  hessian = enm_calculator.hessian_enm(system, positions)
655
672
  mw_hessian = enm_calculator.mass_weight_hessian(hessian, system)
656
- frequencies, modes, eigenvalues = enm_calculator.compute_normal_modes(
657
- mw_hessian, n_modes=args.max_modes, use_gpu=not args.no_gpu,
658
- )
673
+
674
+ if use_rtb:
675
+ positions_nm = np.array(
676
+ [[p.x, p.y, p.z] for p in positions.value_in_unit(unit.nanometer)],
677
+ dtype=np.float64
678
+ )
679
+ n_particles = system.getNumParticles()
680
+ rtb_masses = np.array(
681
+ [system.getParticleMass(i).value_in_unit(unit.dalton)
682
+ for i in range(n_particles)]
683
+ )
684
+ rtb_masses[rtb_masses == 0] = 1.0
685
+
686
+ blocks = build_blocks(topology)
687
+ frequencies, modes, eigenvalues = project_and_diagonalize(
688
+ mw_hessian, positions_nm, rtb_masses, blocks,
689
+ diagonalize_fn=enm_calculator.compute_normal_modes,
690
+ n_modes=args.max_modes, use_gpu=not args.no_gpu, console=console,
691
+ )
692
+ else:
693
+ frequencies, modes, eigenvalues = enm_calculator.compute_normal_modes(
694
+ mw_hessian, n_modes=args.max_modes, use_gpu=not args.no_gpu,
695
+ )
659
696
  except Exception as exc:
660
697
  print(f"{console.PGM_ERR}ENM computation failed: {console.ERR}{exc}{console.STD}")
661
698
  traceback.print_exc()
@@ -73,8 +73,8 @@ def parse_arguments() -> argparse.Namespace:
73
73
  help="Excitation energy (default: 2 kcal/mol)")
74
74
  run_optional.add_argument('-t', '--time', action="store", type=int, default=250, metavar='PS',
75
75
  help="Total simulation time (default: 250 ps)")
76
- run_optional.add_argument('-sel', '--selection', action="store", type=str, default="protein",
77
- help="Atom selection to apply the energy injection (default: protein)")
76
+ run_optional.add_argument('-sel', '--selection', action="store", type=str, default="protein or nucleic",
77
+ help="Atom selection to apply the energy injection (default: protein or nucleic)")
78
78
  run_optional.add_argument('-rep', '--replicas', action="store", type=int, default=10, metavar='N',
79
79
  help="Number of aMDeNM replicas to run (default: 10)")
80
80
  run_optional.add_argument('-seed', '--seed', action="store", type=int, default=42,
@@ -91,6 +91,9 @@ def parse_arguments() -> argparse.Namespace:
91
91
  run_flags.add_argument('--full-ener', action='store_true',
92
92
  help='Write per-term energy decomposition (BOND, ANGLE, DIHED, etc.) '
93
93
  'to rep{N}_ener_decomp.log each cycle')
94
+ run_flags.add_argument('--rtb', action='store_true',
95
+ help='Use RTB reduction for ENM diagonalization. '
96
+ 'Also applies to any --recalc ENM recomputation mid-run.')
94
97
 
95
98
 
96
99
  #####################
@@ -227,8 +230,8 @@ def parse_arguments() -> argparse.Namespace:
227
230
  choices=["CA", "HEAVY"],
228
231
  help='Model type: CA (Cα-only) or HEAVY (heavy atoms) (default: CA)')
229
232
  enm_optional.add_argument(
230
- '-sel', '--selection', action="store", type=str, default="protein",
231
- help='Atom selection to build the ENM (default: "protein")')
233
+ '-sel', '--selection', action="store", type=str, default="protein or nucleic",
234
+ help='Atom selection to build the ENM (default: "protein or nucleic")')
232
235
  enm_optional.add_argument(
233
236
  '-c', '--cutoff', type=float, default=None, metavar='Å',
234
237
  help='Interaction cutoff distance in Å '
@@ -250,6 +253,10 @@ def parse_arguments() -> argparse.Namespace:
250
253
  'Accepts comma-separated integers and inclusive ranges '
251
254
  '(start:end), e.g. "26,41" "7:10" "42,44:50". Requires '
252
255
  '-o/--output pointing to an existing output directory. ')
256
+ enm_optional.add_argument(
257
+ '--rtb', action='store_true',
258
+ help='Use RTB reduction for ENM diagonalization. '
259
+ 'Also applies to any --recalc ENM recomputation mid-run.')
253
260
 
254
261
  # Optional skip flags for ENM
255
262
  enm_flags = opt_enm.add_argument_group('Skip flags (disable individual outputs)')
@@ -301,6 +308,11 @@ def parse_arguments() -> argparse.Namespace:
301
308
  if args.model == 'CHARMM' and args.recalc:
302
309
  opt_run.error("ENM recalculation is not compatible with CHARMM normal modes")
303
310
 
311
+ if hasattr(args, 'option') and args.option == 'run':
312
+ if args.model == 'CHARMM' and args.rtb:
313
+ opt_run.error("RTB (--rtb) is not compatible with -m CHARMM; RTB operates on the "
314
+ "ENM Hessian, not on precomputed CHARMM modes.")
315
+
304
316
  # Validate input-engine-specific file requirements
305
317
  if hasattr(args, 'option') and args.option == 'run':
306
318
  if args.source == 'NAMD':
@@ -53,7 +53,7 @@ class ConsoleConfig:
53
53
  ░░░░░ ░░░░░░
54
54
  '''
55
55
 
56
- VERSION = '3.3.0'
56
+ VERSION = '3.4.0'
57
57
  CITATION = ''' Please cite:
58
58
 
59
59
  \tAdaptive Normal Mode Sampling (aMDeNM) Enhances Exploration of Protein Conformational Space