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.
- {pyadmd-3.3.0/src/pyadmd.egg-info → pyadmd-3.4.0}/PKG-INFO +43 -9
- {pyadmd-3.3.0 → pyadmd-3.4.0}/README.md +43 -9
- {pyadmd-3.3.0 → pyadmd-3.4.0}/pyproject.toml +1 -1
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/__init__.py +1 -1
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/commands.py +46 -9
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/parser.py +16 -4
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/console.py +1 -1
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/enm/calculator.py +176 -50
- pyadmd-3.4.0/src/pyadmd/enm/rtb.py +264 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/modes/exciter.py +24 -5
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/runner.py +18 -1
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/system_builder.py +52 -3
- {pyadmd-3.3.0 → pyadmd-3.4.0/src/pyadmd.egg-info}/PKG-INFO +43 -9
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/SOURCES.txt +1 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/LICENSE +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/setup.cfg +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/__main__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/analysis/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/analysis/analyzer.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/analysis/completion.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/charmm/charmm_toppar.zip +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/charmm/wrt-nm.mdu +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/cli/main.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/constants.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/enm/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/enm/analysis.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/fel/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/fel/calculator.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/fel/completion.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/geometry.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/dcd.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/namd.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/openmm_restart.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/params.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/io/state.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/modes/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/modes/projection.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/__init__.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/simulation/engine.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd/utils.py +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/dependency_links.txt +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/entry_points.txt +0 -0
- {pyadmd-3.3.0 → pyadmd-3.4.0}/src/pyadmd.egg-info/requires.txt +0 -0
- {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
|
+
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
|
-
- **`-
|
|
597
|
+
- **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**).
|
|
564
598
|
|
|
565
|
-
-
|
|
599
|
+
- **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**).
|
|
566
600
|
|
|
567
|
-
- **`--
|
|
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
|
-
- **`--
|
|
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
|
-
- **`-
|
|
569
|
+
- **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**).
|
|
536
570
|
|
|
537
|
-
-
|
|
571
|
+
- **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**).
|
|
538
572
|
|
|
539
|
-
- **`--
|
|
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
|
-
- **`--
|
|
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 ↩](#)
|
|
@@ -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
|
|
163
|
+
n_steps = 1000 # MD steps per excitation cycle (2 fs/step → 2.0 ps/cycle)
|
|
161
164
|
else:
|
|
162
|
-
n_steps =
|
|
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
|
-
|
|
657
|
-
|
|
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':
|