BaseSampler

class snap_simulate.hoomd.BaseSampler(file_name='sampler_state.pkl', sampling_mode='linear', min_interval=10, max_interval=None, Nmag=10, Navg=1, use_multiprocessing=False, auto_load=True)

Base class for autocorrelation samplers supporting logarithmic scheduling and background multiprocessing.

check(tail_window=10, threshold=0.01)

Check autocorrelation condition. Returns (minimized: bool, auto_value).

close()

Clean up background worker process.

get_next_sample_interval()

Calculates the next simulation step interval based on sampling_mode, Nmag, and Navg.

load_state(file_name=None)

Load sampler state from a pickle file if it exists.

sample(timestep, frame)

Sample data at a given timestep.

save_data(file_name='sampled_data.txt')

Save sampled data as a function of time/timestep.

save_state(file_name=None)

Save sampler state to a pickle file.

property steps_ran

Total simulation timesteps executed under this sampler.

The BaseSampler class is the base foundation for all autocorrelation samplers passed to minimize_autocorrelation().

Features

• Sample Scheduling: Supports both linear (fixed step intervals) and logarithmic (exponentially increasing intervals via sampling_mode="logarithmic") sampling schedules.

• Multiprocessing: Accepts use_multiprocessing=True to execute heavy autocorrelation calculations (such as FFTs or spatial particle correlations) in a detached background worker process, keeping the main HOOMD-blue integration loop running at full speed.

• State Persistence: Provides serialization methods (save_state() and load_state()) to save and restore sampling progress across workflow interruptions and stage boundaries.

• Data Export: Saves recorded time series and autocorrelation values to file via save_data().

Parameters

• file_name (str, default "sampler_state.pkl"): File path used for saving and loading sampler checkpoint states.

• sampling_mode (str, default "linear"): Sampling schedule mode, either "linear" (sample every min_interval steps) or "logarithmic" (sample at logarithmically spaced step intervals).

• min_interval (int, default 10): Minimum number of simulation timesteps between consecutive samples.

• max_interval (int, optional, default None): Maximum allowable timestep interval between samples when using logarithmic sampling.

• Nmag (int, default 10): Number of sample points per decade / order of magnitude in logarithmic sampling mode.

• Navg (int, default 1): Number of origin averages across the time series for decorrelation evaluations.

• use_multiprocessing (bool, default False): If True, offloads autocorrelation calculations to a background worker process so the main HOOMD-blue simulation loop runs unhindered.

• auto_load (bool, default True): If True and file_name exists on disk at initialization, automatically restores the previously saved sampler state.

Custom Sampler Subclasses

Custom physical quantities can be measured by subclassing BaseSampler and implementing:

• _internal_sample(timestep, payload): Records new physical data from the simulation state or snapshot.

• _internal_compute(tail_window, threshold): Evaluates autocorrelation on accumulated data and returns an (is_decorrelated, auto_values) tuple.

• _internal_save_data(file_name): Writes accumulated measurement data to disk.