Frame Utils Utility
Frame and atom selection utilities for ReaxKit analyses.
This module provides common helpers for parsing flexible user input (e.g., CLI arguments or configuration strings) that specify frame and atom selections, and for resolving those selections into concrete, ordered indices usable by handlers and analyzers.
Typical use cases include:
- parsing frame ranges such as
"0:100:5"or explicit lists like"10,20,30" - selecting subsets of rows from DataFrames by frame index
- resolving iteration numbers into frame indices via handler metadata
- parsing atom index lists for per-atom analyses
parse_atoms(arg)
Parse an atom-index selection string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
arg
|
str or None
|
Comma- or space-separated atom indices. |
required |
Returns:
| Type | Description |
|---|---|
list[int] or None
|
Parsed atom indices, or |
parse_frames(arg)
Parse a frame-selection string into a slice or index list.
Supported formats are:
- "start:stop[:step]" → slice
- "i,j,k" → list of integers
- None or empty string → None (select all frames)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
arg
|
str or None
|
Frame selection string. |
required |
Returns:
| Type | Description |
|---|---|
slice or list[int] or None
|
Parsed frame selection. |
resolve_indices(handler, frames=None, iterations=None, step=None)
Resolve user-specified frame or iteration selections into frame indices.
Frame selection is resolved in the following order:
1. Explicit frame indices or slices (if provided)
2. Iteration numbers mapped to frame indices via handler.dataframe()['iter']
An optional stride may be applied to decimate the result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
handler
|
Handler providing access to per-frame simulation data. |
required | |
frames
|
slice or list[int]
|
Explicit frame selection. |
None
|
iterations
|
iterable of int
|
Iteration numbers to map to frame indices. |
None
|
step
|
int
|
Stride applied to the resolved frame indices. |
None
|
Returns:
| Type | Description |
|---|---|
list[int]
|
Ordered list of resolved frame indices. |
select_frames(df, frames)
Select rows from a DataFrame based on frame indices.
Selection is performed using row-position indexing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
Input DataFrame containing per-frame data. |
required |
frames
|
slice or list[int] or None
|
Frame selection returned by |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame restricted to the selected frames. |