NeuroCGMD

Quantum-Classical-CG-ML Cooperative Molecular Dynamics Engine

One simulation. One information stream. All-atom accuracy at coarse-grained speed.

Install  •  Quickstart  •  Architecture  •  Analysis  •  Contact

---

What is NeuroCGMD?

NeuroCGMD is a next-generation molecular dynamics engine that fuses four layers of physics into a single cooperative simulation:

Layer	What it does	Why it matters
CG Dynamics	Langevin integration with classical forcefields	Speed: ~1000 steps/min
QCloud	Quantum-informed force corrections on priority regions	Accuracy: AA-level physics where it counts
ML Residual	Neural network learns correction patterns on-the-fly	Efficiency: reduces QCloud calls over time
Back-mapping	Reconstructs full all-atom coordinates from CG	Detail: real residue names, H-bonds, contacts

The result: a 500 KB pure-Python package that does what legacy codes need millions of lines of Fortran/C++ to achieve.

---

Install

pip install neurocgmd

That's it. No compilation, no Fortran, no MPI configuration. Works on any platform with Python 3.11+.

From source:

git clone https://github.com/bessuman/neurocgmd.git
cd neurocgmd
pip install -e .

Verify:

neurocgmd info

---

Quickstart

1. Run a simulation

neurocgmd run examples/barnase_barstar.toml

This single command:

• Imports the PDB structure and maps to coarse-grained beads
• Runs NVT equilibration, NPT equilibration, and production dynamics
• Applies QCloud quantum corrections with adaptive region focusing
• Trains the ML residual model on-the-fly
• Back-maps the CG trajectory to full all-atom coordinates
• Generates 20+ publication-quality analysis plots
• Exports CG and AA trajectory PDB files

2. Analyze an existing trajectory

neurocgmd analyze examples/barnase_barstar.toml

3. Write your own config

[system]
name = "my_protein"
pdb_source = "structures/my_protein.pdb"

[dynamics]
stages = ["nvt", "npt", "production"]

[dynamics.production]
steps = 100000
time_step = 0.02
temperature = 300.0
eval_stride = 50        # Full QCloud+ML every 50 steps

---

Architecture

                    +--------------------------------------------------+
                    |            SIMULATION ENGINE                      |
                    |                                                  |
                    |   CG Dynamics    QCloud Layer    ML Residual     |
                    |   +---------+   +-----------+   +-----------+   |
                    |   | Langevin|-->| Region    |-->| Residual  |   |
                    |   | Integr. |   | Selector  |   | Predictor |   |
                    |   +---------+   +-----------+   +-----------+   |
                    |   | Force   |   | Quantum   |   | On-the-fly|   |
                    |   | Field   |   | Correct.  |   | Training  |   |
                    |   +---------+   +-----------+   +-----------+   |
                    |                                                  |
                    |   F_total = F_CG + F_QCloud + F_ML --> integrator|
                    +----------------------|---------------------------+
                                           |
                                           v
                    +--------------------------------------------------+
                    |              BACK-MAPPING                         |
                    |   CG positions --> interpolation --> AA coords    |
                    |   (carries CG + QCloud + ML information)         |
                    +----------------------|---------------------------+
                                           |
                              +------------+------------+
                              |            |            |
                              v            v            v
                        CG Analysis   AA Analysis   QCloud Analysis
                        (collective)  (atomic)      (corrections)

The cooperative principle

Each CG position at every timestep encodes three sources of information:

1. Classical CG forces drive the base dynamics
2. QCloud quantum corrections refine forces on priority regions (adaptive focus from correction feedback)
3. ML residual predictions fill in learned correction patterns between QCloud evaluations

When we back-map CG to AA, the all-atom coordinates inherit all three layers. The AA-level analysis (residue contacts, H-bonds, binding hotspots) therefore reflects quantum-corrected physics at atomic resolution.

Intelligent analysis routing

Each analysis goes to the level where it is most meaningful:

Level	Analyses	Why this level
CG	RMSD, RMSF, Rg, SASA, PMF, free energy landscape, RDF	Collective variables don't benefit from AA resolution
AA	Residue-residue contacts, H-bonds (angle+distance), interface hotspots, binding decomposition	Needs actual amino acid identity and geometry
QCloud	Structural events, correction timeline, adaptive focus regions	Specific to the quantum correction feedback

---

Analysis Output

A single neurocgmd run produces:

Dynamics & Thermodynamics

• Energy time series (PE, KE, total)
• RMSD / RMSF structural analysis
• Radial distribution function g(r)
• SASA and radius of gyration

Free Energy

• Potential of mean force (Boltzmann inversion)
• 2D free energy landscape (COM distance vs Rg)
• Reaction coordinate trajectory

Binding Interactions (auto-detected)

• Inter-chain contact maps (CG and AA level)
• Pairwise binding energy decomposition
• Top interacting residue pairs (with H-bond overlay)
• Per-residue binding contribution profiles
• Interface H-bond network with angle validation

Quantum Correction Insights

• QCloud structural event detection
• Event timeline with correction magnitudes
• Per-bead energy decomposition

Trajectory Export

• CG trajectory PDB (multi-model)
• AA back-mapped trajectory PDB
• Initial/final snapshots (CG and AA)
• Reference crystal structure

---

How it compares

	NeuroCGMD	GROMACS	OpenMM	NAMD
Language	Pure Python	C/C++/CUDA	C++/Python	C++/Charm++
Install	pip install	Compile from source	conda	Compile
Package size	500 KB	~50 MB	~200 MB	~100 MB
Dependencies	numpy, matplotlib	FFTW, MPI, CUDA...	OpenCL, CUDA...	MPI, Charm++...
CG + QM coupling	Native cooperative	Separate tools	Via plugins	Not built-in
ML corrections	On-the-fly training	External	Via OpenMM-ML	External
Auto analysis	Built-in (20+ plots)	Separate tools	Manual	Separate tools
Back-mapping	Integrated	Third-party	Third-party	Third-party

---

Project Layout

core/           State models, provenance, lifecycle registry
physics/        Neighbor lists, force kernels, cell lists
forcefields/    Hybrid engine: classical + QCloud + ML composition
integrators/    BAOAB Langevin, Velocity-Verlet Langevin
qcloud/         Quantum corrections, region selection, event analysis
ml/             Neural residual model, online training, uncertainty
sampling/       Production engine, stage runner, eval stride control
validation/     Observables: SASA, Rg, H-bonds, contacts, RDF, RMSD
scripts/        CLI, plotting, back-mapping, binding analysis
topology/       System topology, bead mapping, bond graphs
config/         TOML manifest parsing, protein mapping tables
chemistry/      Residue semantics, interface logic
spring/         SPRING universal optimizer + NeuroCGMD bridge

---

Contact

Academic collaboration	bessuman.academia@gmail.com
Bug reports	bessuman.academia@gmail.com
Technical support	bessuman.academia@gmail.com
Commercial licensing	bessuman.academia@gmail.com

Each link opens a pre-filled email with the appropriate subject line and template.

---

Citation

If you use NeuroCGMD in your research, please cite:

@software{neurocgmd2026,
  author  = {Essuman, Bernard},
  title   = {NeuroCGMD: Quantum-Classical-CG-ML Cooperative Molecular Dynamics Engine},
  year    = {2026},
  version = {1.0.0},
  url     = {https://github.com/bessuman/neurocgmd}
}

---

License

MIT License. See LICENSE for details.

---

_{Built with cooperative intelligence. 500 KB of Python that speaks the language of atoms.}