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.
Files changed (46) hide show
  1. {pyadmd-3.2.3/src/pyadmd.egg-info → pyadmd-3.4.0}/PKG-INFO +92 -49
  2. {pyadmd-3.2.3 → pyadmd-3.4.0}/README.md +92 -49
  3. {pyadmd-3.2.3 → pyadmd-3.4.0}/pyproject.toml +1 -1
  4. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/__init__.py +1 -1
  5. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/analysis/analyzer.py +270 -1
  6. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/commands.py +47 -9
  7. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/parser.py +18 -4
  8. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/console.py +1 -1
  9. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/enm/calculator.py +176 -50
  10. pyadmd-3.4.0/src/pyadmd/enm/rtb.py +264 -0
  11. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/fel/calculator.py +91 -134
  12. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/modes/exciter.py +24 -5
  13. pyadmd-3.4.0/src/pyadmd/modes/projection.py +251 -0
  14. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/engine.py +62 -20
  15. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/runner.py +26 -3
  16. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/system_builder.py +52 -3
  17. {pyadmd-3.2.3 → pyadmd-3.4.0/src/pyadmd.egg-info}/PKG-INFO +92 -49
  18. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/SOURCES.txt +2 -0
  19. {pyadmd-3.2.3 → pyadmd-3.4.0}/LICENSE +0 -0
  20. {pyadmd-3.2.3 → pyadmd-3.4.0}/setup.cfg +0 -0
  21. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/__main__.py +0 -0
  22. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/analysis/__init__.py +0 -0
  23. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/analysis/completion.py +0 -0
  24. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/charmm/charmm_toppar.zip +0 -0
  25. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/charmm/wrt-nm.mdu +0 -0
  26. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/__init__.py +0 -0
  27. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/cli/main.py +0 -0
  28. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/constants.py +0 -0
  29. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/enm/__init__.py +0 -0
  30. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/enm/analysis.py +0 -0
  31. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/fel/__init__.py +0 -0
  32. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/fel/completion.py +0 -0
  33. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/geometry.py +0 -0
  34. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/__init__.py +0 -0
  35. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/dcd.py +0 -0
  36. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/namd.py +0 -0
  37. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/openmm_restart.py +0 -0
  38. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/params.py +0 -0
  39. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/io/state.py +0 -0
  40. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/modes/__init__.py +0 -0
  41. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/simulation/__init__.py +0 -0
  42. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd/utils.py +0 -0
  43. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/dependency_links.txt +0 -0
  44. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/entry_points.txt +0 -0
  45. {pyadmd-3.2.3 → pyadmd-3.4.0}/src/pyadmd.egg-info/requires.txt +0 -0
  46. {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.2.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
- - [Output Files Description](#output-files-description-1)
109
+ - [Output Files Description](#output-files-description-1)
108
110
  - [Analysis](#analysis-1)
109
111
  - [Basic Structural Properties Calculated](#basic-structural-properties-calculated)
110
- - [Analysis Modes](#analysis-modes)
111
- - [Standard Analysis](#standard-analysis)
112
- - [Rough Analysis](#rough-analysis)
113
- - [Selective Analysis (Skip Flags)](#selective-analysis-skip-flags)
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
- - **`--full_ener`**: Write per-term energy decomposition (BOND, ANGLE, DIHED, IMPRP, CMAP, UBREY, NBFIX, NONBONDED, etc.) to `rep{N}_ener_decomp.log` every cycle
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
- ├── projections_mode[N].npy # raw mode projections (Å)
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
- ## Output Files Description
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 +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.
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
- 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.
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
- ## Analysis Modes
712
- ### Standard Analysis
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
- ### Rough Analysis
718
- - Analyzes frames at *5ps* intervals
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
- ### Selective Analysis (Skip Flags)
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]. Omitted with `--no-dccm`.
798
- - **`dccm_plot.png`** / **`dccm_average.png`**: DCCM heatmap, diverging colormap (red = fully correlated, white = uncorrelated, blue = fully anti-correlated).
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
- - Interactive summary report with tables and embedded plots
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