Path

aimmd.Path is a lightweight, segment-aware reference to one or more on-disk trajectory files. Heavy data (states, descriptors, committor values) is loaded lazily and cached beside the trajectory as .npy files.

class aimmd.Path(fnames=[], start=None, stop=None, remove_overlapping_frames=False, pipeline=(), weight=1.0, exclude_from=-1, shooting_index=0)

Bases: PathHelpers, PathMagic, PathProperties, PathMethods, PathExtract, PathGet, PathPositions, PathCompute, PathIO

Trajectory-backed path object with segment-aware frame indexing.

A Path represents a sequence of frames assembled from one or more (possibly not contiguous) trajectory segments on disk. It is the basic unit manipulated by AIMMD path sampling:

• workers incrementally extend it while a simulation is running,

• shooting tasks slice and concatenate it to assemble new paths,

• analysis tasks compute and cache per-frame series (states, descriptors, values) aligned with the path frames.

Storage model A Path stores an ordered list of trajectory segments:

• _fnames : list[str] One filename per segment (trajectory file path).

• _first / _last : list[int] Per-segment local frame bounds (inclusive). A segment may be forward (first <= last) or backward (first > last).

The global path frame index space is the concatenation of per-segment intervals in the order stored in _fnames. Most operations treat the path as a linear sequence of frames, hiding the segment structure from callers.

Caching and derived series Per-frame quantities associated with a path (e.g., states, descriptors, values) are commonly cached in .npy files derived from the trajectory filename. These cached arrays are assumed to be aligned with trajectory frames and are subset/concatenated according to the path’s segment slices.

In AIMMD, trajectory readers are obtained through a global MDAnalysis reader cache (aimmd._config.MDA_CACHE). Methods that mutate the underlying trajectory files should evict affected entries from that cache.

Key operations and semantics

• Slicing returns a new Path describing the corresponding subsequence of frames, preserving segment semantics and direction.

• Concatenation (p + q) returns a new Path that is the frame-wise concatenation of the two paths (typically used to join backward and forward segments in shooting).

• extend() mutates the path by appending frames discovered on disk, and is the core primitive used while a simulation is running.

• write() exports the frames represented by the path into a new trajectory file.

:param The constructor is aliased to PathHelpers._init(). See that method: :param for the full signature and meaning of path initialization arguments.:

Notes

• Many AIMMD workflows assume that extension operates on forward segments only (monotonic frame growth within each segment). Backward segments may exist as a representation (e.g., reversed slices) but are typically not extended in place.

• The path object is intentionally lightweight: it stores indexing metadata and filenames, while heavy data access is delegated to cached readers and computed arrays.

Initialize a Path instance.

This method is used as the concrete Path.__init__ via aliasing. It supports initializing from filenames/patterns or by copying/slicing an existing Path.

Parameters:

fnames – Either (i) a filename/pattern, or an iterable of them, or (ii) an

existing Path instance to copy/slice. :type fnames: str or pathlib.Path or Iterable or aimmd.path.Path, optional :param start: Global start index for slicing when initializing from another Path, or for skipping initial frames when initializing from files. :type start: int or None, optional :param stop: Global stop index for slicing, or maximum number of frames. :type stop: int or None, optional :param remove_overlapping_frames: If True, attempt to remove overlap between consecutive files based on time stamps when extending. :type remove_overlapping_frames: bool, optional :param pipeline: Optional compute pipeline. Each element is an argument tuple passed as path.compute(*args) after initialization. :type pipeline: tuple, optional :param weight: Statistical weight of this path. :type weight: float, optional :param exclude_from: If >= 0, mark the path as rejected from this frame onward. :type exclude_from: int, optional :param shooting_index: Shooting point index in global Path coordinates. If not an integer, the property setter “finds” it (frame with time = 0 or first frame). :type shooting_index: int or any, optional

Notes

• exclude_from affects the public states view (frames after it may be treated as invalid) but does not physically truncate the Path.

property accepted

Whether the path is accepted (exclude_from < 0).

all(attribute)

Return the full attribute array over the entire path.

Parameters:

attribute (str) – Attribute name to retrieve.

Returns:

The complete attribute as returned by self._get(attribute).

In most cases this is a NumPy array of length len(self). :rtype: object

backward(attribute)

Return an attribute restricted to the “backward” range.

Parameters:

attribute (str) – Attribute name to retrieve.

Returns:

The attribute slice corresponding to self._range('backward').

Return type:

object

check_stop(allowed_states='', max_length=inf, check_first_frame=True)

Determine whether growth should stop by scanning the state sequence.

Parameters:

allowed_states – Allowed one-letter state labels. If empty or 'all', no restriction is

enforced. If non-empty and check_first_frame=True, the first frame must be in allowed_states or a RuntimeError is raised. :type allowed_states: str, default=’’ :param max_length: Maximum allowed length (in frames) of a contiguous block as returned by aimmd.path.utils.split(). :type max_length: int | float, default=math.inf :param check_first_frame: Whether to enforce that the first frame is in allowed_states when allowed_states is provided. :type check_first_frame: bool, default=True

Returns:

• stop_index (int | None) – Global frame index (0-based) where the violating block begins, or None if

no stop condition is met.

• nframes (int) – Number of usable frames after trimming trailing empty state labels.

• last_state (str) – A state label associated with the detected condition (or the final observed

state if no condition is met).

• block_length (int) – Length in frames of the relevant contiguous block.

Notes

This method temporarily disables _exclude_from to query the full states array, then restores the original value.

compute(function=<function PathCompute.<lambda>>, target='', source='reader', conditions={}, overwrite=False, mtime=None, batch_size=4096, return_result=False, raise_if_error=False, verbose=False, worker=None, system_id=None)

Compute a time series on this Path, optionally caching the results.

Parameters:

function – Computation function. Its expected calling convention depends on

source:

• If source == ‘reader’, compute_batch will feed a reader slice

(or timesteps) and function typically iterates over timesteps.

• Otherwise, function is applied to numpy-like batches of the

extracted source series. If function is None, no computation is performed and the method returns either None (if returning results) or 0 (if only updating). :type function: callable or None, optional :param target: Name of the cache target series to write.

• If non-empty: results are written to a .npy cache file per input

trajectory file.

• If empty: nothing is written and results are returned.

Parameters:

source – Input series name used to generate inputs for function.

Common values: ‘reader’, ‘frames’, ‘positions’, ‘coordinates’, ‘velocities’, ‘times’, ‘dimensions’, or the name of an existing cached attribute. :type source: str, optional :param conditions: Mapping {reference_name: predicate}. For each file-segment k, the method attempts to load reference_name via _extract(k, …) and applies predicate(…) to obtain a boolean mask. Masks are multiplied together. :type conditions: dict, optional :param overwrite: If False (default), try to skip frames already present in the target cache file (if it exists and is recent enough). :type overwrite: bool, optional :param mtime: If provided, cached target files with modification time >= mtime are considered valid for skipping. At the end, the method sets the mtime of all touched target cache files to this value (via os.utime). :type mtime: float or None, optional :param batch_size: Maximum number of frames passed to compute_batch at once. Controls memory usage and amortizes Python overhead. :type batch_size: int, optional :param return_result: If True, return computed values as a numpy array. If False, return the number of computed frames (or another scalar summary returned by compute_batch). This is forced to True if target is empty. :type return_result: bool, optional :param raise_if_error: If True, propagate errors encountered when extracting condition references or sources. If False, missing references simply do not affect the mask (conditions are best-effort). :type raise_if_error: bool, optional :param verbose: If True, show a tqdm progress bar indicating how many frames are processed/skipped/computed. :type verbose: bool, optional :param worker: Optional worker/controller object. If it has a truthy attribute termination_signal, the method returns early. :type worker: object, optional

Returns:

• If return_result is True: numpy array of computed results

(concatenated over all files and selected frames).

• Otherwise: integer-like count accumulated from compute_batch.

Return type:

numpy.ndarray or int

Notes

• This method operates per underlying trajectory file (self._fnames), applying per-file masks and updating per-file cache targets.

• When target is provided, this method removes the relevant entry from NPY_CACHE before writing to ensure subsequent reads see updates.

copy()

Return a shallow copy of the Path.

Returns:

New Path instance with duplicated segment lists and copied cached arrays.

Return type:

aimmd.path.Path

Notes

This method copies values stored in self.__dict__ starting after the standard internal fields, using value.copy().

property dt

Estimate time step between frames.

Notes

• If times are in memory, uses the first two times.

• Otherwise uses middle(‘times’) - initial(‘times’).

property exclude_from

Rejection marker.

Returns:

If < 0, the path is accepted.

If >= 0, frames at/after this index are considered invalid/rejected. :rtype: int

extend(fnames, nframes=inf, skip=0, remove_overlapping_frames=True, pipeline=())

Extend the current Path by appending frames available on disk.

This method is designed for incrementally growing trajectories that may be written concurrently. It tries to append up to nframes new frames by:

1. optionally extending the Path’s current last segment (same filename), then

2. appending additional trajectory files from fnames as new segments.

Crucially, step (A) only happens when both of the following are true:

• after normalization, skip == 0 (see the skip parameter semantics), and

• the Path is non-empty and its last filename self._fnames[-1] appears in the expanded filename list derived from fnames.

Parameters:

fnames – One or more trajectory filenames and/or glob patterns. Expansion and ordering

are handled by aimmd.path.utils.get_fnames().

The expanded list is the authoritative sequence of candidate files. If the expanded list is empty, the method returns (0, 0) and does not modify the Path.

If the expanded list includes the current last segment file, that file is consumed by the “extend last segment” step and removed from the list of files to append afterwards. :type fnames: str | pathlib.Path | Sequence[str | pathlib.Path] | None :param nframes: Maximum number of frames to append in total. Internally treated as a remaining budget frames_to_add. If nframes is 0 or falsy, the method returns (0, 0). :type nframes: int | float, default=math.inf :param skip: Skip count applied before appending new frames.

Semantics in this implementation:

1) skip is normalized via: - skip = 0 if skip is None, - otherwise skip = max(int(skip), 0). 2) Then it is converted to “extra skip beyond the current Path length” via:

skip = max(skip - start, 0), where start = len(self) before any changes.

Consequences:

• If skip < len(self), then the effective skip becomes 0 (it does not

skip within existing frames).

• If skip > len(self), the extra skip is applied to the first new input file(s)

by advancing the local starting index for those files. :type skip: int | None, default=0 :param remove_overlapping_frames: If True and a time reference from the previous appended frame is available, attempt to remove overlap between the last appended segment and the next segment.

Important: this implementation may remove multiple frames from the end of the previously appended segment by repeatedly decrementing self._last[-1] until t1 < t0, where:

• t1 is the time of the last frame currently in the Path (rounded to 3 decimals),

• t0 is the time of the first candidate frame in the next file at local index

skip (also rounded to 3 decimals),

• dt is taken from aimmd.path.utils.get_last_time_and_dt() on the previous

reader.

Each rewind increases frames_to_add by 1 (to keep the total append budget consistent). If the rewind affected the original last segment that existed before calling this method, start is decremented so the pipeline recomputes one extra frame. :type remove_overlapping_frames: bool, default=True :param pipeline: Optional post-processing pipeline applied after extension.

If non-empty, the code constructs:

• path = self[start:] if start is non-zero,

• otherwise path = self.

Then for each element args in pipeline, it executes: path.compute(*args).

Therefore each pipeline element must be a tuple of positional arguments compatible with Path.compute. The pipeline is executed regardless of whether frames were added (the code checks only whether pipeline is truthy), but the slice self[start:] may be empty. :type pipeline: Iterable[tuple] | tuple, default=()

Returns:

• added_frames (int) – Total number of frames appended across all updated/appended segments.

• frames_left (int) – Remaining frames available in the last reader touched after extension:

• For the last file processed, frames_left is computed as

len(reader) - end_index (or len(reader) - skip - delta in the new-file loop).

• When the method stops because frames_to_add <= 0 inside the new-file loop,

it sets frames_left = -1 as a sentinel meaning “unknown (next file)”.

Raises:

• RuntimeError – If the method attempts to extend the current last segment but the segment is running backwards, detected by self._first[-1] >= self._last[-1] + 1.

• Side effects –

• ------------ –

• - Mutates self._fnames, self._first, self._last. –

• - May shorten the last segment (overlap rewind). –

• - Special case – if MDA_CACHE.get(fname, min_length) returns None when trying to: extend the current last file, the method removes that last segment entirely and returns early with (added_frames, -1).

Notes

• The method assumes that “continuing” a file means appending local indices starting at self._last[-1] + 1.

• All time comparisons used for overlap removal are rounded to 3 decimals.

• Several operations are wrapped in broad try/except blocks to tolerate transient I/O failures during concurrent writes.

property filenames

Per-frame filename array aligned with locs.

final(attribute)

Return an attribute at the final (last) frame.

Parameters:

attribute (str) – Attribute name to retrieve (see initial()).

Returns:

The value of attribute at global index -1.

Return type:

object

find_shooting_index()

Return the frame index corresponding to the shooting point.

The shooting point is inferred purely from the trajectory time stamps. In AIMMD paths, frames before the shooting point are typically stored in reverse time order, while frames after the shooting point are stored in forward time order. This means that the sign of the time increment between the first two frames tells us whether the path starts by moving forward or backward away from the shooting point:

• dt >= 0: the trajectory already starts at the shooting point, so the shooting index is 0.

• dt < 0: the first frames belong to the backward branch, so the shooting point lies later in the path and can be reconstructed from the time grid.

The method assumes that the trajectory times are approximately equally spaced around the shooting point and that the shooting frame corresponds to time zero.

Returns:

Index of the shooting frame.

Return type:

int

Notes

The computation uses times rounded to 6 decimal places to suppress tiny floating-point noise from trajectory readers.

For paths with fewer than two frames, the only sensible answer is 0.

property first

Per-file first frame index (absolute index within each file).

property fname

Last (“active”) trajectory filename, or ‘’ for an empty Path.

property fnames

Per-file trajectory filenames composing this Path.

forward(attribute)

Return an attribute restricted to the “forward” range.

Parameters:

attribute (str) – Attribute name to retrieve.

Returns:

The attribute slice corresponding to self._range('forward').

Return type:

object

from_files()

Drop cached in-memory arrays and revert to file-backed reading.

Returns:

The same Path instance, mutated in-place.

Return type:

self

get(attribute, start=0, stop=None, step=None, raise_if_missing=False)

Retrieve a Path attribute over a global slice.

Parameters:

attribute – Name of the series to retrieve. Common values include:

• ‘indices’ : return global indices (0..len(path)-1)

• ‘reader’ : reader slice (single reader or ChainReader)

• ‘frames’ : list of Timestep copies

• ‘states’ : cached states array if present, otherwise extracted

• ‘true_states’ : alias for ‘states’ that bypasses exclusion masking

• ‘positions’, ‘coordinates’, ‘velocities’, ‘times’, ‘dimensions’

(resolved via _extract when not cached)

• any name stored in self.__dict__ as a cached array

Parameters:

start – Slice bounds expressed in the global Path index space.

They are normalized via slice(start, stop, step).indices(len(self)). :type start: int or None, optional :param stop: Slice bounds expressed in the global Path index space. They are normalized via slice(start, stop, step).indices(len(self)). :type stop: int or None, optional :param step: Slice bounds expressed in the global Path index space. They are normalized via slice(start, stop, step).indices(len(self)). :type step: int or None, optional :param raise_if_missing: If True, _extract is asked to raise when a requested series is not available on disk. If False, missing series may be replaced with default arrays depending on _extract behavior. :type raise_if_missing: bool, optional

Returns:

Depending on attribute:

• numpy.ndarray (most attributes)

• list of timesteps for ‘frames’

• reader-like object for ‘reader’

Return type:

object

Notes

• If the Path is empty (start == stop), returns empty containers with appropriate dtype for ‘states’.

• If attribute == ‘states’ and self._exclude_from >= 0, states from exclude_from onward are replaced with ‘’ (empty string).

• For in-memory mode (self.in_memory()), requesting ‘reader’/’frames’ constructs a MemoryReader from cached arrays.

in_memory(attribute=None)

Return whether cached in-memory arrays are present.

Parameters:

attribute

• If None (or one of 'self', 'reader', 'frames'): check for the

full in-memory representation (times/positions/velocities/dimensions).

• Otherwise: check whether that attribute key exists in self.__dict__.

Return type:

bool

property indices

Global Path indices (0..len(self)-1).

initial(attribute)

Return an attribute at the initial (first) frame.

Parameters:

attribute – Name of the attribute to retrieve. Typical values are

'positions', 'velocities', 'dimensions', 'times', 'states', 'values', or any other key supported by the Path getter logic. :type attribute: str

Returns:

The value of attribute at global index 0.

Return type:

object

Notes

This is equivalent to self._position(0, attribute).

internal(attribute)

Return an attribute restricted to the “internal” range.

Parameters:

attribute (str) – Attribute name to retrieve.

Returns:

The attribute slice corresponding to self._range('internal').

Return type:

object

is_complete(target_state='R', states='ARB')

Return whether the path is complete with respect to a target state.

Parameters:

target_state – Target one-letter state label to test for. The label is normalized by

aimmd.core.utils.process_state() using the states alphabet. :type target_state: str, default=’R’ :param states: Three-character alphabet defining (initial, middle/reactive, final) state labels. :type states: str, default=’ARB’

Returns:

True if self.type indicates that the target state has been reached in

an allowed/complete pattern, otherwise False. :rtype: bool

is_excursion(states='ARB')

Return True if the path leaves an end state and visits the middle state.

Parameters:

states (str, default='ARB') – Three-character alphabet defining the end states and middle state.

Returns:

True if the initial state is an end state (A or B) and the middle state is

the reactive/middle label (R). :rtype: bool

is_internal(states='ARB')

Return True if the path is classified as internal by its middle state.

Parameters:

states (str, default='ARB') – Three-character alphabet defining the end states and middle state.

Returns:

True if self.middle('states') is one of the end-state labels.

Return type:

bool

is_transition(states='ARB')

Return True if the path is a direct A<->B transition.

Parameters:

states (str, default='ARB') – Three-character alphabet defining the two end states and the middle state.

Returns:

True if self.type[:3] equals states or its reverse.

Return type:

bool

property last

Per-file last frame index (absolute index within each file).

property lengths

Per-file segment lengths (number of frames in each file segment).

property locs

Absolute file-local locations corresponding to each Path frame.

Returns:

Concatenation of per-file range(first, last+step, step).

Return type:

numpy.ndarray

max(attribute, source='values')

Return attribute at the location where source is maximal.

Parameters:

• attribute (str) – Attribute to return at the extremum location.

• source (str, default='values') – Attribute used to locate the maximum.

Returns:

The value of attribute at the argmax location of source within

the internal segment. :rtype: object

Notes

Delegates to: self._extreme(attribute, np.argmax, 'internal', source).

max_backward(attribute, source='values')

Return attribute at the location where source is maximal in backward range.

Parameters:

• attribute (str) – Attribute to return at the extremum location.

• source (str, default='values') – Attribute used to locate the maximum.

Returns:

The value of attribute at the argmax location of source within

the backward segment. :rtype: object

max_forward(attribute, source='values')

Return attribute at the location where source is maximal in forward range.

Parameters:

• attribute (str) – Attribute to return at the extremum location.

• source (str, default='values') – Attribute used to locate the maximum.

Returns:

The value of attribute at the argmax location of source within

the forward segment. :rtype: object

middle(attribute)

Return an attribute at the middle frame.

Parameters:

attribute – Attribute name to retrieve.

Special case:

• if attribute == 'indices', this method returns the integer global

index chosen as “middle” by the Path (see Notes). :type attribute: str

Returns:

• If attribute == 'indices': an int global index.

• Otherwise: the value of attribute at that middle index.

Return type:

object

Notes

The “middle index” used by this code is not len(self)//2. The implementation is:

min(len(self), 1)

This returns:

• 0 for an empty path (though this method is typically not called then),

• 1 for any non-empty path of length >= 1.

This behavior is inherited from the existing code and should be treated as an API contract for this package version.

min(attribute, source='values')

Return attribute at the location where source is minimal.

Parameters:

attribute – Attribute to return at the extremum location (e.g. 'positions',

'times', 'states', 'indices'). :type attribute: str :param source: Attribute whose numeric values are used to locate the minimum. This is commonly 'values' (e.g. a collective variable) but may be any Path attribute understood by the underlying _extreme implementation. :type source: str, default=’values’

Returns:

The value of attribute evaluated at the frame index (within the

internal segment) where source attains its minimum. :rtype: object

Notes

• The minimum is computed over the internal range only.

• This method does not return the minimum value of source; it returns attribute at the argmin of source.

• Delegates to: self._extreme(attribute, np.argmin, 'internal', source).

min_backward(attribute, source='values')

Return attribute at the location where source is minimal in backward range.

Parameters:

• attribute (str) – Attribute to return at the extremum location.

• source (str, default='values') – Attribute used to locate the minimum.

Returns:

The value of attribute at the argmin location of source within

the backward segment. :rtype: object

Notes

Delegates to: self._extreme(attribute, np.argmin, 'backward', source).

min_forward(attribute, source='values')

Return attribute at the location where source is minimal in forward range.

Parameters:

• attribute (str) – Attribute to return at the extremum location.

• source (str, default='values') – Attribute used to locate the minimum.

Returns:

The value of attribute at the argmin location of source within

the forward segment. :rtype: object

property n_atoms

Number of atoms per frame, inferred from the first trajectory file.

property n_files

Number of underlying trajectory files contributing to the Path.

property n_frames

Number of internal frames.

property offsets

Cumulative sum of lengths, used for global→local index mapping.

partial(attribute='self', key=None)

Extract one or more file segments from the Path.

Parameters:

attribute – What to extract from each selected segment. The special value 'self'

returns a Path object; other values are delegated to the private extraction helper _extract. :type attribute: str, default=’self’ :param key: Segment selector over file indices (0..``self.n_files-1``). If not an integer, the selection is expanded via np.arange(self.n_files)[key] and a list is returned. :type key: int | slice | numpy.ndarray | None, default=None

Returns:

Extracted object(s) for the selected segment(s).

Return type:

object | list[object]

sample(n_samples, source='values', vmin=None, vmax=None)

Randomly sample internal frames and return them as a new single-frame-segment Path.

Parameters:

n_samples – Number of frames to sample. If 0 or the Path is empty, an empty Path is

returned. :type n_samples: int :param source: :type source: limit to source vmin to vmax

Returns:

A new Path with n_samples segments, each containing exactly one frame.

Return type:

aimmd.path.Path

shooting(attribute)

Return an attribute at the shooting frame.

Parameters:

attribute (str) – Attribute name to retrieve.

Returns:

The value of attribute at global index self._shooting_index.

Return type:

object

property shooting_index

Index of the shooting point in global Path coordinates.

shooting_result(states='ARB')

Return a 2-element outcome count derived from the 3-letter path type.

Parameters:

states (str, default='ARB') – Three-character alphabet defining (A, R, B).

Returns:

Array of shape (2,) with counts for reaching A (index 0) and B (index 1),

conditional on the middle letter being R. :rtype: numpy.ndarray

split(return_start_stop=False, states=None)

Split the path into contiguous blocks of non-empty state labels.

Parameters:

• return_start_stop (bool, default=False) – Currently unused (kept for API compatibility).

• states – Optional external state array. If not provided, the method attempts to use

self.states; on failure it uses an array of empty labels. :type states: numpy.ndarray | Sequence[str] | None, default=None

Returns:

Ensemble whose paths are slices corresponding to blocks returned by

aimmd.path.utils.split(). :rtype: aimmd.pathensemble.PathEnsemble

to_memory()

Cache the full trajectory in memory on this Path.

Returns:

The same Path instance, mutated in-place. After completion, the Path has

cached arrays: positions, velocities, dimensions, and times. :rtype: self

Notes

• Missing velocities are replaced by zeros.

• Missing box dimensions are replaced by DEFAULT_DIMENSIONS.

property type

Compact 4-character summary of the path.

Convention Returns a string of length 4 representing:

• initial state label,

• “middle” state label,

• final state label,

• shooting state label.

Rejected/empty paths return ‘….’.

update_exclude_from(log_fname)

Update _exclude_from by parsing an external log file.

Parameters:

log_fname – Log file path. The method scans whitespace-separated tokens per line. If the

basename of token 0 matches self.fname, token 1 (if present) is parsed as an integer exclude-from index; otherwise exclude-from is set to 0. :type log_fname: str | pathlib.Path

Return type:

None

property weight

Statistical weight associated with this Path.

write(filename, key=None, atoms=None, t0=None, overwrite=False, return_writer=False)

Write frames from the Path to a trajectory file.

Frames are written through an MDAnalysis Writer. The source is either:

• file-backed: self.reader if the required arrays are not fully in memory, or

• in-memory: the cached arrays stored on the Path (times, positions, velocities, dimensions).

Parameters:

filename – Output trajectory filename. The output format is inferred by MDAnalysis from

the file extension. :type filename: str | pathlib.Path :param key: Frame selector in global Path indexing. Internally converted by np.arange(len(self))[key] and flattened. If None, all frames are written. :type key: int | slice | numpy.ndarray | None, default=None :param atoms: Atom selector applied as np.arange(self.n_atoms)[atoms] and flattened. If None, all atoms are written. :type atoms: int | slice | numpy.ndarray | None, default=None :param t0: Optional time origin override. If provided, the written time is set to t0 + dt * i where i is the write counter (0..n_frames-1) and dt is inferred from the first two selected frames (or set to 1.0 for a single frame). If None, uses the times from the source frames. :type t0: float | None, default=None :param overwrite: If False, refuse to overwrite an existing file. :type overwrite: bool, default=False :param return_writer: If True, return the writer object (left open). If False, close it and return the list of written times. :type return_writer: bool, default=False

Returns:

writer_or_times –

• If return_writer=True: the MDAnalysis writer instance.

• Otherwise: a list of times corresponding to the written frames.

Return type:

MDAnalysis Writer | list[float]

Raises:

• TypeError – If overwrite is False and filename already exists.

• RuntimeError – If the selection yields no frames.

Notes

• A temporary in-memory universe is created via Universe.empty(n_atoms, trajectory=True).

• If a source frame has not dimensions, aimmd._config.DEFAULT_DIMENSIONS is written.