# alison-jarvis/dow-aacg-workflow architecture

> Architecture diagram of the GitHub repository alison-jarvis/dow-aacg-workflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alison-jarvis/dow-aacg-workflow
- Repository: https://github.com/alison-jarvis/dow-aacg-workflow

## Overview

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: [`src/AllAtomSimulation.py`](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/AllAtomSimulation.py) (AAMD driver), [`entrypoint.sh`](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/entrypoint.sh) (entrypoint.sh), [`src/CoarseGrainSimulation.py`](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/CoarseGrainSimulation.py) (CGMD driver), [`validation/ValidateSimulation.py`](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/ValidateSimulation.py) (ValidateSimulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_build_sh["build.sh<br/>container build<br/>[build.sh]"]
  node_entrypoint_sh["entrypoint.sh<br/>container entry<br/>[entrypoint.sh]"]
  node_environment_yml["environment.yml<br/>deps spec<br/>[environment.yml]"]
  node_mamba_env_def["mamba_env.def<br/>apptainer def<br/>[mamba_env.def]"]
end

subgraph group_orchestration["Orchestration"]
  node_run_aamd_sim_sh["run AAMD<br/>workflow entry<br/>[run_aamd_sim.sh]"]
  node_run_cgmd_sim_sh["run CGMD<br/>workflow entry<br/>[run_cgmd_sim.sh]"]
  node_run_validation_sh["run validation<br/>workflow entry<br/>[run_validation.sh]"]
  node_plot_sim_sh["plot sim<br/>workflow entry<br/>[plot_sim.sh]"]
  node_interactive_sh["interactive<br/>workflow entry<br/>[interactive.sh]"]
end

subgraph group_config["Configuration"]
  node_system_configs["system configs<br/>system model"]
  node_general_configs["general configs<br/>md settings"]
end

subgraph group_aamd["AAMD"]
  node_smiles_input_py["SMILES input<br/>input parser<br/>[smiles_input.py]"]
  node_box_packer_py["Box packer<br/>system builder<br/>[BoxPacker.py]"]
  node_all_atom_sim_py["AAMD driver<br/>atomistic driver"]
  node_aamd_utils_py["AAMD utils<br/>atomistic helpers<br/>[aamd_utils.py]"]
  node_run_aamd_py["run_aamd.py<br/>python wrapper<br/>[run_aamd.py]"]
  node_plot_aamd_py["AAMD plots<br/>analysis helper<br/>[plot_aamd.py]"]
end

subgraph group_cgmd["CGMD"]
  node_auto_mapper_py["auto mapper<br/>mapping stage<br/>[auto_mapper.py]"]
  node_cg_build_py["CG build<br/>cg model build<br/>[cg_build.py]"]
  node_coarse_grain_sim_py["CGMD driver<br/>cg driver"]
  node_cgmd_utils_py["CGMD utils<br/>cg helpers<br/>[cgmd_utils.py]"]
  node_run_cgmd_py["run_cgmd.py<br/>python wrapper<br/>[run_cgmd.py]"]
end

subgraph group_validation["Validation"]
  node_validate_sim_py["ValidateSimulation<br/>validator"]
  node_validation_utils_py["validation utils<br/>compare helpers"]
  node_run_validation_py["run_validation.py<br/>validation wrapper<br/>[run_validation.py]"]
end

node_build_sh -->|"builds"| node_mamba_env_def
node_mamba_env_def -->|"installs"| node_environment_yml
node_entrypoint_sh -->|"launches"| node_run_aamd_sim_sh
node_entrypoint_sh -->|"launches"| node_run_cgmd_sim_sh
node_entrypoint_sh -->|"launches"| node_run_validation_sh
node_entrypoint_sh -->|"launches"| node_plot_sim_sh
node_entrypoint_sh -->|"launches"| node_interactive_sh
node_system_configs -->|"defines inputs"| node_smiles_input_py
node_system_configs -->|"defines system"| node_box_packer_py
node_general_configs -->|"configures"| node_all_atom_sim_py
node_general_configs -->|"configures"| node_coarse_grain_sim_py
node_run_aamd_sim_sh -->|"invokes"| node_run_aamd_py
node_run_aamd_py -->|"drives"| node_all_atom_sim_py
node_all_atom_sim_py -->|"builds from"| node_box_packer_py
node_box_packer_py -->|"uses"| node_smiles_input_py
node_all_atom_sim_py -->|"uses"| node_aamd_utils_py
node_all_atom_sim_py -->|"outputs to"| node_plot_aamd_py
node_run_cgmd_sim_sh -->|"invokes"| node_run_cgmd_py
node_run_cgmd_py -->|"starts"| node_auto_mapper_py
node_auto_mapper_py -->|"feeds"| node_cg_build_py
node_cg_build_py -->|"prepares"| node_coarse_grain_sim_py
node_coarse_grain_sim_py -->|"uses"| node_cgmd_utils_py
node_run_validation_sh -->|"invokes"| node_run_validation_py
node_run_validation_py -->|"drives"| node_validate_sim_py
node_validate_sim_py -->|"uses"| node_validation_utils_py
node_plot_sim_sh -->|"invokes"| node_plot_aamd_py
node_all_atom_sim_py -.->|"provides data"| node_validate_sim_py
node_coarse_grain_sim_py -.->|"provides data"| node_validate_sim_py

click node_build_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/build.sh"
click node_entrypoint_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/entrypoint.sh"
click node_environment_yml "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/environment.yml"
click node_mamba_env_def "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/mamba_env.def"
click node_run_aamd_sim_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/run_aamd_sim.sh"
click node_run_cgmd_sim_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/run_cgmd_sim.sh"
click node_run_validation_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/run_validation.sh"
click node_plot_sim_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/plot_sim.sh"
click node_interactive_sh "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/interactive.sh"
click node_system_configs "https://github.com/alison-jarvis/dow-aacg-workflow/tree/main/system_config_files"
click node_general_configs "https://github.com/alison-jarvis/dow-aacg-workflow/tree/main/general_config_files"
click node_smiles_input_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/smiles_input.py"
click node_box_packer_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/BoxPacker.py"
click node_all_atom_sim_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/AllAtomSimulation.py"
click node_aamd_utils_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/aamd_utils.py"
click node_run_aamd_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/run_aamd.py"
click node_plot_aamd_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/plot_aamd.py"
click node_auto_mapper_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/auto_mapper.py"
click node_cg_build_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/cg_build.py"
click node_coarse_grain_sim_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/CoarseGrainSimulation.py"
click node_cgmd_utils_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/cgmd_utils.py"
click node_run_cgmd_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/run_cgmd.py"
click node_validate_sim_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/ValidateSimulation.py"
click node_validation_utils_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/validation_utils.py"
click node_run_validation_py "https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/run_validation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_sh,node_entrypoint_sh,node_environment_yml,node_mamba_env_def toneBlue
class node_run_aamd_sim_sh,node_run_cgmd_sim_sh,node_run_validation_sh,node_plot_sim_sh,node_interactive_sh toneAmber
class node_system_configs,node_general_configs toneMint
class node_smiles_input_py,node_box_packer_py,node_all_atom_sim_py,node_aamd_utils_py,node_run_aamd_py,node_plot_aamd_py toneRose
class node_auto_mapper_py,node_cg_build_py,node_coarse_grain_sim_py,node_cgmd_utils_py,node_run_cgmd_py toneIndigo
class node_validate_sim_py,node_validation_utils_py,node_run_validation_py toneTeal
```

## Components

### Runtime

Containerized execution environment and launch wrappers.

- [build.sh](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/build.sh): container build · Builds the Apptainer runtime image. · `build.sh`
- [entrypoint.sh](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/entrypoint.sh): container entry · Container startup entrypoint. · `entrypoint.sh`
- [environment.yml](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/environment.yml): deps spec · Conda-style environment definition for the simulation stack. · `environment.yml`
- [mamba_env.def](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/mamba_env.def): apptainer def · Apptainer definition for the mamba-based runtime. · `mamba_env.def`

### Orchestration

User-facing shell entry points for running the workflow.

- [run AAMD](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/run_aamd_sim.sh): workflow entry · Shell entry point for atomistic simulation runs. · `run_aamd_sim.sh`
- [run CGMD](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/run_cgmd_sim.sh): workflow entry · Shell entry point for coarse-grained simulation runs. · `run_cgmd_sim.sh`
- [run validation](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/run_validation.sh): workflow entry · Shell entry point for validation runs. · `run_validation.sh`
- [plot sim](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/plot_sim.sh): workflow entry · Shell entry point for postprocessing and plotting. · `plot_sim.sh`
- [interactive](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/interactive.sh): workflow entry · Interactive container access for ad hoc use. · `interactive.sh`

### Configuration

System identity and simulation-physics settings.

- [system configs](https://github.com/alison-jarvis/dow-aacg-workflow/tree/main/system_config_files): system model · System composition, mixture mode, ensemble, and state settings. · `system_config_files`
- [general configs](https://github.com/alison-jarvis/dow-aacg-workflow/tree/main/general_config_files): md settings · Forcefield, cutoffs, timesteps, and run-control settings. · `general_config_files`

### AAMD

Atomistic setup, simulation, and analysis.

- [SMILES input](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/smiles_input.py): input parser · Parses molecule identity and composition inputs. · `src/smiles_input.py`
- [Box packer](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/BoxPacker.py): system builder · Builds the initial simulation box from configured molecules and densities. · `src/BoxPacker.py`
- [AAMD driver](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/AllAtomSimulation.py): atomistic driver · Core atomistic MD workflow driver. · `src/AllAtomSimulation.py`
- [AAMD utils](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/aamd_utils.py): atomistic helpers · Shared helpers for setup, execution, and inspection. · `src/aamd_utils.py`
- [run_aamd.py](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/run_aamd.py): python wrapper · Python wrapper for launching the atomistic pipeline. · `src/run_aamd.py`
- [AAMD plots](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/plot_aamd.py): analysis helper · Atomistic trajectory and log plotting helpers. · `src/plot_aamd.py`

### CGMD

Coarse-graining, model build, and reduced-resolution simulation.

- [auto mapper](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/auto_mapper.py): mapping stage · Maps atomistic structures to coarse-grained representations. · `src/auto_mapper.py`
- [CG build](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/cg_build.py): cg model build · Builds coarse-grained model inputs and topology. · `src/cg_build.py`
- [CGMD driver](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/CoarseGrainSimulation.py): cg driver · Core coarse-grained MD workflow driver. · `src/CoarseGrainSimulation.py`
- [CGMD utils](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/cgmd_utils.py): cg helpers · Coarse-grained simulation helpers and shared utilities. · `src/cgmd_utils.py`
- [run_cgmd.py](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/src/run_cgmd.py): python wrapper · Python wrapper for launching the coarse-grained pipeline. · `src/run_cgmd.py`

### Validation

Comparison and validation of simulation outputs.

- [ValidateSimulation](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/ValidateSimulation.py): validator · Compares CGMD behavior against AAMD-derived reference data. · `validation/ValidateSimulation.py`
- [validation utils](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/validation_utils.py): compare helpers · Support routines for validation metrics and comparisons. · `validation/validation_utils.py`
- [run_validation.py](https://github.com/alison-jarvis/dow-aacg-workflow/blob/main/validation/run_validation.py): validation wrapper · Python entry point for validation workflows. · `validation/run_validation.py`

## Connections

- 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.
