pyadmd 3.2.3__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.2.3/src/pyadmd.egg-info → pyadmd-3.4.0}/PKG-INFO +92 -49
- {pyadmd-3.2.3 → pyadmd-3.4.0}/README.md +92 -49
- {pyadmd-3.2.3 → pyadmd-3.4.0}/pyproject.toml +1 -1
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/__init__.py +1 -1
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/analysis/analyzer.py +270 -1
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/commands.py +47 -9
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/parser.py +18 -4
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/console.py +1 -1
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/enm/calculator.py +176 -50
- pyadmd-3.4.0/src/pyadmd/enm/rtb.py +264 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/fel/calculator.py +91 -134
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/modes/exciter.py +24 -5
- pyadmd-3.4.0/src/pyadmd/modes/projection.py +251 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/engine.py +62 -20
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/runner.py +26 -3
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/system_builder.py +52 -3
- {pyadmd-3.2.3 → pyadmd-3.4.0/src/pyadmd.egg-info}/PKG-INFO +92 -49
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/SOURCES.txt +2 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/LICENSE +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/setup.cfg +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/__main__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/analysis/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/analysis/completion.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/charmm/charmm_toppar.zip +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/charmm/wrt-nm.mdu +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/main.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/constants.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/enm/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/enm/analysis.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/fel/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/fel/completion.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/geometry.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/dcd.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/namd.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/openmm_restart.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/params.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/state.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/modes/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/__init__.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/utils.py +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/dependency_links.txt +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/entry_points.txt +0 -0
- {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/requires.txt +0 -0
- {pyadmd-3.2.3 → 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)
|
|
@@ -104,13 +106,13 @@ The **Adaptive Molecular Dynamics with Excited Normal Modes (aMDeNM)** method ap
|
|
|
104
106
|
- [Extending a Previous Free Energy Calculation](#extending-a-previous-free-energy-calculation)
|
|
105
107
|
- [Output Structure](#output-structure-1)
|
|
106
108
|
- [Directory Organization](#directory-organization-1)
|
|
107
|
-
|
|
109
|
+
- [Output Files Description](#output-files-description-1)
|
|
108
110
|
- [Analysis](#analysis-1)
|
|
109
111
|
- [Basic Structural Properties Calculated](#basic-structural-properties-calculated)
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
112
|
+
- [Analysis Modes](#analysis-modes)
|
|
113
|
+
- [Standard Analysis](#standard-analysis)
|
|
114
|
+
- [Rough Analysis](#rough-analysis)
|
|
115
|
+
- [Selective Analysis (Skip Flags)](#selective-analysis-skip-flags)
|
|
114
116
|
- [Trajectory Source](#trajectory-source)
|
|
115
117
|
- [Handling Incomplete Units](#handling-incomplete-units)
|
|
116
118
|
- [Configuration Parameters](#configuration-parameters)
|
|
@@ -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
|
* ****
|
|
@@ -479,7 +509,7 @@ Create an atom selection to apply the energy injection using *[MDAnalysis select
|
|
|
479
509
|
|
|
480
510
|
- **`-rep`/`--replicas`**: Number of replicas to run (**optional**. Default: **`10`**)
|
|
481
511
|
|
|
482
|
-
- **`-seed`/`--seed`**: Random seed for the uniform mode-combination generation (the repulsion-algorithm initialization described in [Uniform Normal Modes Combination](#uniform-normal-modes-combination)) (**optional**. Default: **`42`**). Fixing this makes `run` reproducible: identical CLI arguments always produce identical excitation vectors and `factors.csv`. Pass a different value to obtain an independent replicate ensemble. Does **not** affect the `--recalc` mid-simulation re-excitation, which remains stochastic by design — see [Excitation Direction Update](#excitation-direction-update).
|
|
512
|
+
- **`-seed`/`--seed`**: Random seed for the uniform mode-combination generation (the repulsion-algorithm initialization described in [Uniform Normal Modes Combination](#uniform-normal-modes-combination)) (**optional**. Default: **`42`**). Fixing this value makes `run` more reproducible: identical CLI arguments always produce identical excitation vectors and `factors.csv`. Pass a different value to obtain an independent replicate ensemble. Does **not** affect the `--recalc` mid-simulation re-excitation, which remains stochastic by design — see [Excitation Direction Update](#excitation-direction-update). **Note:** fixing the random seed will create the same start conditions to `run`, but the simulation will diverge after a given point due to stochasticity and floating point precision.
|
|
483
513
|
|
|
484
514
|
### Files
|
|
485
515
|
`pyadmd run` automatically creates the `inputs/` directory in the current
|
|
@@ -508,7 +538,9 @@ below into it.
|
|
|
508
538
|
|
|
509
539
|
- **`-r`/`--recalc`**: Recompute ENM modes instead of correcting the excitation vector direction. **Note:** the new mode combination generated after each recomputation is drawn from a fresh random unit vector and is not controlled by `-seed`/`--seed` — see [Excitation Direction Update](#excitation-direction-update).
|
|
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
|
|
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.
|
|
512
544
|
|
|
513
545
|
## Append
|
|
514
546
|
### Parameters
|
|
@@ -546,26 +578,29 @@ Each analysis step can be independently disabled. When skipped, that metric will
|
|
|
546
578
|
- **`--no-dssp`**: Skip secondary structure analysis via DSSP
|
|
547
579
|
- **`--no-dccm`**: Skip DCCM (dynamic cross-correlation matrix) calculation
|
|
548
580
|
- **`--no-lmi`**: Skip LMI (Linear Mutual Information) calculation
|
|
581
|
+
- **`--no-modeproj`**: Skip mode-projection analysis
|
|
549
582
|
|
|
550
583
|
**Note:** Before analysis, the program checks if `pyadmd` or `fel` calls are properly completed. If any unit (pyAdMD replica or free energy centroid) hasn't finished running, `analyze` prints a warning listing the incomplete units and their cycles completed/target, but proceeds anyway — see [Handling Incomplete Units](#handling-incomplete-units) below.
|
|
551
584
|
|
|
552
585
|
## ENM
|
|
553
586
|
### Parameters
|
|
554
|
-
- **`-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).
|
|
555
588
|
|
|
556
|
-
- **`-o`/`--output`**: Output folder name (**optional**. Default: **`output`**)
|
|
589
|
+
- **`-o`/`--output`**: Output folder name (**optional**. Default: **`output`**).
|
|
557
590
|
|
|
558
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.
|
|
559
592
|
|
|
560
|
-
- **`-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).
|
|
561
594
|
|
|
562
|
-
- **`-c`/`--cutoff`**: Interaction cutoff distance, in Å (**optional**. Default: **`15.0`** for CA, **`12.0`** for HEAVY)
|
|
595
|
+
- **`-c`/`--cutoff`**: Interaction cutoff distance, in Å (**optional**. Default: **`15.0`** for CA, **`12.0`** for HEAVY).
|
|
563
596
|
|
|
564
|
-
- **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**)
|
|
597
|
+
- **`-k`/`--spring-constant`**: ENM harmonic spring constant, in kcal/mol/Ų (**optional**. Default: **`1.0`**).
|
|
565
598
|
|
|
566
|
-
- **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**)
|
|
599
|
+
- **`--max-modes`**: Number of non-rigid-body vibrational modes to compute (**optional**. Default: **`50`**).
|
|
567
600
|
|
|
568
|
-
- **`--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`**)
|
|
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`**).
|
|
602
|
+
|
|
603
|
+
- **`--rtb`**: Use RTB reduction for diagonalization instead of direct full-Hessian diagonalization (**optional**. Default: disabled).
|
|
569
604
|
|
|
570
605
|
### Skip Flags
|
|
571
606
|
Collectivity, contributions, RMSF, DCCM, and mode vector/trajectory writing can each be independently disabled:
|
|
@@ -660,7 +695,7 @@ fel/
|
|
|
660
695
|
├── clustering_rmsd_cache.npz # cached pairwise-RMSD matrix (reused across calls)
|
|
661
696
|
├── clustering_rmsd_cache.json # cache validity metadata (selection, frame count, stride)
|
|
662
697
|
├── clustering_summary.csv # per-cluster frame index, size, and production status
|
|
663
|
-
├──
|
|
698
|
+
├── mode_projections.csv # combined per-frame mode projections (centroid_frame, time, mode_N...)
|
|
664
699
|
├── fel_mode[N].csv # 1D FEL data (coordinate, ΔG)
|
|
665
700
|
├── fel_mode[N]_plot.png # 1D FEL plot
|
|
666
701
|
├── fel_2d_mode[N]_mode[M].png # 2D FEL plot for a mode pair
|
|
@@ -673,16 +708,19 @@ fel/
|
|
|
673
708
|
└── checkpoint.chk # periodic (every 10 cycles) checkpoint
|
|
674
709
|
```
|
|
675
710
|
|
|
676
|
-
|
|
711
|
+
### Output Files Description
|
|
677
712
|
1. **Cache Files**
|
|
678
|
-
- **`run_metadata.json`**: the clustering selection, temperature, cutoff, de-excitation length, `max-centroids`, and production length used.
|
|
679
|
-
- **`clustering_rmsd_cache.npz`/`.json`**: the pairwise-RMSD matrix over subsampled frames.
|
|
680
|
-
- **`clustering_summary.csv`**: summary containing cluster ID, frame index, cluster size, status this run (`fresh`/`extended`/`skipped`/`failed`, annotated with `substitute frame {N}` and/or `reinforced` when a centroid needed those fallbacks), `source_frame_used` (the frame whose coordinates actually produced a successful run — equal to `centroid_frame` unless a substitute member was used), `md_attempts` (total attempts across the standard and reinforced passes), and cycles/ps completed. A `status` of `failed` means every attempt (original frame + substitutes, standard + reinforced settings) failed; that centroid is excluded from the FEL rather than blocking the run.
|
|
713
|
+
- **`run_metadata.json`**: the clustering selection, temperature, cutoff, de-excitation length, `max-centroids`, and production length used.
|
|
714
|
+
- **`clustering_rmsd_cache.npz`/`.json`**: the pairwise-RMSD matrix over subsampled frames.
|
|
715
|
+
- **`clustering_summary.csv`**: summary containing cluster ID, frame index, cluster size, status this run (`fresh`/`extended`/`skipped`/`failed`, annotated with `substitute frame {N}` and/or `reinforced` when a centroid needed those fallbacks), `source_frame_used` (the frame whose coordinates actually produced a successful run — equal to `centroid_frame` unless a substitute member was used), `md_attempts` (total attempts across the standard and reinforced passes), and cycles/ps completed. A `status` of `failed` means every attempt (original frame + substitutes, standard + reinforced settings) failed; that centroid is excluded from the FEL rather than blocking the run.
|
|
716
|
+
- **`mode_projections.csv`**: every production frame's signed mass-weighted MRMS displacement (Å) along each mode in `--modes`, one row per `(centroid_frame, time)` pair, columns `centroid_frame, time, mode_{N}, ...`. Reused directly by `pyadmd analyze -src fel`'s mode-projection analysis (see [Analysis](#analysis-1)) whenever it already covers every mode that call needs, skipping recomputation entirely.
|
|
717
|
+
|
|
681
718
|
2. **Plot Files**
|
|
682
|
-
- **`fel_mode[N].csv`/`fel_mode[N]_plot.png`**: 1D free energy landscape per mode, in Å and kcal/mol.
|
|
683
|
-
- **`fel_2d_mode[N]_mode[M].png`**: 2D free energy landscape for a mode pair.
|
|
719
|
+
- **`fel_mode[N].csv`/`fel_mode[N]_plot.png`**: 1D free energy landscape per mode, in Å and kcal/mol.
|
|
720
|
+
- **`fel_2d_mode[N]_mode[M].png`**: 2D free energy landscape for a mode pair.
|
|
721
|
+
|
|
684
722
|
3. **HTML Summary**
|
|
685
|
-
- **`fel_summary.html`**: interactive summary with protocol parameters, per-mode FEL statistics, per-centroid production status, and embedded plots.
|
|
723
|
+
- **`fel_summary.html`**: interactive summary with protocol parameters, per-mode FEL statistics, per-centroid production status, and embedded plots.
|
|
686
724
|
|
|
687
725
|
[Back to top ↩](#)
|
|
688
726
|
* ****
|
|
@@ -704,22 +742,24 @@ The PyAdMD **`analysis`** module provides comprehensive analysis capabilities fo
|
|
|
704
742
|
|
|
705
743
|
6. **Secondary Structure Content:** Calculates secondary structure elements using DSSP. Tracks helix, sheet, coil, turn, and other structural elements over time and reports the number of residues in each secondary structure type.
|
|
706
744
|
|
|
707
|
-
7. **Dynamic Cross-Correlation Matrix (DCCM):** Measures pairwise linear correlation of Cα residue motions after Kabsch superposition to remove rigid-body rotation/translation. Values range from
|
|
745
|
+
7. **Dynamic Cross-Correlation Matrix (DCCM):** Measures pairwise linear correlation of Cα residue motions after Kabsch superposition to remove rigid-body rotation/translation. Values range from $`+1`$ (fully correlated motion) through $`0`$ (uncorrelated) to $`−1`$ (fully anti-correlated motion), useful for identifying coupled domains, allosteric communication paths, and correlated/anti-correlated collective motions.
|
|
746
|
+
|
|
747
|
+
8. **Linear Mutual Information (LMI):** An alternative, signless measure of residue-residue coupling strength (range $`[0, 1]`$) computed via the Gaussian approximation of generalized correlation. Unlike DCCM, LMI reports strongly anti-correlated motion with the same high value as strongly correlated motion, since it measures total coupling rather than its direction.
|
|
708
748
|
|
|
709
|
-
|
|
749
|
+
9. **Mode Projections:** Every analyzed frame's signed mass-weighted MRMS displacement (Å) along each individually excited normal mode. Pairs of excited modes are additionally visualized as 2D scatter plots colored by KDE density, useful for seeing which combinations of mode directions the trajectory actually populates.
|
|
710
750
|
|
|
711
|
-
|
|
712
|
-
|
|
751
|
+
### Analysis Modes
|
|
752
|
+
#### Standard Analysis
|
|
713
753
|
- Analyzes every frame of the trajectory
|
|
714
754
|
- Provides the highest resolution data
|
|
715
755
|
- May be computationally intensive
|
|
716
756
|
|
|
717
|
-
|
|
718
|
-
- Analyzes frames at
|
|
757
|
+
#### Rough Analysis
|
|
758
|
+
- Analyzes frames at $`5ps`$ intervals
|
|
719
759
|
- Significantly reduces computation time
|
|
720
760
|
- Suitable for quick overviews or large systems
|
|
721
761
|
|
|
722
|
-
|
|
762
|
+
#### Selective Analysis (Skip Flags)
|
|
723
763
|
Individual analyses can be disabled at the command line. This is useful when:
|
|
724
764
|
- DSSP is not installed (avoid exception error)
|
|
725
765
|
- Only a subset of metrics is needed (*e.g.* RMSD + RMSF only)
|
|
@@ -756,6 +796,8 @@ When `-src fel` is used, the shared production time axis (applied uniformly acro
|
|
|
756
796
|
analysis/{fel/}
|
|
757
797
|
├── analysis_results.csv # Combined analysis data from all units
|
|
758
798
|
├── rmsf.csv # Combined RMSF data (omitted with --no-rmsf)
|
|
799
|
+
├── mode_projections.csv # Combined mode-projection data from all units (omitted with --no-modeproj)
|
|
800
|
+
├── mode_proj_scatter_mode[N]_mode[M].png # KDE-colored scatter plot for a pair of excited modes (omitted with --no-modeproj)
|
|
759
801
|
├── analysis_summary.html # HTML summary report
|
|
760
802
|
├── rmsd_plot.png # RMSD plot (omitted with --no-rmsd)
|
|
761
803
|
├── radius_gyration_plot.png # Radius of gyration plot (omitted with --no-rg)
|
|
@@ -785,25 +827,26 @@ analysis/{fel/}
|
|
|
785
827
|
|
|
786
828
|
## Output Files Description
|
|
787
829
|
1. **CSV Files**
|
|
788
|
-
- **`analysis_results.csv`:** Time-series data for RMSD, RoG, SASA, hydrophobic exposure, and secondary structure content
|
|
789
|
-
- **`rmsf.csv`:** Per-residue RMSF values for all analyzed units (all replicas, or all centroids with `-src fel`)
|
|
830
|
+
- **`analysis_results.csv`:** Time-series data for RMSD, RoG, SASA, hydrophobic exposure, and secondary structure content
|
|
831
|
+
- **`rmsf.csv`:** Per-residue RMSF values for all analyzed units (all replicas, or all centroids with `-src fel`)
|
|
832
|
+
- **`mode_projections.csv`:** Combined per-frame mode-projection data across all analyzed units, columns `{unit_col}, time, mode_{N}, ...` where `{unit_col}` is `replica` (`-src pyadmd`) or `centroid_frame` (`-src fel`) and `mode_{N}` are the individual modes excited in `run` (`nm_parsed`). With `-src fel`, reused directly from `fel/mode_projections.csv` when that file already covers every needed mode, instead of being recomputed — see [Mode Projections](#mode-projections). Omitted with `--no-modeproj`.
|
|
790
833
|
|
|
791
834
|
2. **Plot Files**
|
|
792
|
-
- Individual property plots for each unit (replica, or centroid with `-src fel`)
|
|
793
|
-
- Combined plots showing all units
|
|
794
|
-
- Average plots across all units
|
|
835
|
+
- Individual property plots for each unit (replica, or centroid with `-src fel`)
|
|
836
|
+
- Combined plots showing all units
|
|
837
|
+
- Average plots across all units
|
|
838
|
+
- **`dccm_plot.png`** / **`dccm_average.png`**: DCCM heatmap, diverging colormap (red = fully correlated, white = uncorrelated, blue = fully anti-correlated).
|
|
839
|
+
- **`lmi_plot.png`** / **`lmi_average.png`**: LMI heatmap, sequential colormap (LMI has no sign).
|
|
840
|
+
- **`mode_proj_scatter_mode[N]_mode[M].png`:** One 2D scatter plot per pairwise combination of excited modes, pooling frames from every analyzed unit, colored by KDE density. Omitted with `--no-modeproj`.
|
|
795
841
|
|
|
796
842
|
3. **Correlation Matrix Files**
|
|
797
|
-
- **`dccm_matrix.npy`** (per-unit) / **`dccm_average.npy`** (cross-unit): raw (n_Cα × n_Cα) DCCM matrix, values in [-1, 1]
|
|
798
|
-
- **`
|
|
799
|
-
- **`lmi_matrix.npy`** / **`lmi_average.npy`**: raw (n_Cα × n_Cα) LMI matrix, values in [0, 1]. Omitted with `--no-lmi`.
|
|
800
|
-
- **`lmi_plot.png`** / **`lmi_average.png`**: LMI heatmap, sequential colormap (LMI has no sign).
|
|
843
|
+
- **`dccm_matrix.npy`** (per-unit) / **`dccm_average.npy`** (cross-unit): raw (n_Cα × n_Cα) DCCM matrix, values in $`[-1, 1]`$. Omitted with `--no-dccm`.
|
|
844
|
+
- **`lmi_matrix.npy`** / **`lmi_average.npy`**: raw (n_Cα × n_Cα) LMI matrix, values in $`[0, 1]`$. Omitted with `--no-lmi`.
|
|
801
845
|
|
|
802
846
|
4. **HTML Summary**
|
|
803
|
-
-
|
|
804
|
-
- Statistics for each unit and averages across all units
|
|
805
|
-
- An "Incomplete Units" section when any unit hadn't reached its target cycle count at analysis time (see [Handling Incomplete Units](#handling-incomplete-units))
|
|
806
|
-
- Easy navigation and visualization of results
|
|
847
|
+
- Summary report with tables and embedded plots
|
|
848
|
+
- Statistics for each unit and averages across all units
|
|
849
|
+
- An "Incomplete Units" section when any unit hadn't reached its target cycle count at analysis time (see [Handling Incomplete Units](#handling-incomplete-units))
|
|
807
850
|
|
|
808
851
|
|
|
809
852
|
Furthermore, some basic analyses are written inside each replica folder at the end of the simulation, they can be found as follows:
|
|
@@ -822,21 +865,21 @@ Example files are available at the **[tutorial](tutorial)** folder (human calmod
|
|
|
822
865
|
## Using OpenMM inputs and heavy atoms NMs
|
|
823
866
|
```
|
|
824
867
|
pyadmd run -src OPENMM \
|
|
825
|
-
-m HEAVY \
|
|
826
868
|
-psf tutorial/system.psf \
|
|
827
869
|
-rst tutorial/system.rst \
|
|
828
|
-
-pdb tutorial/system.pdb
|
|
870
|
+
-pdb tutorial/system.pdb \
|
|
871
|
+
-m HEAVY
|
|
829
872
|
```
|
|
830
873
|
## Using NAMD inputs and Cα NMs with custom parameters
|
|
831
874
|
```
|
|
832
875
|
pyadmd run -src NAMD \
|
|
833
|
-
-m CA \
|
|
834
876
|
-psf tutorial/system.psf \
|
|
835
877
|
-pdb tutorial/system.pdb \
|
|
836
878
|
-coor tutorial/system.coor \
|
|
837
879
|
-vel tutorial/system.vel \
|
|
838
880
|
-xsc tutorial/system.xsc \
|
|
839
881
|
-str tutorial/system.str \
|
|
882
|
+
-m CA \
|
|
840
883
|
-nm 7,8 \
|
|
841
884
|
-ek 0.5 \
|
|
842
885
|
-t 100 \
|
|
@@ -846,14 +889,14 @@ pyadmd run -src NAMD \
|
|
|
846
889
|
## Using NAMD inputs and CHARMM NMs without direction correction (standard MDeNM)
|
|
847
890
|
```
|
|
848
891
|
pyadmd run -src NAMD \
|
|
849
|
-
-m CHARMM \
|
|
850
|
-
-mod tutorial/system.mod \
|
|
851
892
|
-psf tutorial/system.psf \
|
|
852
893
|
-pdb tutorial/system.pdb \
|
|
853
894
|
-coor tutorial/system.coor \
|
|
854
895
|
-vel tutorial/system.vel \
|
|
855
896
|
-xsc tutorial/system.xsc \
|
|
856
897
|
-str tutorial/system.str \
|
|
898
|
+
-m CHARMM \
|
|
899
|
+
-mod tutorial/system.mod \
|
|
857
900
|
--no-correc
|
|
858
901
|
```
|
|
859
902
|
## Restart unfinished pyAdMD simulations
|