Skip to content

Add option to evaluate only reference contact pairs - #5515

Merged
orbeckst merged 10 commits into
MDAnalysis:developfrom
carlosvega:contacts-pairs-option
Nov 13, 2026
Merged

orbeckst merged 10 commits into
MDAnalysis:developfrom
carlosvega:contacts-pairs-option

Conversation

@carlosvega

@carlosvega carlosvega commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #5517

Changes made in this Pull Request:

Contacts builds the full distance matrix of the two selections on every frame and then keeps only the entries that were in contact in the reference. When the native contacts are a tiny fraction of all pairs (for example all protein heavy atoms), nearly all of that work gets thrown away.

This PR adds an opt-in compute_pairs_only=False keyword. With compute_pairs_only=True, the contact indices and reference distances are worked out once per run, and each frame calls calc_bonds on just those pairs, using the same box and the same method. The default code path is untouched, and the results match the default (compared at rtol=1e-12 in the tests and in the benchmark below).

In short, instead of computing every distance and discarding most, we remember once which pairs matter and compute only those.

Benchmark. 15 cases on 7 systems (macOS ARM64, serial, OMP_NUM_THREADS=1, median of 3–5 alternating runs, Contacts.run() only). "Density" is the share of all N×N atom pairs that are reference contacts. "init+run" also counts building the Contacts object, whose dense reference setup is unchanged. "Memory" is the peak memory allocated during run() (tracemalloc).

System Selection Atoms Frames Density compute_pairs_only=False compute_pairs_only=True Speedup (run) Speedup (init+run) Memory in run(), MiB (compute_pairs_only=False / True)
AdK equilibrium first 64 heavy atoms, radius 1000 Å (every pair is a contact) 64 256 100% 0.021 s 0.041 s 0.52× (slower) 0.52× 0.2 / 0.3
AdK equilibrium salt bridge (Asp/Glu vs Arg/Lys) 70 256 1.1% 0.015 s 0.014 s 1.1× 1.1× 0.2 / 0.2
AdK equilibrium CA, 8 Å 214 256 4.6% 0.039 s 0.027 s 1.5× 1.5× 0.5 / 0.2
Small protein, test files (TPR/TRR) heavy atoms 480 3 3.3% 0.021 s 0.020 s 1.05× 1.05× 2.0 / 0.4
I-FABP heavy atoms 1057 256 1.5% 0.448 s 0.135 s 3.3× 3.3× 9.2 / 1.1
AdK, test files (PSF/DCD) heavy atoms 1656 98 1.0% 0.521 s 0.084 s 6.2× 6.0× 21.8 / 1.7
AdK in water, test files (TPR/XTC) heavy atoms 1656 10 1.0% 0.641 s 0.037 s 17.4× 7.1× 21.8 / 1.6
AdK equilibrium heavy atoms 1656 256 1.0% 1.655 s 0.202 s 8.2× 8.0× 21.8 / 1.6
AdK equilibrium heavy atoms, 8 Å cutoff 1656×1656 32 4.4% 0.249 s 0.115 s 2.17× 2.10× 24.7 / 7.0
AdK equilibrium heavy atoms, 12 Å cutoff 1656×1656 32 12% 0.347 s 0.337 s 1.03× 1.03× 31.1 / 19.0
AdK equilibrium heavy atoms, 20 Å cutoff 1656×1656 32 39% 0.520 s 0.998 s 0.52× 0.52× 53.4 / 60.9
Membrane protein, test files (GRO_MEMPROT) heavy atoms 4372 5 0.4% 2.120 s 0.082 s 25.9× 5.1× 148.1 / 4.4
NhaA heavy atoms 5622 64 0.3% 4.944 s 0.360 s 13.7× 11.2× 244.1 / 5.7
Membrane protein, test files (GRO_MEMPROT) all heavy atoms incl. lipids 18062 5 0.08% 37.265 s 0.894 s 41.7× 5.1× 2496.6 / 14.7
NhaA lipid heavy atoms vs protein heavy atoms 19266×5622 16 0.0039% 3.866 s 0.299 s 12.92× 7.23× 826.7 / 0.5

So it helps a lot when the contacts are sparse and the selection is large, is neutral for small selections, and is slower when almost every pair is a contact. That is why it is opt-in rather than the default. The Asp/Glu–Arg/Lys case is also a small selection, so it doesn't gain much either.

Test: pytest testsuite/MDAnalysisTests/analysis/test_contacts.py. The existing tests are parametrized over compute_pairs_only and run with both False and True for hard/soft/radius cut, with and without PBC (serial and multiprocessing backends), and with a custom method. New tests cover several overlapping references and rerunning after editing the mask.

LLM / AI generated code disclosure

LLMs or other AI-powered tools (beyond simple IDE use cases) were used in this contribution: yes
patch was checked with LLMs for quality, tests done with LLM and benchmark script were drafted with an AI coding assistant.

PR Checklist

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.

@read-the-docs-community

read-the-docs-community Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

@IAlibay IAlibay left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@carlosvega I'm blocking to PR to ask you to please open an issue to discuss the need for the code you're adding.

@codecov

codecov Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.93%. Comparing base (607a5a9) to head (5ae938c).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop    #5515   +/-   ##
========================================
  Coverage    93.93%   93.93%           
========================================
  Files          184      184           
  Lines        22662    22675   +13     
  Branches      3223     3227    +4     
========================================
+ Hits         21287    21300   +13     
  Misses         915      915           
  Partials       460      460           

☔ View full report in Codecov by Harness.
📢 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.

@carlosvega

Copy link
Copy Markdown
Contributor Author

Thanks, I opened #5517 to discuss whether this is needed.

@orbeckst orbeckst left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall the PR makes sense to me. Please see my initial comments.

Comment thread package/CHANGELOG Resolved
Comment thread package/CHANGELOG Resolved
Comment thread package/CHANGELOG Resolved
Comment thread package/MDAnalysis/analysis/contacts.py Resolved
Comment thread package/MDAnalysis/analysis/contacts.py Resolved
Comment thread package/MDAnalysis/analysis/contacts.py Resolved
Comment thread package/MDAnalysis/analysis/contacts.py Resolved
Comment thread package/MDAnalysis/analysis/contacts.py Resolved

@BradyAJohnston BradyAJohnston left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This mostly looks good to me, just some minor nits.

Additionally:

  • Need to update PR description to ref comput_pairs_only instead of pairs.

  • The __init__ stil builds the full NxM self.r0 which is still kept for the full lifetime. The initial memory isn't saved currently. We could also drop the full matrix and just use include the pairs as well saving some more memory for larger systems.

Comment thread package/MDAnalysis/analysis/contacts.py Resolved
Comment thread package/MDAnalysis/analysis/contacts.py Resolved
@carlosvega

Copy link
Copy Markdown
Contributor Author

Hi, good point regarding r0. Maybe we can open a separate PR for this. I am worried because dropping the full matrix would change behaviour for everyone regardless of compute_pairs_only=True

@carlosvega

Copy link
Copy Markdown
Contributor Author

@carlosvega I'm blocking to PR to ask you to please open an issue to discuss the need for the code you're adding.

Hi again @IAlibay I opened #5517 to discuss this as requested. Could you take another look ?

@carlosvega

carlosvega commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor Author

@orbeckst @IAlibay I think I addressed all your comments. Thanks again. Let me know if something else is needed

@carlosvega
carlosvega requested a review from orbeckst October 29, 2026 13:11
@carlosvega

Copy link
Copy Markdown
Contributor Author

Hello everyone, is there anything I can do to move this PR forward? Thank you all.

@carlosvega
carlosvega requested a review from IAlibay November 13, 2026 09:46
@orbeckst orbeckst added the AI-assisted Generated with AI/LLM assistance label Nov 13, 2026

@orbeckst orbeckst left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks good to me. I like that the clean separation of the two code paths though private methods.

def test_rerun_after_initial_contacts_edit(
self, universe, compute_pairs_only
):
"""initial_contacts is public: editing it between runs must be

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

initial_contacts is not actually documented so calling it public is a bit of a stretch. However, clever people may have (ab)used it so I am ok with leaving this test in.

@orbeckst

Copy link
Copy Markdown
Member

@IAlibay are you ok with moving forward with merging the PR? The issue was raised and described the idea, both Brady and I are happy with the PR.

@orbeckst orbeckst self-assigned this Nov 13, 2026
@IAlibay
IAlibay dismissed their stale review November 13, 2026 16:22

issue raised

@IAlibay

IAlibay commented Nov 13, 2026

Copy link
Copy Markdown
Member

@IAlibay are you ok with moving forward with merging the PR? The issue was raised and described the idea, both Brady and I are happy with the PR.

Yeah sorry about that - I dismissed the review.

@orbeckst
orbeckst merged commit 951f305 into MDAnalysis:develop Nov 13, 2026
35 of 36 checks passed
@orbeckst

Copy link
Copy Markdown
Member

@carlosvega congratulations on your first merged PR 🎉

@carlosvega

Copy link
Copy Markdown
Contributor Author

Thanks! ☺️

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI-assisted Generated with AI/LLM assistance

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Contacts computes the full N×M distance matrix every frame even when only sparse reference pairs are needed

4 participants