Skip to content

feat: add enhanced-sampling PR1 - #159

Open
samarjeet wants to merge 10 commits into
NVIDIA:mainfrom
samarjeet:main
Open

feat: add enhanced-sampling PR1#159
samarjeet wants to merge 10 commits into
NVIDIA:mainfrom
samarjeet:main

Conversation

@samarjeet

Copy link
Copy Markdown

ALCHEMI Toolkit Pull Request

Description

Adds the PR1 enhanced-sampling foundation: BiasPotential, detached and validated BiasResult, ConservativeBias autograd support for forces and canonical virials, pair_distance as the first collective variable, and bias-result aggregation.

This PR also records the compile-spike outcome. pair_distance, aggregation, and bias energy() functions compile with torch.compile(fullgraph=True) on CPU and CUDA. ConservativeBias.evaluate() remains the eager orchestration layer because requires_grad_() causes a Dynamo graph break; compile_biases=True should compile
each bias energy() override instead.

Scope notes:

  • pair_distance supports nonperiodic systems and Minkowski-reduced triclinic MIC.
  • General unreduced triclinic MIC is deferred; eager mode rejects unreduced periodic cells.
  • Compiled callers are responsible for supplying already-reduced cells because runtime validation is skipped under torch.compile.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • [ x] New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Performance improvement
  • Documentation update
  • Refactoring (no functional changes)
  • CI/CD or infrastructure change

Related Issues

Changes Made

Testing

  • [x ] Unit tests pass locally (make pytest)
  • Linting passes (make lint)
  • [ x] New tests added for new functionality meets coverage expectations?

Checklist

  • I have read and understand the Contributing Guidelines
  • I have updated the CHANGELOG.md
  • [ x] I have performed a self-review of my code
  • [x ] I have added docstrings to new functions/classes
  • I have updated the documentation (if applicable)

Additional Notes

Tip

This repository uses Greptile, an AI code review service, to help conduct
pull request reviews. We encourage contributors to read and consider suggestions
made by Greptile, but note that human maintainers will provide the necessary
reviews for merging: Greptile's comments are not a qualitative judgement
of your code, nor is it an indication that the PR will be accepted/rejected.
We encourage the use of emoji reactions to Greptile comments, depending on
their usefulness and accuracy.

…riable

Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
Signed-off-by: Samarjeet Prasad <p.samar.j@gmail.com>
@copy-pr-bot

copy-pr-bot Bot commented Aug 5, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@greptile-apps

greptile-apps Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR introduces the initial enhanced-sampling API, including detached bias results, autograd-derived forces and virials, pair-distance collective variables, and result aggregation.

  • Adds BiasPotential, BiasResult, and ConservativeBias abstractions.
  • Implements nonperiodic and reduced-triclinic pair distances with eager validation and compile support.
  • Adds aggregation and extensive unit and compilation tests.

Important Files Changed

Filename Overview
nvalchemi/enhanced_sampling/_bias.py Adds the core bias contracts and autograd orchestration, but aggregation rejects mixed stress/virial contributions and drops state-version metadata.
nvalchemi/enhanced_sampling/cv/pair_distance.py Adds a differentiable pair-distance CV with eager input and reduced-cell validation plus a compile-compatible MIC path.
nvalchemi/enhanced_sampling/init.py Exposes the new enhanced-sampling abstractions and pair-distance CV through the package API.
test/enhanced_sampling/test_bias_core.py Provides broad validation, autograd, MIC, aggregation, and compilation coverage, but does not exercise mixed stress/virial aggregation or state-version preservation.

Reviews (1): Last reviewed commit: "fixing non-periodic case" | Re-trigger Greptile

Comment on lines +519 to +522
if r.stress is not None:
stress_total = r.stress if stress_total is None else stress_total + r.stress
if r.virial is not None:
virial_total = r.virial if virial_total is None else virial_total + r.virial

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

P1 Mixed stress and virial fail

When one result supplies stress and another supplies virial, aggregation retains both fields and passes them to BiasResult, whose mutual-exclusion validation raises ValueError instead of returning the combined bias output.

Comment on lines +514 to +536
for r in results:
if r.energy is not None:
energy_total = r.energy if energy_total is None else energy_total + r.energy
if r.forces is not None:
forces_total = r.forces if forces_total is None else forces_total + r.forces
if r.stress is not None:
stress_total = r.stress if stress_total is None else stress_total + r.stress
if r.virial is not None:
virial_total = r.virial if virial_total is None else virial_total + r.virial
for key, val in r.observables.items():
if key in observables_total:
raise ValueError(
f"aggregate_bias_results: duplicate observable key {key!r}. "
"Apply 'bias/<name>/<key>' namespacing before aggregation."
)
observables_total[key] = val

return BiasResult(
energy=energy_total,
forces=forces_total,
stress=stress_total,
virial=virial_total,
observables=observables_total,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

P1 Aggregation drops state versions

When an input carries state_version IDs, the aggregation loop never reads them and the returned BiasResult omits them, preventing downstream replica-exchange processing from performing the documented state-coherence validation.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant