Classical Atomistic Formation Engine
Deterministic structure generation from elemental identity + thermodynamic boundary conditions
Long-term development targets reaction modeling and structured multiscale coupling while preserving reproducibility and auditability. Long-term development targets expanding reaction modeling, and creating multiscale coupling while preserving reproducibility and auditability.
Included in this release:
- Formal methodology: 13 LaTeX sections (186 pages) documenting every equation, parameter, and design decision
- Validation-first: 35 hierarchical tests across 5 levels (80% pass rate)
- Production certified: Approved for noble gases, hydrocarbons, and small organic molecules
- Deterministic by design: Same inputs → bit-identical output across platforms
- Hash-based provenance: Every structure carries full generation history (SHA-256)
- Self-audit infrastructure: Autonomous failure classification, gap targeting, regression detection
Guiding principle:
Every state is reproducible. Every result is traceable. Structure is a primary simulation output, not an input assumption.
- Lennard-Jones 12-6 + Coulomb + bonded MM (UFF parameterization)
- Velocity Verlet (NVE), Langevin (NVT), FIRE minimization
- Periodic boundary conditions (orthogonal boxes)
- Supercell replication with bond re-inference
- Explicit units throughout (Å, fs, kcal/mol, amu, K)
.xyz → Static geometry (element + Cartesian coordinates)
.xyza → Animated trajectory (sequential frames)
.xyzc → Checkpointed MD (positions + velocities + thermodynamics + SHA-256 hash)
- Interactive CLI: Molecular construction and manipulation
- Simulation engine: MD/minimization with FIRE, Verlet, and Langevin integrators
- OpenGL viewer: 3D visualization with atom tooltips
- Self-audit suite: Python tools for failure analysis and regression detection
The scientific foundation lives in 11 standalone LaTeX files (186 pages total).
| Document | Pages | Purpose |
|---|---|---|
METHODOLOGY_2PAGE.tex |
2 | Conference handout (two-column summary) |
METHODOLOGY_12PAGE.tex |
12 | Quick reference with equations |
| File | Sections | Content |
|---|---|---|
section0_identity_state_decomposition.tex |
§0 | Particle identity vectors, cell/world container ontology |
section1_foundational_thesis.tex |
§1 | Problem definition, scope, domain of validity |
section2_state_ontology.tex |
§2 | State tuple, identity/phase/scratch partitioning |
section3_interaction_model.tex |
§3 | LJ, Coulomb, UFF, switching, PBC |
section4_thermodynamics.tex |
§4 | Unit system, temperature, pressure, heat capacity |
section5_integration.tex |
§5 | Verlet, Langevin, FIRE algorithms |
section6_formation_physics.tex |
§6 | Bonded terms, formation pipeline, basin mapping |
section7_statistical_interpretation.tex |
§7 | Welford, stationarity, Kabsch, scoring |
section8_9_reaction_electronic.tex |
§8-9 | QEq, Fukui functions, HSAB, reaction templates |
section10_12_13_closing.tex |
§10,12,13 | Multiscale, validation doctrine (35 tests), roadmap |
section11_self_audit.tex |
§11 | Failure classifier, gap targeter, regression detector |
Compile with:
cd docs && for f in section*.tex; do pdflatex "$f"; doneFull index: docs/INDEX.md
chmod +x vseprw
./vseprw H2O relax # First run: configure + build + minimize
./vseprw molecule.xyz sim --temp 300 # MD simulation at 300 K
./vseprw molecule.xyz view # 3D visualizationcmake -B build && cmake --build build -j8
# Interactive molecular builder (formula pipeline)
./build/atomistic-build
>> build H2O
>> info
>> save H2O.xyz
>> exit
# Energy minimization
./build/atomistic-relax H2O.xyz
# Molecular dynamics
./build/atomistic-sim simulate H2O.xyz --temp 300 --steps 10000
# 3D viewer
./build/interactive-viewer H2O.xyzvsepr-sim/
├── src/ Core C++ engine (170 files)
│ ├── core/ State, force evaluation, energy ledger
│ ├── sim/ Integrators (Verlet, Langevin, FIRE)
│ ├── pot/ Potentials (LJ, Coulomb, bonded MM)
│ ├── box/ Periodic boundaries
│ ├── io/ XYZ/XYZA/XYZC parsers
│ └── cli/ Command-line interface
├── include/ Public headers (51 files)
├── apps/ Entry points (35 applications)
│ ├── cli.cpp # Interactive builder
│ ├── relax.cpp # Energy minimization
│ ├── simulate.cpp # MD engine
│ └── viewer.cpp # OpenGL visualization
├── tests/ Validation suite (56 files)
│ ├── energy_tests.cpp
│ ├── ensemble_consistency_test.cpp
│ └── basic_molecule_validation.cpp
├── docs/ LaTeX methodology + notebooks
│ ├── section*.tex (11 files, 186 pages)
│ ├── METHODOLOGY_2PAGE.tex
│ ├── METHODOLOGY_12PAGE.tex
│ └── VALIDATION_REPORT.md
├── tools/ Self-audit Python scripts
│ ├── failure_classifier.py
│ ├── gap_targeter.py
│ └── regression_detector.py
├── data/ Reference geometries
├── examples/ Demo molecules (.xyz)
└── third_party/ ImGui (vendored)
✅ Approved for:
- Noble gas systems (Ar, Xe, Kr)
- Hydrocarbon molecules (CH₄, benzene, alkanes)
- Small organics (H₂O, NH₃, CH₃OH)
- Molecular clusters
❌ Known limitations:
- Ionic MD (NaCl, MgO) — Use FIRE only until Coulomb-integrator coupling is fixed
- Transition metal complexes — Classical approximation insufficient
Full report: docs/VALIDATION_REPORT.md
- Explicit units everywhere — Positions in Å, energies in kcal/mol. No reduced units.
- No silent domain switching — Force field, integrator, and BC declared upfront.
- Deterministic core — Identical inputs produce bit-identical outputs (seeded RNG).
- Periodic table as sole authority — No molecular databases. Parameters from UFF.
- Extension without replacement — Validated core remains intact.
- Compiler: GCC 7+, Clang 10+, or MSVC 2019+ (C++20 support)
- Build System: CMake 3.15+
- Graphics (optional): OpenGL 3.3+, GLFW, GLEW
- GPU (optional): CUDA toolkit (graceful CPU fallback)
- OS: Linux, Windows (WSL recommended), macOS
MIT License — see LICENSE for details.
- Universal Force Field (UFF) parameterization: Rappé et al., J. Am. Chem. Soc. 114, 10024 (1992)
- FIRE minimization: Bitzek et al., Phys. Rev. Lett. 97, 170201 (2006)
- Kabsch alignment: Kabsch, Acta Cryst. A32, 922 (1976)
- ImGui: Omar Cornut et al. (vendored under MIT license)
Documentation • Methodology • Validation • GitHub
This is not a theoretical proposal. This is a documented, validated, production-ready scientific instrument.