shrink_box

snap_simulate.hoomd.shrink_box(sim, params=None, total_steps=None, updater_period=None, final_box_length=None, final_vol_frac=None, final_area_frac=None, final_aspect_ratio=None, molecules=None, particles=None, dimensions=None, hoomd_objs=None)[source]

Shrink the HOOMD simulation box to a target box length, volume fraction, or area fraction.

Accepts parameters either via a nested params dictionary/object or via direct kwargs.

This function drives dynamic box compression/shrinking. It supports two flexible calling patterns: passing a configuration dictionary (params) or passing direct keyword arguments.

Parameter Lookup Order

When params is provided, shrink settings are looked up in the following order:

  1. params[“box”][“shrink”] or params[“box”, “shrink”] (Checked first)

  2. params[“shrink”] (Top-level fallback)

Keyword Arguments

  • sim (hoomd.Simulation): The HOOMD-blue simulation instance to compress.

  • params (dict, optional): System configuration dictionary.

  • total_steps (int): Total simulation timesteps over which to compress the box (t_ramp).

  • updater_period (int | str | hoomd.trigger.Trigger, default 100): Frequency/period in timesteps for box resize updates.

  • final_box_length (float | list[float], optional): Explicit target box dimensions (e.g. [10.0, 10.0, 10.0] or scalar 10.0).

  • final_vol_frac (float, optional): Target 3D volume fraction to compress to.

  • final_area_frac (float, optional): Target 2D area fraction to compress to.

  • final_aspect_ratio (list[float], optional): Target aspect ratio for 2D/3D boxes.

  • molecules (dict, optional): Molecules specification dictionary (required when computing box length from volume/area fraction).

  • particles (dict, optional): Particles specification dictionary (required when computing box length from volume/area fraction).

  • dimensions (int, default 3): Spatial dimensions (2 or 3).

  • hoomd_objs (dict, optional): HOOMD object registry containing custom triggers.

Usage Examples

Direct Keyword Arguments:

from snap_simulate.hoomd import shrink_box

# Compress to explicit target box dimensions over 50,000 steps
shrink_box(sim, total_steps=50000, updater_period=100, final_box_length=[10.0, 10.0, 10.0])

Configuration Dictionary:

from snap_simulate.hoomd import shrink_box

# Compress using system configuration dictionary
shrink_box(sim, sys_params)