# glotzerlab/hoomd-blue architecture

> Architecture diagram of the GitHub repository glotzerlab/hoomd-blue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/glotzerlab/hoomd-blue
- Repository: https://github.com/glotzerlab/hoomd-blue

## Overview

HOOMD-blue is a Python interface and native CPU/GPU engine for particle simulations. Users create a simulation, provide or initialize particle state, attach an integrator and its model, then run timesteps and write trajectory or logged data. Its major simulation domains are molecular dynamics (MD), hard-particle Monte Carlo (HPMC), and multiparticle collision dynamics (MPCD), with shared state, device, operation, and communication infrastructure. The graph reflects the README workflows and repository layout; sampled excerpts do not expose every runtime call, so uncertain wiring is omitted.

Main entry points: [`hoomd/operations.py`](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/operations.py) (Operations), [`hoomd/state.py`](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/state.py) (System state), [`hoomd/mpcd/integrate.py`](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/integrate.py) (MPCD integrator), [`hoomd/simulation.py`](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/simulation.py) (Simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Simulation setup"]
  node_simulation["Simulation<br/>[simulation.py]"]
  node_operations["Operations<br/>[operations.py]"]
  node_state["System state<br/>[state.py]"]
  node_snapshot["Snapshot data<br/>[snapshot.py]"]
  node_device["CPU or GPU<br/>[device.py]"]
end

subgraph group_md["Molecular dynamics"]
  node_md_integrator["MD integrator<br/>[integrate.py]"]
  node_md_forces["MD forces<br/>[force.py]"]
  node_neighbor_list["Neighbor lists<br/>[nlist.py]"]
  node_md_pair["Pair potentials<br/>[pair.py]"]
  node_md_methods["Integration methods<br/>[methods.py]"]
end

subgraph group_hpmc["Hard-particle MC"]
  node_hpmc_integrator["HPMC integrator<br/>[integrate.py]"]
  node_hpmc_pair["HPMC pair potentials<br/>[pair.py]"]
  node_hpmc_updates["HPMC updates<br/>[update.py]"]
end

subgraph group_mpcd["Multiparticle dynamics"]
  node_mpcd_integrator["MPCD integrator<br/>[integrate.py]"]
  node_mpcd_collide["Collision methods<br/>[collide.py]"]
  node_mpcd_stream["Streaming methods<br/>[stream.py]"]
  node_mpcd_fill["Virtual particles<br/>[fill.py]"]
end

subgraph group_runtime["Runtime and output"]
  node_analyzers["Analysis operations<br/>[operation.py]"]
  node_updates["State updates<br/>[__init__.py]"]
  node_tuning["Parameter tuning<br/>[__init__.py]"]
  node_gsd_reader["GSD reader<br/>[GSDReader.cc]"]
  node_gsd_writer["GSD writer<br/>[gsd.py]"]
  node_native_core["Native simulation core<br/>[SystemDefinition.h]"]
  node_particle_data[("Particle data<br/>[ParticleData.h]")]
  node_communicator["Domain communication<br/>[Communicator.h]"]
end

node_user(("Simulation user"))
node_trajectory["Trajectory file"]

node_user -->|"configures"| node_simulation
node_simulation -->|"selects device"| node_device
node_simulation -->|"runs operations"| node_operations
node_user -->|"initializes"| node_state
node_snapshot -->|"provides data"| node_state
node_gsd_reader -->|"loads frames"| node_state
node_operations -->|"dispatches"| node_md_integrator
node_operations -->|"dispatches"| node_hpmc_integrator
node_operations -->|"dispatches"| node_mpcd_integrator
node_md_integrator -->|"evaluates forces"| node_md_forces
node_md_integrator -->|"applies methods"| node_md_methods
node_md_forces -->|"uses neighbors"| node_neighbor_list
node_md_pair -->|"provides interactions"| node_md_forces
node_hpmc_integrator -->|"evaluates overlaps"| node_hpmc_pair
node_hpmc_integrator -->|"applies moves"| node_hpmc_updates
node_mpcd_integrator -->|"streams particles"| node_mpcd_stream
node_mpcd_integrator -->|"collides particles"| node_mpcd_collide
node_mpcd_integrator -->|"fills particles"| node_mpcd_fill
node_analyzers -->|"reads state"| node_state
node_updates -->|"modifies state"| node_state
node_tuning -->|"adjusts parameters"| node_operations
node_operations -->|"executes simulation"| node_native_core
node_native_core -->|"accesses particles"| node_particle_data
node_native_core -->|"exchanges domains"| node_communicator
node_gsd_writer -->|"reads state"| node_state
node_gsd_writer -->|"writes frames"| node_trajectory

click node_simulation "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/simulation.py"
click node_operations "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/operations.py"
click node_state "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/state.py"
click node_snapshot "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/snapshot.py"
click node_device "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/device.py"
click node_md_integrator "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/integrate.py"
click node_md_forces "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/force.py"
click node_neighbor_list "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/nlist.py"
click node_md_pair "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/pair/pair.py"
click node_md_methods "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/methods/methods.py"
click node_hpmc_integrator "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/hpmc/integrate.py"
click node_hpmc_pair "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/hpmc/pair/pair.py"
click node_hpmc_updates "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/hpmc/update.py"
click node_mpcd_integrator "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/integrate.py"
click node_mpcd_collide "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/collide.py"
click node_mpcd_stream "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/stream.py"
click node_mpcd_fill "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/fill.py"
click node_analyzers "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/operation.py"
click node_updates "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/update/__init__.py"
click node_tuning "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/tune/__init__.py"
click node_gsd_reader "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/GSDReader.cc"
click node_gsd_writer "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/write/gsd.py"
click node_native_core "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/SystemDefinition.h"
click node_particle_data "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/ParticleData.h"
click node_communicator "https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/Communicator.h"

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_simulation,node_operations,node_state,node_snapshot,node_device,node_user toneBlue
class node_md_integrator,node_md_forces,node_neighbor_list,node_md_pair,node_md_methods toneAmber
class node_hpmc_integrator,node_hpmc_pair,node_hpmc_updates toneMint
class node_mpcd_integrator,node_mpcd_collide,node_mpcd_stream,node_mpcd_fill toneRose
class node_analyzers,node_updates,node_tuning,node_gsd_reader,node_gsd_writer,node_native_core,node_particle_data,node_communicator,node_trajectory toneIndigo
```

## Components

### Simulation setup

- [Simulation](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/simulation.py): `hoomd/simulation.py`
- [Operations](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/operations.py): `hoomd/operations.py`
- [System state](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/state.py): `hoomd/state.py`
- [Snapshot data](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/snapshot.py): `hoomd/snapshot.py`
- [CPU or GPU](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/device.py): `hoomd/device.py`

### Molecular dynamics

- [MD integrator](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/integrate.py): `hoomd/md/integrate.py`
- [MD forces](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/force.py): `hoomd/md/force.py`
- [Neighbor lists](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/nlist.py): `hoomd/md/nlist.py`
- [Pair potentials](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/pair/pair.py): `hoomd/md/pair/pair.py`
- [Integration methods](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/md/methods/methods.py): `hoomd/md/methods/methods.py`

### Hard-particle MC

- [HPMC integrator](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/hpmc/integrate.py): `hoomd/hpmc/integrate.py`
- [HPMC pair potentials](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/hpmc/pair/pair.py): `hoomd/hpmc/pair/pair.py`
- [HPMC updates](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/hpmc/update.py): `hoomd/hpmc/update.py`

### Multiparticle dynamics

- [MPCD integrator](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/integrate.py): `hoomd/mpcd/integrate.py`
- [Collision methods](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/collide.py): `hoomd/mpcd/collide.py`
- [Streaming methods](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/stream.py): `hoomd/mpcd/stream.py`
- [Virtual particles](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/mpcd/fill.py): `hoomd/mpcd/fill.py`

### Runtime and output

- [Analysis operations](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/operation.py): `hoomd/operation.py`
- [State updates](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/update/__init__.py): `hoomd/update/__init__.py`
- [Parameter tuning](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/tune/__init__.py): `hoomd/tune/__init__.py`
- [GSD reader](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/GSDReader.cc): `hoomd/GSDReader.cc`
- [GSD writer](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/write/gsd.py): `hoomd/write/gsd.py`
- [Native simulation core](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/SystemDefinition.h): `hoomd/SystemDefinition.h`
- [Particle data](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/ParticleData.h): `hoomd/ParticleData.h`
- [Domain communication](https://github.com/glotzerlab/hoomd-blue/blob/trunk/hoomd/Communicator.h): `hoomd/Communicator.h`

### Other components

- **Simulation user**
- **Trajectory file**

## Connections

- Simulation user → Simulation: configures
- Simulation → CPU or GPU: selects device
- Simulation → Operations: runs operations
- Simulation user → System state: initializes
- Snapshot data → System state: provides data
- GSD reader → System state: loads frames
- Operations → MD integrator: dispatches
- Operations → HPMC integrator: dispatches
- Operations → MPCD integrator: dispatches
- MD integrator → MD forces: evaluates forces
- MD integrator → Integration methods: applies methods
- MD forces → Neighbor lists: uses neighbors
- Pair potentials → MD forces: provides interactions
- HPMC integrator → HPMC pair potentials: evaluates overlaps
- HPMC integrator → HPMC updates: applies moves
- MPCD integrator → Streaming methods: streams particles
- MPCD integrator → Collision methods: collides particles
- MPCD integrator → Virtual particles: fills particles
- Analysis operations → System state: reads state
- State updates → System state: modifies state
- Parameter tuning → Operations: adjusts parameters
- Operations → Native simulation core: executes simulation
- Native simulation core → Particle data: accesses particles
- Native simulation core → Domain communication: exchanges domains
- GSD writer → System state: reads state
- GSD writer → Trajectory file: writes frames