Add a current frame iterator for streamed trajectories

[PardhavMaradani]

Fixes #5183

Changes made in this Pull Request:

• Added a current frame iterator for streamed trajectories
  • The iterator is created when the frames array has a single value that is same as the current frame
  • This enables passing current frame to an analysis class run method as .run(frames=[u.trajectory.frame])
• Added a current frame access for streamed trajectories
  • This allows access like u.trajectory[u.trajectory.frame] to get current timestep
  • This enables analysis classes (like RMSD, AverageStructure) to use current frame as a ref_frame (in their __init__ method)
• Tests for all analysis classes that now work with streamed trajectories on a per-frame basis

This PR allows us to do something like the following:

import MDAnalysis as mda
from MDAnalysis.analysis.dssp import DSSP

top = "/tmp/imd-workshop-2025/workshop/sample_simulation/GROMACS/input/start.gro"
u = mda.Universe(top, "imd://localhost:8889")

dssp = DSSP(u)

for i in range(5):
    ts = u.trajectory.ts
    print(ts.data, ts.frame)
    run = dssp.run(frames=[ts.frame])
    print("".join(run.results.dssp[0]))
    u.trajectory.next()

Here is a sample output of the per-frame analysis above:

{'time': 41.54, 'dt': 0.002, 'step': 20770} 0
-E--HHHHHHHHH-----------HHHHHHHHHHH---E---EEE-----EEE----EE-----E-------------E---------HHHHHHHHHH----------HHHHHH------HHHH-----
{'time': 41.56, 'dt': 0.002, 'step': 20780} 1
-E--HHHHHHHHH-----------HHHHHHHHHHH---E---EEE-----EEE----EE-----E-------------E---------HHHHHHHHHH----------HHHHHH-------HHH-----
{'time': 41.58, 'dt': 0.002, 'step': 20790} 2
-E--HHHHHHHHH-----------HHHHHHHHHHHH--E---EEE-----EEE----EE-----E-------------E---------HHHHHHHHHH----------HHHHHH-------HHH-----
{'time': 41.6, 'dt': 0.002, 'step': 20800} 3
-E--HHHHHHHHH------HHHE-HHHHHHHHHHHH--E---EEE-----EEE----EE-----E-------------E---------HHHHHHHHHHHHH-------HHHHHH-------HHH-----
{'time': 41.62, 'dt': 0.002, 'step': 20810} 4
-E--HHHHHHHHH------HHHE-HHHHHHHHHHHH--E---EEE-----EEE----EE-----E-------------E---------HHHHHHHHHH----------HHHHHH------HHHH-----

LLM / AI generated code disclosure

LLMs or other AI-powered tools (beyond simple IDE use cases) were used in this contribution: no

PR Checklist

• Issue raised/referenced?
• Tests updated/added?
• Documentation updated/added?
• package/CHANGELOG file updated?
• Is your name in package/AUTHORS? (If it is not, add it!)
• LLM/AI disclosure was updated.

Developers Certificate of Origin

I certify that I can submit this code contribution as described in the Developer Certificate of Origin, under the MDAnalysis LICENSE.

---

📚 Documentation preview 📚: https://mdanalysis--5184.org.readthedocs.build/en/5184/

[github-actions]

Hello there first time contributor! Welcome to the MDAnalysis community! We ask that all contributors abide by our Code of Conduct and that first time contributors introduce themselves on GitHub Discussions so we can get to know you. You can learn more about participating here. Please also add yourself to package/AUTHORS as part of this PR.

[codecov]

Codecov Report

❌ Patch coverage is 96.15385% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.76%. Comparing base (9fb8b0a) to head (833875a).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
package/MDAnalysis/coordinates/base.py	95.65%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #5184      +/-   ##
===========================================
+ Coverage    92.72%   92.76%   +0.03%     
===========================================
  Files          180      180              
  Lines        22472    22495      +23     
  Branches      3188     3194       +6     
===========================================
+ Hits         20838    20867      +29     
+ Misses        1176     1174       -2     
+ Partials       458      454       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[BradyAJohnston]

This seems like a good idea to me - but I would defer to those more experienced with MDA & streaming as for why this approach maybe wasn't already taken.

[orbeckst]

I’m away from most of work (and open source) and won’t get to reviewing until the new year. But please let this not halt any discussions here!

[orbeckst]

I have high-level questions before diving into code and I am using issue #5183 for the discussion.