ColPack

Hard-particle Monte Carlo packing simulations for colloidal systems, built on HOOMD-blue's HPMC integrator. ColPack orchestrates the full pipeline — problem setup, parameter sweep planning, simulation execution, and analysis — and exposes it both as a Python API and as an MCP tool surface for agent-driven workflows.

Installation

ColPack depends on HOOMD-blue and OVITO, which are not available on PyPI and must be installed from conda-forge. The recommended setup is a conda environment with those two packages, then pip install colpack on top:

conda create -n colpack python=3.11
conda activate colpack
conda install -c conda-forge hoomd ovito
pip install colpack

The remaining dependencies (numpy, gsd, freud-analysis, matplotlib, pydantic, mcp) are resolved automatically by pip.

Capabilities

Dimensions, shapes, and ensembles

Variations supported in a sweep

Across the dimension × shape × ensemble grid above, ColPack can express five kinds of variation. Any combination of these can be specified as a parameter sweep through the planner.

1. System volume fraction (NVT) — sweep volume_fraction. With fixed N and shape, compress the box to a series of target packing fractions to trace an equation-of-state isotherm at fixed composition.

2. Per-component relative volume fraction — sweep particle_specs.<i>.relative_volume_fraction. In a multi-component system this controls how the total volume budget is split across particle types. The first component is normalized to 1; values for other components set their volume share relative to it.

3. Per-shape geometric parameters — sweep any shape's intrinsic geometry, e.g. particle_specs.<i>.diameter (disk, sphere, capsule), particle_specs.<i>.length (capsule, rectangle), particle_specs.<i>.width (rectangle), particle_specs.<i>.a / b / c (ellipse, ellipsoid), particle_specs.<i>.side (triangle, square, cube, octahedron, tetrahedron). The full per-shape default set lives in colpack/colpack_config.json under dimensions.<d>.shape_parameters.

4. System pressure (NPT) — sweep P. With fixed N, the box volume fluctuates to reach a target pressure. Sweeping P traces the equation of state at the chosen shape and composition.

5. Mixtures — pass a multi-entry particle_shape_list at setup to build binary or higher-order mixtures in 2D or 3D. Variations 1–4 then apply on top of any per-component knob.

   HPMC compatibility constraint (inherited from HOOMD-blue):

   • In 2D, ellipse cannot be mixed with polygon/rod shapes (triangle, square, rectangle, capsule).
   • In 3D, ellipsoid cannot be mixed with polyhedron/rod shapes (cube, octahedron, tetrahedron, capsule).
   • disk (2D) and sphere (3D) promote to whichever integrator the rest of the mixture needs and are compatible with everything.

   The compatibility matrix and integrator-selection logic live in colpack/initialize.py (select_optimal_integrator).

Sweeps are submitted to plan_simulation_runs_tool via two arguments: baseline_parameters (fixed overrides on the setup) and tunable_parameters (parameter path → list of values). Both support nested dot-paths (e.g. particle_specs.0.diameter). Tunable entries expand one-parameter-at-a-time over the baseline rather than as a full Cartesian product.

Workflow pipeline

A simulation goes through four stages in order. Each stage has both a Python function in colpack/workflow.py and an MCP tool in colpack/mcp/server.py.

The capabilities tool get_colpack_capabilities_tool returns the live config (supported shapes, ensembles, key parameters, workflow steps) and is the recommended source of truth for agents.

Inside the Execute stage

Each run cycles through three sub-steps before analysis:

1. Initialize — generate a low-density configuration and init.gsd with the integrator and shape definitions selected automatically per shape.
2. Compress — drive the system from the initial dilute state to the target packing fraction (NVT) or pressure (NPT) via staged QuickCompress (NVT) or BoxMC updaters (NPT).
3. Sample — equilibrate and record a trajectory at the target state point. Auto-tunes HPMC trial-move sizes; for NPT also auto-tunes the BoxMC volume move.

Equilibrium is detected on the fly from a pointwise sigma gate over the sampled time series.

Analysis

ColPack drives freud for order-parameter and density analysis. Defaults are shape-aware, and additional parameters can be added per call.

Order parameters (per shape default)

Any of the following can be added via the extra_order_params argument:

Density analysis

System analysis

Outputs

Per working_dir:

• simulation_problem.json, simulation_baseline.json, simulation_plan.json
• run_*/init.gsd, compress.gsd, sample.gsd (HOOMD trajectory)
• run_*/order_params.json, rdf.json, plot images
• workflow_status.csv — one row per run, latest state per row
• workflow_progress.json, workflow_events.log — async progress for the agent / monitor CLI to consume

Programmatic use

from colpack.workflow import (
    setup_simulation_problem,
    plan_simulaiton_runs,         # note: legacy spelling preserved in the API
    execute_simulation_workflow,
    analyze_simulation_runs,
)

setup_simulation_problem(
    dimension=3,
    total_particle_number=500,
    particle_shape_list=["sphere"],
    ensemble="NVT",
)

setup_simulation_problem resolves and returns the canonical working_dir; pass that same value through to the planner, executor, and analyzer.

MCP server

The package ships an MCP server exposing the five workflow tools. Launch it with:

python -m colpack.mcp.server

The wrapper in agent/app.py connects to this server when the agent runs end-to-end workflows.

Configuration

colpack/colpack_config.json is the live config: allowed shapes per dimension, ensemble requirements, default integration / compression / sampling parameters, analysis catalog, and per-shape order-parameter defaults. The capabilities tool reads from this file, so editing it propagates to both the Python API and the agent.

Dependencies

Provided by conda-forge (system prerequisites, see Installation above):

• hoomd-blue (HPMC integrator)
• ovito (rendering / per-frame visualization)

Resolved automatically by pip:

• freud (analysis)
• gsd (trajectory I/O)
• pydantic, mcp, numpy, matplotlib