GSoC 2026: Week 7 & 8

GSoC 2026: Week 7 & 8 - All about Auxdata

The bridge between WESTPA and MDAnalysis became a lot stronger in these weeks. Users now have the ability to import auxdata from their WESTPA simulations into their converted MDAnalysis Universe as metadata, use it for analysis and save their analysis results back into their source west.h5 file as auxdata. This creates a powerful closed-loop workflow which allows users to efficiently trasmit data between the two tools. Researchers can completely bypass the need for messy intermediate text files or fragile post-processing scripts. This keeps the simulation ecosystem perfectly organized, ensuring that raw trajectory segments and their computed properties remain strictly cartegorized by iteration and walker ID.
This closed-loop workflow is divided into two parts:

Reading simulation auxdata into the Universe:

When you load a universe, the WESTPAReader processes the simulation frame by frame. For every single frame it reads, it runs this snippet

if 'auxdata' in iter_group:
    for aux_name, aux_dataset in iter_group['auxdata'].items():
        aux_len = aux_dataset.shape[1]

        if local_frame < aux_len:
            self.ts.data[aux_name] = aux_dataset[seg_idx, local_frame]

It is pretty straightforward. If any auxdata exists in the directory, it safely loads it into ts.data. The ts.data dictionary is a native MDAnalysis feature designed specifically to carry arbitrary properties alongside standard coordinates. This lets users to easily access the auxdata as required.

Saving anaylsis results as auxdata back into west.h5

When you run an analysis tool like rms.RMSD, MDAnalysis returns a flat, 1D array of results. The saving function’s job is to “un-flatten” that list and safely pack it back into the WESTPA HDF5 grid. This works in three phases:

Mapping

To figure out where a flat result belongs in the HDF5 hierarchy, the code uses the Universe’s frame_index.

data_map = {}
    for i, frame_info in enumerate(universe.trajectory.frame_index):
        iter_num, seg_idx, actual_pos, path, frame_within_seg = frame_info
        
        # Build nested dictionaries dynamically
        if iter_num not in data_map: data_map[iter_num] = {}
        if seg_idx not in data_map[iter_num]: data_map[iter_num][seg_idx] = {}
            
        data_map[iter_num][seg_idx][frame_within_seg] = results[i]

This matches the index of the result (i) with the trajectory metadata (frame_index[i]). It then builds a massive nested dictionary and completely reconstructs the branching tree logic of WESTPA.

Validation

if 'auxdata' in iter_group and dataset_name in iter_group['auxdata']:
    if not overwrite:
        raise RuntimeError(...)

This scans the HDF5 file based on the planned writes in data_map. If the dataset already exists and you didn’t pass overwrite=True, it intentionally crashes before any writing begins. This prevents “partial writes” where half your file gets updated before an error occurs.

Writing

Finally, the code loops through the data_map to build the physical datasets.

# 1. Size the array perfectly for WESTPA
chunk_shape = (n_segments, pcoord_len) + result_shape
iter_array = np.zeros(chunk_shape, dtype=result_dtype)

# 2. Populate the grid
for seg_idx, frames in segs.items():
    for frame_within_seg, val in frames.items():
        iter_array[seg_idx, frame_within_seg] = val
        
# 3. Save to disk
aux_group.create_dataset(dataset_name, data=iter_array)

This asks the HDF5 file how many segments exist in the iteration and creates an empty grid of zeros. It loops through the data_map and slots the values directly into the correct grid coordinates and then pushes the completed grid into the HDF5 file using create_dataset.

With this in place, it instantly unlocks compatibility with the broader WESTPA ecosystem; the moment the analysis is saved, native visualization and analysis tools like w_pdist , plothist , and wedap can immediately read the new auxdata to plot probability distributions, pcoords, etc. The next part of this project is a CLI tool which will allow users working from the terminal to use all these new tools easily.

Summary

  • Read simulation auxdata from west.h5 and imported it into the Universe
  • Allowed exporting of analysis results as auxdata back into west.h5
  • Created a test case for this loop.