How alison-jarvis/dow-aacg-workflow works
1. Overall shape
- This repo is a configuration-driven molecular simulation workflow that goes from atomistic MD (AAMD) to coarse-grained MD (CGMD), then into analysis/validation.
- The core unit of work is a named project folder created from the system config; all outputs for that run are written there.
2. Execution/runtime boundary
- The repo is designed to run inside an Apptainer container rather than directly on the host.
- build.sh, entrypoint.sh, mamba_env.def, and environment.yml define and launch the runtime environment, which matters because the workflow depends on the simulation stack and GPU passthrough.
3. Top-level orchestration
- The shell scripts are the primary user-facing entry points:
- run_aamd_sim.sh for atomistic simulation
- run_cgmd_sim.sh for coarse-grained simulation
- run_validation.sh for comparing/validating results
- plot_sim.sh for postprocessing/visualization
- interactive.sh for ad hoc container use
- These scripts are the boundary between user input and the Python simulation code in src/.
4. Configuration model
- The workflow is driven by two config layers:
- system_config_files/: what system to simulate, including molecules, counts, densities, mixture type, ensemble, temperature, pressure
- general_config_files/: how the MD engine should run, including forcefield, water model, cutoffs, timestep, equilibration/production times, logging frequencies
- This separation is important architecturally: system identity and composition are decoupled from simulation physics/runtime settings.
5. Atomistic simulation subsystem
- src/AllAtomSimulation.py is the core AAMD driver.
- Supporting modules such as src/aamd_utils.py, src/BoxPacker.py, src/smiles_input.py, and src/plot_aamd.py provide setup, packing, input handling, visualization, and analysis helpers.
- src/run_aamd.py appears to be the command-line/Python wrapper around the atomistic pipeline.
6. Initial system construction
- BoxPacker.py and related config files imply an initial-stage subsystem that builds the starting simulation box from SMILES-defined molecules, counts, densities, and mixture type.
- The mixture modes in the system config create an important branch in the data flow:
- fully mixed
- separated phases
- COI dissolved into solvent
- This initial packing step is a key boundary because it determines the topology and starting coordinates fed into MD.
7. Coarse-graining / mapping subsystem
- src/auto_mapper.py and src/cg_build.py indicate a mapping/build stage that converts atomistic descriptions into coarse-grained representations.
- src/CoarseGrainSimulation.py is the CGMD driver, while src/cgmd_utils.py likely holds CG-specific helpers.
- This is the handoff point from AAMD-generated structures/trajectories into CGMD model construction.
8. CGMD simulation subsystem
- The coarse-grained simulation path is separate from the atomistic path, with its own driver and utilities.
- run_cgmd_sim.sh is the external entry point; internally it likely consumes the mapped CG system and the same style of project/config inputs to run the reduced-resolution simulation.
9. Analysis and visualization
- plot_sim.sh is a project-level reporting hook that generates plots for temperature, density, volume, and energies from OpenMM logs.
- src/plot_aamd.py and the visualize_trajectory helper in aamd_utils.py provide interactive inspection of the trajectory data.
- These tools operate on run artifacts rather than driving the simulations themselves.
10. Validation subsystem
- validation/ValidateSimulation.py, validation/validation_utils.py, and validation/run_validation.py form a dedicated comparison layer.
- Its role is to assess whether CGMD reproduces the relevant behavior/statistics from the AAMD workflow, rather than producing the simulation itself.
11. Data artifacts and flow
- Typical outputs include:
- trajectory files (.dcd)
- topology/structure files (.pdb)
- simulation logs (log.txt or similar)
- plot folders for derived figures
- The main data flow is: configs + SMILES-like inputs → packed initial system → AAMD run → CG mapping/build → CGMD run → plots/validation.
12. Important architectural boundary
- The repo cleanly separates:
- user-facing orchestration in shell scripts
- simulation logic in src/
- postprocessing/verification in validation/
- For an architecture diagram, the most important arrows are from config files into the simulation drivers, and from simulation outputs into plotting and validation.
Main entry points: AllAtomSimulation.py AAMD driver · entrypoint.sh entrypoint.sh · CoarseGrainSimulation.py CGMD driver · ValidateSimulation.py ValidateSimulation
Components 25
Runtime
Containerized execution environment and launch wrappers.
- build.sh · Builds the Apptainer runtime image.
build.sh - entrypoint.sh · Container startup entrypoint.
entrypoint.sh - environment.yml · Conda-style environment definition for the simulation stack.
environment.yml - mamba_env.def · Apptainer definition for the mamba-based runtime.
mamba_env.def
Orchestration
User-facing shell entry points for running the workflow.
- run AAMD · Shell entry point for atomistic simulation runs.
run_aamd_sim.sh - run CGMD · Shell entry point for coarse-grained simulation runs.
run_cgmd_sim.sh - run validation · Shell entry point for validation runs.
run_validation.sh - plot sim · Shell entry point for postprocessing and plotting.
plot_sim.sh - interactive · Interactive container access for ad hoc use.
interactive.sh
Configuration
System identity and simulation-physics settings.
- system configs · System composition, mixture mode, ensemble, and state settings.
system_config_files - general configs · Forcefield, cutoffs, timesteps, and run-control settings.
general_config_files
AAMD
Atomistic setup, simulation, and analysis.
- SMILES input · Parses molecule identity and composition inputs.
src/smiles_input.py - Box packer · Builds the initial simulation box from configured molecules and densities.
src/BoxPacker.py - AAMD driver · Core atomistic MD workflow driver.
src/AllAtomSimulation.py - AAMD utils · Shared helpers for setup, execution, and inspection.
src/aamd_utils.py - run_aamd.py · Python wrapper for launching the atomistic pipeline.
src/run_aamd.py - AAMD plots · Atomistic trajectory and log plotting helpers.
src/plot_aamd.py
CGMD
Coarse-graining, model build, and reduced-resolution simulation.
- auto mapper · Maps atomistic structures to coarse-grained representations.
src/auto_mapper.py - CG build · Builds coarse-grained model inputs and topology.
src/cg_build.py - CGMD driver · Core coarse-grained MD workflow driver.
src/CoarseGrainSimulation.py - CGMD utils · Coarse-grained simulation helpers and shared utilities.
src/cgmd_utils.py - run_cgmd.py · Python wrapper for launching the coarse-grained pipeline.
src/run_cgmd.py
Validation
Comparison and validation of simulation outputs.
- ValidateSimulation · Compares CGMD behavior against AAMD-derived reference data.
validation/ValidateSimulation.py - validation utils · Support routines for validation metrics and comparisons.
validation/validation_utils.py - run_validation.py · Python entry point for validation workflows.
validation/run_validation.py
Connections 28
- build.sh → mamba_env.def: builds · Defines the container environment.
- mamba_env.def → environment.yml: installs · Pulls in the runtime dependencies.
- entrypoint.sh → run AAMD: launches · Container entrypoint dispatches workflow commands.
- entrypoint.sh → run CGMD: launches · Container entrypoint dispatches workflow commands.
- entrypoint.sh → run validation: launches · Container entrypoint dispatches workflow commands.
- entrypoint.sh → plot sim: launches · Container entrypoint dispatches workflow commands.
- entrypoint.sh → interactive: launches · Container entrypoint dispatches workflow commands.
- system configs → SMILES input: defines inputs · System config drives molecule and mixture parsing.
- system configs → Box packer: defines system · Composition and density determine the starting box.
- general configs → AAMD driver: configures · Physics and run-control settings feed the atomistic driver.
- general configs → CGMD driver: configures · Physics and run-control settings feed the CG driver.
- run AAMD → run_aamd.py: invokes · Shell wrapper calls the atomistic Python entry point.
- run_aamd.py → AAMD driver: drives · Python wrapper starts the AAMD workflow.
- AAMD driver → Box packer: builds from · Atomistic simulation begins with packed starting coordinates.
- Box packer → SMILES input: uses · Packing uses molecule definitions and counts.
- AAMD driver → AAMD utils: uses · Simulation driver depends on atomistic helpers.
- AAMD driver → AAMD plots: outputs to · Produces data for atomistic plotting and inspection.
- run CGMD → run_cgmd.py: invokes · Shell wrapper calls the CG Python entry point.
- run_cgmd.py → auto mapper: starts · CG workflow begins with mapping atomistic structures.
- auto mapper → CG build: feeds · Mapped representations are used to build the CG model.
- CG build → CGMD driver: prepares · CG build outputs are consumed by the CGMD driver.
- CGMD driver → CGMD utils: uses · CG driver depends on coarse-grained helpers.
- run validation → run_validation.py: invokes · Shell wrapper calls the validation entry point.
- run_validation.py → ValidateSimulation: drives · Validation wrapper starts the comparison workflow.
- ValidateSimulation → validation utils: uses · Validation logic relies on comparison helpers.
- plot sim → AAMD plots: invokes · Plotting script reuses atomistic plotting routines.
- AAMD driver → ValidateSimulation: provides data · Atomistic outputs serve as the reference for validation.
- CGMD driver → ValidateSimulation: provides data · CG outputs are compared against the atomistic reference.