Skip to content

Conversation

curtischong
Copy link
Collaborator

@curtischong curtischong commented Jul 7, 2025

Summary

  • The usage of the word "batch" is misleading since it really means "sample in a set of graphs". Describing multiple systems as a set of graphs is so much clearer. By renaming batch to graphs, we also free up the word "batch" to mean an actual batch (e.g. a set of systems we are processing at once)
  • See https://github.com/Radical-AI/torch-sim/pull/189/files for more discussion.

This change is quite involved. But I didn't want to split it up into multiple parts because "batch" is so pervasive within the codebase. But it feels like the right thing to do. Notable, I changed these interfaces in the SimState:

SimState.n_atoms_per_batch (renamed to n_atoms_per_graph)
SimState.n_batches (renamed to n_graphs)
SimState.batch (renamed to graph_idx)
SimState.__getitem__(self, batch_indices: int | list[int] | slice | torch.Tensor) -> Self: (renamed to SimState.__getitem__(self, graph_indices: int | list[int] | slice | torch.Tensor) -> Self:)
SimState.__init__(self, ..., batch) (renamed to SimState.__init__(self, ..., graph_idx))

The changes to getitem and init will cause breaking changes, but I feel like it is worth it while torchsim's adoption is currently minimal.

Notes of my changes

  • I didn't change the autobatcher logic much since it's a bit more involved and would probably require a more experienced eye to properly rename it.
  • comments that are talking about the "batch dimension" have not been changed. This already makes sense because the graph dimension IS the batch dimension.
  • I probably did not get every rename. But the vast majority have been renamed.
  • One way to review this PR is to clone it and search for "batch". Here, you can see the things that did NOT get renamed (and the surrounding code that did)
  • codecov/patch is failing becuase this is just a huge change. However, I do not want to introduce logical changes in this PR so I'm not fixing it (it'll make it harder to review)
  • http://test_graphpes.py/ failing is probably a flake

Checklist

Before a pull request can be merged, the following items must be checked:

  • Doc strings have been added in the Google docstring format.
  • Run ruff on your code.
  • Tests have been added for any new functionality or bug fixes.

Summary by CodeRabbit

  • Refactor

    • Replaced all occurrences of "batch" with "graph" in variable names, property names, function parameters, comments, and documentation across the codebase, aligning terminology with the concept of graphs representing independent systems.
    • Updated tensor shape annotations and indexing semantics from per-batch to per-graph throughout modules including integrators, models, optimizers, transforms, and workflows.
    • Renamed properties and method signatures accordingly (e.g., batchgraph_idx, n_batchesn_graphs) without changing logic or control flow.
  • Tests

    • Modified all test code to reflect the new "graph" terminology, updating variable names, assertions, comments, and test function names for consistency with the refactor.
  • Style

    • Improved print statements, error messages, and comments to use "graph" terminology, enhancing clarity and consistency.
  • Chores

    • Updated .gitignore to exclude the .vscode/ directory.

@cla-bot cla-bot bot added the cla-signed Contributor license agreement signed label Jul 7, 2025
Copy link

coderabbitai bot commented Jul 7, 2025

"""

Walkthrough

The changes systematically rename variables, function names, comments, and documentation from "batch" to "graph" throughout the codebase, reflecting a shift in terminology to better represent the data structure. This includes updates in scripts, core modules, tests, and documentation, without altering underlying logic or control flow.

Changes

File(s) Change Summary
.gitignore Added .vscode/ to ignore list under a new "# IDE" section.
examples/scripts/1_Introduction/1.2_MACE.py
examples/scripts/2_Structural_optimization/2.3_MACE_Gradient_Descent.py
Renamed variable atoms_per_batch to atoms_per_graph in tensor creation and usage.
examples/scripts/2_Structural_optimization/2.5_MACE_UnitCellFilter_Gradient_Descent.py
examples/scripts/2_Structural_optimization/2.6_MACE_UnitCellFilter_FIRE.py
examples/scripts/2_Structural_optimization/2.7_MACE_FrechetCellFilter_FIRE.py
Updated comments to reflect default cell_factor behavior as "atoms per graph" instead of "atoms per batch".
examples/scripts/3_Dynamics/*.py (multiple) Replaced all calls passing batch=state.batch with graph_idx=state.graph_idx in kinetic energy and temperature calculations.
examples/scripts/3_Dynamics/3.10_Hybrid_swap_mc.py
examples/tutorials/hybrid_swap_tutorial.py
Changed tensor size initialization from n_batches to n_graphs for last_permutation in HybridSwapMCState.
examples/scripts/4_High_level_api/4.2_auto_batching_api.py
examples/scripts/5_Workflow/5.2_In_Flight_WBM.py
Updated print statements to use state.n_graphs instead of state.n_batches.
examples/scripts/7_Others/7.3_Batched_neighbor_list.py Renamed batch variable to graph_idx and updated related comments and function arguments.
examples/scripts/7_Others/7.6_Compare_ASE_to_VV_FIRE.py Renamed variables and comments from batch to graph in optimization functions.
examples/tutorials/autobatching_tutorial.py Replaced fire_state.n_batches with fire_state.n_graphs in batch processing logic.
examples/tutorials/high_level_tutorial.py Corrected tutorial text to refer to output length as n_graphs instead of n_batches.
examples/tutorials/low_level_tutorial.py Changed call argument from batch=state.batch to graph_idx=state.graph_idx in temperature calculation.
tests/* (multiple files including test_integrators.py, test_state.py, test_trajectory.py, test_autobatching.py, test_correlations.py, test_io.py, test_monte_carlo.py, test_neighbors.py, test_optimizers.py, test_runners.py, test_transforms.py) Renamed all occurrences of batch/n_batches to graph_idx/n_graphs in variables, assertions, comments, and test function names. Added backward compatibility test for deprecated batch properties in test_state.py.
torch_sim/autobatching.py Renamed variables and docstrings from batch to graph terminology in memory and batch size metrics.
torch_sim/integrators/npt.py
torch_sim/integrators/nvt.py
torch_sim/integrators/nve.py
torch_sim/integrators/md.py
Systematic renaming of all batch-related variables, arguments, and comments to graph-related ones, including indexing and tensor shapes; no logic changes.
torch_sim/io.py Renamed batch-related variables and comments to graph-related ones in state conversion functions.
torch_sim/math.py Updated docstring to reflect return shape as [n_graphs] instead of [n_batches] in batched_vdot.
torch_sim/models/* (including mace.py, fairchem.py, graphpes.py, interface.py, lennard_jones.py, metatomic.py, morse.py, orb.py, particle_life.py, sevennet.py, soft_sphere.py) Replaced all batch-related variable names, comments, and docstrings with graph-related terminology in model forward methods and related functions.
torch_sim/monte_carlo.py Renamed batch-related parameters, variables, and comments to graph-related ones in swap generation, validation, and Monte Carlo step functions.
torch_sim/neighbors.py Renamed function parameter and internal variables from batch to graph in torch_nl_linked_cell.
torch_sim/optimizers.py Comprehensive renaming of batch-related attributes, variables, and comments to graph-related ones in optimizer states and functions; updated tensor shape annotations accordingly.
torch_sim/runners.py Updated progress bar total counts and convergence function docstrings to use n_graphs instead of n_batches.
torch_sim/state.py Renamed batch attribute and related properties to graph_idx and n_graphs; updated method signatures and internal variable names accordingly; added deprecated batch property aliases with warnings.
torch_sim/trajectory.py Renamed variables and parameters from batch to graph in TrajectoryReporter.report and TorchSimTrajectory.write_state methods; updated error messages and comments.
torch_sim/transforms.py Renamed function parameters, variables, and docstrings from batch to graph in coordinate transformations and neighborhood building functions.
torch_sim/typing.py Updated type alias StateKey to replace "batch" with "graph_idx".
torch_sim/workflows/a2c.py Changed tensor dimensions in logging from state.n_batches to state.n_graphs.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Script/Module
    participant State
    participant Integrator

    User->>Script/Module: Run computation or test
    Script/Module->>State: Access n_atoms_per_graph
    State-->>Script/Module: Return per-graph atom counts
    Script/Module->>Integrator: Pass per-graph data
    Integrator-->>Script/Module: Process and return results
    Script/Module-->>User: Output results with per-graph terminology
Loading

Possibly related PRs

  • Remove unbatched code #206: This PR removes unbatched code and replaces it with batched implementations; it is strongly related as the current PR's renaming and refactoring are part of the broader effort to adopt batched processing fully.

Suggested labels

enhancement, pkg

Poem

A rabbit hopped through fields of code,
Swapping "batch" for "graph" in every node.
Now atoms align, per-graph in their place,
With comments and tests keeping up the pace.
The code feels fresh, the naming clear—
A hoppy update, let’s all cheer!
🐇✨
"""


📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0aa7991 and be83288.

📒 Files selected for processing (2)
  • torch_sim/models/morse.py (2 hunks)
  • torch_sim/models/particle_life.py (2 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
  • torch_sim/models/morse.py
  • torch_sim/models/particle_life.py
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (37)
  • GitHub Check: test-examples (examples/scripts/5_Workflow/5.1_a2c_silicon_batched.py)
  • GitHub Check: test-examples (examples/scripts/4_High_level_api/4.2_auto_batching_api.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.5_MACE_UnitCellFilter_Gradient_Descen...
  • GitHub Check: test-examples (examples/tutorials/high_level_tutorial.py)
  • GitHub Check: test-examples (examples/scripts/4_High_level_api/4.1_high_level_api.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.4_MACE_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.2_Soft_Sphere_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.12_MACE_NPT_Langevin.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.6_MACE_NVT_Nose_Hoover_temp_profile.py)
  • GitHub Check: test-examples (examples/scripts/6_Phonons/6.1_Phonons_MACE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.13_MACE_NVE_non_pbc.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.4_MACE_NVT_Langevin.py)
  • GitHub Check: test-examples (examples/scripts/6_Phonons/6.3_Conductivity_MACE.py)
  • GitHub Check: test-examples (examples/scripts/7_Others/7.6_Compare_ASE_to_VV_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.8_MACE_NPT_Nose_Hoover.py)
  • GitHub Check: test-examples (examples/scripts/7_Others/7.4_Velocity_AutoCorrelation.py)
  • GitHub Check: test-examples (examples/tutorials/using_graphpes_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/autobatching_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/low_level_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/hybrid_swap_tutorial.py)
  • GitHub Check: test-model (macos-14, 3.12, lowest-direct, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (macos-14, 3.12, lowest-direct, metatomic, tests/models/test_metatomic.py)
  • GitHub Check: test-model (macos-14, 3.12, lowest-direct, sevenn, tests/models/test_sevennet.py)
  • GitHub Check: test-model (macos-14, 3.11, highest, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (macos-14, 3.12, lowest-direct, fairchem, tests/models/test_fairchem.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, sevenn, tests/models/test_sevennet.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, mace, tests/test_optimizers_vs_ase.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, mace, tests/test_elastic.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, sevenn, tests/models/test_sevennet.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, fairchem, tests/models/test_fairchem.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, mace, tests/test_elastic.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, fairchem, tests/models/test_fairchem.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, mace, tests/test_optimizers_vs_ase.py)
  • GitHub Check: test-core (ubuntu-latest, 3.12, lowest-direct)
  • GitHub Check: build-docs
✨ Finishing Touches
  • 📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Explain this complex logic.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@curtischong curtischong marked this pull request as draft July 7, 2025 14:43
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 4

🧹 Nitpick comments (2)
examples/tutorials/state_tutorial.py (1)

263-263: Label still says “Per-batch” – update to match the new terminology

The printout now queries scope["per_graph"], but the user-facing label remains “Per-batch”. Tiny mismatch, but it’s user-visible.

-print("Per-batch properties:", scope["per_graph"])
+print("Per-graph properties:", scope["per_graph"])
tests/test_integrators.py (1)

375-409: Docstring/comments lag behind rename + minor ratio comment

  1. The test has been renamed to atoms_per_graph, yet the docstring still says “…per batch”.
  2. Inline comment line 382 says “8:1 atom ratio” but the code creates 8 vs 64 atoms (1 : 8); could confuse future readers.
-"""Test that compute_cell_force correctly scales by number of atoms per batch.
+"""Test that _compute_cell_force correctly scales by the number of atoms per graph.
@@
-    # Setup minimal state with two batches having 8:1 atom ratio
+    # Two graphs with an 8 × larger atom count in the second (8 vs 64)
📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2bb3bd5 and 8773f45.

📒 Files selected for processing (12)
  • .gitignore (1 hunks)
  • examples/scripts/1_Introduction/1.2_MACE.py (1 hunks)
  • examples/scripts/2_Structural_optimization/2.3_MACE_Gradient_Descent.py (1 hunks)
  • examples/tutorials/state_tutorial.py (1 hunks)
  • tests/test_integrators.py (1 hunks)
  • tests/test_state.py (3 hunks)
  • tests/test_trajectory.py (1 hunks)
  • torch_sim/integrators/npt.py (10 hunks)
  • torch_sim/integrators/nvt.py (2 hunks)
  • torch_sim/io.py (3 hunks)
  • torch_sim/quantities.py (1 hunks)
  • torch_sim/state.py (14 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (3)
torch_sim/integrators/nvt.py (1)
torch_sim/state.py (1)
  • n_atoms_per_graph (152-158)
tests/test_state.py (1)
torch_sim/state.py (1)
  • n_atoms_per_graph (152-158)
tests/test_trajectory.py (2)
tests/conftest.py (1)
  • si_double_sim_state (323-325)
torch_sim/trajectory.py (1)
  • get_array (601-629)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (58)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.6_MACE_UnitCellFilter_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/4_High_level_api/4.1_high_level_api.py)
  • GitHub Check: test-examples (examples/scripts/5_Workflow/5.3_Elastic.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.5_MACE_UnitCellFilter_Gradient_Descen...
  • GitHub Check: test-examples (examples/scripts/4_High_level_api/4.2_auto_batching_api.py)
  • GitHub Check: test-examples (examples/scripts/5_Workflow/5.1_a2c_silicon_batched.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.3_MACE_Gradient_Descent.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.1_Lennard_Jones_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/5_Workflow/5.2_In_Flight_WBM.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.9_MACE_NVT_staggered_stress.py)
  • GitHub Check: test-examples (examples/scripts/1_Introduction/1.3_Fairchem.py)
  • GitHub Check: test-examples (examples/scripts/2_Structural_optimization/2.7_MACE_FrechetCellFilter_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/6_Phonons/6.1_Phonons_MACE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.10_Hybrid_swap_mc.py)
  • GitHub Check: test-examples (examples/scripts/6_Phonons/6.3_Conductivity_MACE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.12_MACE_NPT_Langevin.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.4_MACE_NVT_Langevin.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.8_MACE_NPT_Nose_Hoover.py)
  • GitHub Check: test-examples (examples/scripts/1_Introduction/1.2_MACE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.6_MACE_NVT_Nose_Hoover_temp_profile.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.3_MACE_NVE_cueq.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.5_MACE_NVT_Nose_Hoover.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.13_MACE_NVE_non_pbc.py)
  • GitHub Check: test-examples (examples/scripts/7_Others/7.6_Compare_ASE_to_VV_FIRE.py)
  • GitHub Check: test-examples (examples/scripts/7_Others/7.4_Velocity_AutoCorrelation.py)
  • GitHub Check: test-examples (examples/scripts/6_Phonons/6.2_QuasiHarmonic_MACE.py)
  • GitHub Check: test-examples (examples/scripts/3_Dynamics/3.2_MACE_NVE.py)
  • GitHub Check: test-examples (examples/tutorials/metatomic_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/high_level_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/hybrid_swap_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/autobatching_tutorial.py)
  • GitHub Check: test-examples (examples/tutorials/low_level_tutorial.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, sevenn, tests/models/test_sevennet.py)
  • GitHub Check: test-model (macos-14, 3.11, highest, metatomic, tests/models/test_metatomic.py)
  • GitHub Check: test-model (macos-14, 3.11, highest, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, graphpes, tests/models/test_graphpes.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, mace, tests/test_optimizers_vs_ase.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, fairchem, tests/models/test_fairchem.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, metatomic, tests/models/test_metatomic.py)
  • GitHub Check: test-model (macos-14, 3.11, highest, fairchem, tests/models/test_fairchem.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, mattersim, tests/models/test_mattersim.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, mace, tests/models/test_mace.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, sevenn, tests/models/test_sevennet.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, mace, tests/test_optimizers_vs_ase.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, mace, tests/test_elastic.py)
  • GitHub Check: test-model (ubuntu-latest, 3.12, lowest-direct, mace, tests/models/test_mace.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, orb, tests/models/test_orb.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, graphpes, tests/models/test_graphpes.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, fairchem, tests/models/test_fairchem.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, metatomic, tests/models/test_metatomic.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, mattersim, tests/models/test_mattersim.py)
  • GitHub Check: test-model (ubuntu-latest, 3.11, highest, mace, tests/test_elastic.py)
  • GitHub Check: test-core (macos-14, 3.12, lowest-direct)
  • GitHub Check: test-core (macos-14, 3.11, highest)
  • GitHub Check: test-core (ubuntu-latest, 3.12, lowest-direct)
  • GitHub Check: test-core (ubuntu-latest, 3.11, highest)
  • GitHub Check: build-docs
🔇 Additional comments (11)
.gitignore (1)

38-40: Ignoring .vscode/ is a sound addition

Prevents IDE-specific metadata from slipping into commits and keeps the repo clean.

tests/test_trajectory.py (1)

681-684: LGTM – variable rename & assertions consistent with new terminology
No functional issues spotted.

torch_sim/quantities.py (1)

63-69: LGTM! Consistent terminology update.

The variable rename from dof_per_batch to dof_per_graph aligns with the broader codebase terminology update while preserving the calculation logic.

tests/test_state.py (1)

32-32: LGTM! Test assertions correctly updated.

The test assertions properly reflect the updated scope keys from "per_batch" to "per_graph".

Also applies to: 53-53

torch_sim/io.py (3)

229-231: LGTM! Consistent variable renaming.

The local variable rename from atoms_per_batch to atoms_per_graph improves terminology consistency while preserving the batch index creation logic.


301-303: LGTM! Consistent variable renaming.

The variable rename maintains the same logic for creating batch indices using torch.repeat_interleave.


372-374: LGTM! Consistent variable renaming.

The rename aligns with the broader terminology update while preserving the batch index generation logic.

torch_sim/integrators/nvt.py (2)

373-380: LGTM! Consistent terminology update in initialization.

The variable renames from n_atoms_per_batch/dof_per_batch to n_atoms_per_graph/dof_per_graph preserve the degrees of freedom calculation logic while improving terminology consistency.


482-483: LGTM! Consistent variable renaming in invariant calculation.

The rename to n_atoms_per_graph maintains the same degrees of freedom calculation for the conserved quantity computation.

torch_sim/integrators/npt.py (1)

139-139: LGTM: Systematic and consistent renaming from "batch" to "graph" terminology.

The renaming of variables and properties from n_atoms_per_batch/KE_per_batch/DOF_per_batch to n_atoms_per_graph/KE_per_graph/DOF_per_graph is systematic and preserves all underlying mathematical logic. The terminology change better reflects that each "batch" represents a separate molecular graph/system.

Also applies to: 666-666, 672-672, 738-739, 1020-1021, 1216-1224, 1239-1239, 1288-1289, 1428-1429, 1599-1605, 1609-1611, 1621-1628

torch_sim/state.py (1)

152-152: Breaking change: Property renamed from n_atoms_per_batch to n_atoms_per_graph.

This property name change supports the terminology update throughout the codebase but constitutes a breaking change for external users.

@curtischong curtischong changed the title Rename per-batch to per-graph Rename batch to graph Jul 7, 2025
@curtischong curtischong added the breaking Breaking changes label Jul 7, 2025
@curtischong curtischong marked this pull request as ready for review July 7, 2025 21:15
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8773f45 and c555b9d.

📒 Files selected for processing (66)
  • examples/scripts/1_Introduction/1.2_MACE.py (1 hunks)
  • examples/scripts/2_Structural_optimization/2.3_MACE_Gradient_Descent.py (1 hunks)
  • examples/scripts/2_Structural_optimization/2.5_MACE_UnitCellFilter_Gradient_Descent.py (1 hunks)
  • examples/scripts/2_Structural_optimization/2.6_MACE_UnitCellFilter_FIRE.py (1 hunks)
  • examples/scripts/2_Structural_optimization/2.7_MACE_FrechetCellFilter_FIRE.py (1 hunks)
  • examples/scripts/3_Dynamics/3.10_Hybrid_swap_mc.py (1 hunks)
  • examples/scripts/3_Dynamics/3.11_Lennard_Jones_NPT_Langevin.py (2 hunks)
  • examples/scripts/3_Dynamics/3.12_MACE_NPT_Langevin.py (5 hunks)
  • examples/scripts/3_Dynamics/3.13_MACE_NVE_non_pbc.py (1 hunks)
  • examples/scripts/3_Dynamics/3.2_MACE_NVE.py (1 hunks)
  • examples/scripts/3_Dynamics/3.3_MACE_NVE_cueq.py (1 hunks)
  • examples/scripts/3_Dynamics/3.4_MACE_NVT_Langevin.py (1 hunks)
  • examples/scripts/3_Dynamics/3.5_MACE_NVT_Nose_Hoover.py (1 hunks)
  • examples/scripts/3_Dynamics/3.6_MACE_NVT_Nose_Hoover_temp_profile.py (1 hunks)
  • examples/scripts/3_Dynamics/3.7_Lennard_Jones_NPT_Nose_Hoover.py (2 hunks)
  • examples/scripts/3_Dynamics/3.8_MACE_NPT_Nose_Hoover.py (4 hunks)
  • examples/scripts/3_Dynamics/3.9_MACE_NVT_staggered_stress.py (1 hunks)
  • examples/scripts/4_High_level_api/4.2_auto_batching_api.py (1 hunks)
  • examples/scripts/5_Workflow/5.2_In_Flight_WBM.py (1 hunks)
  • examples/scripts/7_Others/7.3_Batched_neighbor_list.py (2 hunks)
  • examples/scripts/7_Others/7.6_Compare_ASE_to_VV_FIRE.py (10 hunks)
  • examples/tutorials/autobatching_tutorial.py (2 hunks)
  • examples/tutorials/high_level_tutorial.py (1 hunks)
  • examples/tutorials/hybrid_swap_tutorial.py (1 hunks)
  • examples/tutorials/low_level_tutorial.py (1 hunks)
  • examples/tutorials/state_tutorial.py (6 hunks)
  • tests/models/conftest.py (1 hunks)
  • tests/test_autobatching.py (6 hunks)
  • tests/test_correlations.py (1 hunks)
  • tests/test_integrators.py (6 hunks)
  • tests/test_io.py (6 hunks)
  • tests/test_monte_carlo.py (5 hunks)
  • tests/test_neighbors.py (3 hunks)
  • tests/test_optimizers.py (9 hunks)
  • tests/test_runners.py (9 hunks)
  • tests/test_state.py (18 hunks)
  • tests/test_trajectory.py (5 hunks)
  • tests/test_transforms.py (10 hunks)
  • torch_sim/autobatching.py (12 hunks)
  • torch_sim/integrators/md.py (7 hunks)
  • torch_sim/integrators/npt.py (51 hunks)
  • torch_sim/integrators/nve.py (5 hunks)
  • torch_sim/integrators/nvt.py (10 hunks)
  • torch_sim/io.py (12 hunks)
  • torch_sim/math.py (1 hunks)
  • torch_sim/models/fairchem.py (1 hunks)
  • torch_sim/models/graphpes.py (1 hunks)
  • torch_sim/models/interface.py (4 hunks)
  • torch_sim/models/lennard_jones.py (2 hunks)
  • torch_sim/models/mace.py (9 hunks)
  • torch_sim/models/metatomic.py (2 hunks)
  • torch_sim/models/morse.py (2 hunks)
  • torch_sim/models/orb.py (3 hunks)
  • torch_sim/models/particle_life.py (2 hunks)
  • torch_sim/models/sevennet.py (2 hunks)
  • torch_sim/models/soft_sphere.py (4 hunks)
  • torch_sim/monte_carlo.py (5 hunks)
  • torch_sim/neighbors.py (3 hunks)
  • torch_sim/optimizers.py (38 hunks)
  • torch_sim/quantities.py (5 hunks)
  • torch_sim/runners.py (8 hunks)
  • torch_sim/state.py (23 hunks)
  • torch_sim/trajectory.py (6 hunks)
  • torch_sim/transforms.py (15 hunks)
  • torch_sim/typing.py (1 hunks)
  • torch_sim/workflows/a2c.py (1 hunks)
✅ Files skipped from review due to trivial changes (16)
  • examples/scripts/2_Structural_optimization/2.6_MACE_UnitCellFilter_FIRE.py
  • examples/scripts/2_Structural_optimization/2.7_MACE_FrechetCellFilter_FIRE.py
  • examples/scripts/2_Structural_optimization/2.5_MACE_UnitCellFilter_Gradient_Descent.py
  • examples/scripts/5_Workflow/5.2_In_Flight_WBM.py
  • torch_sim/math.py
  • examples/scripts/4_High_level_api/4.2_auto_batching_api.py
  • examples/scripts/1_Introduction/1.2_MACE.py
  • examples/tutorials/state_tutorial.py
  • tests/test_transforms.py
  • examples/tutorials/high_level_tutorial.py
  • torch_sim/models/lennard_jones.py
  • torch_sim/models/interface.py
  • tests/test_neighbors.py
  • torch_sim/integrators/nve.py
  • torch_sim/trajectory.py
  • torch_sim/transforms.py
🚧 Files skipped from review as they are similar to previous changes (7)
  • tests/test_trajectory.py
  • examples/scripts/2_Structural_optimization/2.3_MACE_Gradient_Descent.py
  • torch_sim/io.py
  • torch_sim/quantities.py
  • torch_sim/integrators/nvt.py
  • torch_sim/state.py
  • tests/test_state.py
🧰 Additional context used
🧬 Code Graph Analysis (19)
examples/scripts/3_Dynamics/3.12_MACE_NPT_Langevin.py (1)
torch_sim/quantities.py (1)
  • calc_kT (23-69)
examples/tutorials/hybrid_swap_tutorial.py (1)
torch_sim/state.py (3)
  • n_graphs (202-204)
  • device (142-144)
  • dtype (147-149)
torch_sim/models/graphpes.py (1)
torch_sim/state.py (1)
  • n_graphs (202-204)
examples/scripts/3_Dynamics/3.10_Hybrid_swap_mc.py (1)
torch_sim/state.py (1)
  • n_graphs (202-204)
tests/test_optimizers.py (2)
tests/conftest.py (1)
  • ar_supercell_sim_state (306-310)
torch_sim/state.py (2)
  • clone (239-255)
  • n_graphs (202-204)
tests/test_correlations.py (1)
torch_sim/state.py (4)
  • n_graphs (202-204)
  • device (142-144)
  • dtype (147-149)
  • split (281-290)
examples/scripts/3_Dynamics/3.5_MACE_NVT_Nose_Hoover.py (2)
torch_sim/quantities.py (1)
  • calc_kT (23-69)
torch_sim/integrators/nvt.py (1)
  • nvt_nose_hoover_invariant (448-517)
examples/scripts/3_Dynamics/3.7_Lennard_Jones_NPT_Nose_Hoover.py (2)
torch_sim/quantities.py (2)
  • calc_kT (23-69)
  • calc_kinetic_energy (96-130)
torch_sim/integrators/npt.py (2)
  • momenta (70-72)
  • npt_nose_hoover_invariant (1559-1668)
examples/tutorials/autobatching_tutorial.py (1)
torch_sim/state.py (1)
  • n_graphs (202-204)
tests/test_monte_carlo.py (1)
torch_sim/monte_carlo.py (1)
  • validate_permutation (127-141)
tests/test_runners.py (3)
torch_sim/state.py (6)
  • batch (175-181)
  • batch (184-190)
  • n_graphs (202-204)
  • device (142-144)
  • dtype (147-149)
  • n_atoms (152-154)
tests/conftest.py (4)
  • ar_double_sim_state (314-319)
  • device (24-25)
  • dtype (29-30)
  • ar_supercell_sim_state (306-310)
tests/test_correlations.py (1)
  • MockState (22-42)
torch_sim/models/soft_sphere.py (1)
torch_sim/state.py (2)
  • SimState (26-353)
  • n_graphs (202-204)
torch_sim/models/particle_life.py (4)
torch_sim/models/lennard_jones.py (1)
  • unbatched_forward (223-354)
torch_sim/models/soft_sphere.py (2)
  • unbatched_forward (253-378)
  • unbatched_forward (655-803)
torch_sim/models/morse.py (1)
  • unbatched_forward (230-344)
torch_sim/state.py (1)
  • n_graphs (202-204)
torch_sim/runners.py (2)
torch_sim/state.py (1)
  • n_graphs (202-204)
torch_sim/properties/correlations.py (1)
  • update (178-196)
torch_sim/optimizers.py (12)
torch_sim/state.py (10)
  • n_graphs (202-204)
  • device (142-144)
  • dtype (147-149)
  • to (321-335)
  • deform_grad (391-397)
  • clone (239-255)
  • DeformGradMixin (356-397)
  • _deform_grad (379-389)
  • row_vector_cell (226-228)
  • row_vector_cell (231-237)
torch_sim/models/interface.py (4)
  • device (107-109)
  • device (112-116)
  • dtype (119-121)
  • dtype (124-128)
tests/conftest.py (2)
  • device (24-25)
  • dtype (29-30)
tests/test_neighbors.py (1)
  • dtype (15-16)
tests/models/test_graphpes.py (1)
  • dtype (23-25)
tests/models/test_mace.py (1)
  • dtype (28-30)
tests/models/test_sevennet.py (1)
  • dtype (22-24)
tests/models/test_mattersim.py (1)
  • dtype (25-27)
torch_sim/integrators/md.py (1)
  • velocities (44-48)
torch_sim/integrators/npt.py (1)
  • velocities (866-872)
torch_sim/integrators/nvt.py (1)
  • velocities (269-273)
torch_sim/math.py (1)
  • batched_vdot (992-1022)
tests/test_integrators.py (1)
torch_sim/quantities.py (1)
  • calc_kT (23-69)
torch_sim/monte_carlo.py (3)
torch_sim/state.py (3)
  • device (142-144)
  • n_graphs (202-204)
  • n_atoms (152-154)
tests/conftest.py (1)
  • device (24-25)
tests/test_monte_carlo.py (1)
  • generator (33-36)
torch_sim/autobatching.py (1)
torch_sim/state.py (2)
  • n_graphs (202-204)
  • concatenate_states (806-892)
torch_sim/integrators/npt.py (4)
torch_sim/state.py (8)
  • device (142-144)
  • dtype (147-149)
  • n_graphs (202-204)
  • n_atoms_per_graph (157-163)
  • volume (207-209)
  • momenta (360-366)
  • to (321-335)
  • clone (239-255)
torch_sim/integrators/md.py (2)
  • velocities (44-48)
  • calculate_momenta (51-109)
torch_sim/integrators/nvt.py (1)
  • velocities (269-273)
torch_sim/quantities.py (1)
  • calc_kinetic_energy (96-130)
🪛 GitHub Check: codecov/patch
torch_sim/integrators/md.py

[warning] 83-83: torch_sim/integrators/md.py#L83
Added line #L83 was not covered by tests


[warning] 90-90: torch_sim/integrators/md.py#L90
Added line #L90 was not covered by tests


[warning] 95-96: torch_sim/integrators/md.py#L95-L96
Added lines #L95 - L96 were not covered by tests

torch_sim/autobatching.py

[warning] 1023-1023: torch_sim/autobatching.py#L1023
Added line #L1023 was not covered by tests


[warning] 1029-1029: torch_sim/autobatching.py#L1029
Added line #L1029 was not covered by tests

torch_sim/integrators/npt.py

[warning] 246-246: torch_sim/integrators/npt.py#L246
Added line #L246 was not covered by tests


[warning] 249-249: torch_sim/integrators/npt.py#L249
Added line #L249 was not covered by tests


[warning] 286-286: torch_sim/integrators/npt.py#L286
Added line #L286 was not covered by tests


[warning] 294-294: torch_sim/integrators/npt.py#L294
Added line #L294 was not covered by tests


[warning] 498-498: torch_sim/integrators/npt.py#L498
Added line #L498 was not covered by tests


[warning] 507-507: torch_sim/integrators/npt.py#L507
Added line #L507 was not covered by tests


[warning] 510-510: torch_sim/integrators/npt.py#L510
Added line #L510 was not covered by tests


[warning] 581-581: torch_sim/integrators/npt.py#L581
Added line #L581 was not covered by tests


[warning] 584-584: torch_sim/integrators/npt.py#L584
Added line #L584 was not covered by tests


[warning] 887-889: torch_sim/integrators/npt.py#L887-L889
Added lines #L887 - L889 were not covered by tests


[warning] 962-964: torch_sim/integrators/npt.py#L962-L964
Added lines #L962 - L964 were not covered by tests


[warning] 975-975: torch_sim/integrators/npt.py#L975
Added line #L975 was not covered by tests


[warning] 1013-1013: torch_sim/integrators/npt.py#L1013
Added line #L1013 was not covered by tests


[warning] 1016-1017: torch_sim/integrators/npt.py#L1016-L1017
Added lines #L1016 - L1017 were not covered by tests


[warning] 1085-1085: torch_sim/integrators/npt.py#L1085
Added line #L1085 was not covered by tests


[warning] 1150-1150: torch_sim/integrators/npt.py#L1150
Added line #L1150 was not covered by tests


[warning] 1208-1208: torch_sim/integrators/npt.py#L1208
Added line #L1208 was not covered by tests


[warning] 1212-1212: torch_sim/integrators/npt.py#L1212
Added line #L1212 was not covered by tests


[warning] 1215-1220: torch_sim/integrators/npt.py#L1215-L1220
Added lines #L1215 - L1220 were not covered by tests


[warning] 1230-1230: torch_sim/integrators/npt.py#L1230
Added line #L1230 was not covered by tests


[warning] 1269-1271: torch_sim/integrators/npt.py#L1269-L1271
Added lines #L1269 - L1271 were not covered by tests


[warning] 1284-1285: torch_sim/integrators/npt.py#L1284-L1285
Added lines #L1284 - L1285 were not covered by tests


[warning] 1409-1409: torch_sim/integrators/npt.py#L1409
Added line #L1409 was not covered by tests


[warning] 1413-1414: torch_sim/integrators/npt.py#L1413-L1414
Added lines #L1413 - L1414 were not covered by tests


[warning] 1421-1421: torch_sim/integrators/npt.py#L1421
Added line #L1421 was not covered by tests


[warning] 1424-1425: torch_sim/integrators/npt.py#L1424-L1425
Added lines #L1424 - L1425 were not covered by tests


[warning] 1434-1434: torch_sim/integrators/npt.py#L1434
Added line #L1434 was not covered by tests


[warning] 1444-1444: torch_sim/integrators/npt.py#L1444
Added line #L1444 was not covered by tests

🔇 Additional comments (101)
examples/scripts/3_Dynamics/3.13_MACE_NVE_non_pbc.py (1)

80-80: Verified: graph_idx parameter is supported end-to-end

  • The calc_kinetic_energy function in torch_sim/quantities.py defines graph_idx as an optional parameter.
  • The state.graph_idx field is populated by atoms_to_state in torch_sim/io.py.

No further changes are needed; this renaming is correct.

examples/scripts/3_Dynamics/3.3_MACE_NVE_cueq.py (1)

74-74: Parameter renaming is consistent.

The change from batch=state.batch to graph_idx=state.graph_idx aligns with the systematic renaming throughout the codebase.

examples/scripts/3_Dynamics/3.2_MACE_NVE.py (1)

91-91: Parameter renaming follows established pattern.

The change from batch=state.batch to graph_idx=state.graph_idx is consistent with the renaming pattern seen across the other files.

examples/scripts/3_Dynamics/3.10_Hybrid_swap_mc.py (1)

89-89: Property renaming is correct.

The change from md_state.n_batches to md_state.n_graphs correctly updates the tensor size calculation to use the renamed property. Based on the code snippet from torch_sim/state.py, the n_graphs property properly returns the number of distinct graphs in the system.

examples/scripts/3_Dynamics/3.4_MACE_NVT_Langevin.py (1)

86-86: LGTM: Consistent parameter name update.

The changes correctly update the calc_kT function calls to use the new graph_idx parameter instead of batch, aligning with the broader renaming effort throughout the codebase.

Also applies to: 93-93

examples/scripts/3_Dynamics/3.5_MACE_NVT_Nose_Hoover.py (1)

71-71: LGTM: Consistent parameter name update.

The changes correctly update the calc_kT function calls to use the new graph_idx parameter instead of batch, maintaining consistency with the codebase-wide renaming effort.

Also applies to: 79-79

examples/scripts/3_Dynamics/3.8_MACE_NPT_Nose_Hoover.py (1)

72-72: LGTM: Consistent parameter name updates across multiple functions.

The changes correctly update both calc_kT and calc_kinetic_energy function calls to use the new graph_idx parameter instead of batch, maintaining consistency throughout the NPT simulation loops and final calculations.

Also applies to: 89-89, 98-98, 110-110, 118-120

examples/scripts/3_Dynamics/3.11_Lennard_Jones_NPT_Langevin.py (1)

122-122: LGTM: Consistent parameter name updates.

The changes correctly update both calc_kT and calc_kinetic_energy function calls to use the new graph_idx parameter instead of batch, maintaining consistency with the codebase-wide renaming effort.

Also applies to: 128-128, 142-142, 150-150

examples/tutorials/hybrid_swap_tutorial.py (1)

136-136: LGTM: Consistent property name update.

The change correctly updates the tensor size from md_state.n_batches to md_state.n_graphs, aligning with the codebase-wide renaming effort. The tensor will still have the correct size for tracking permutation status per graph.

examples/scripts/3_Dynamics/3.6_MACE_NVT_Nose_Hoover_temp_profile.py (1)

166-166: LGTM! Parameter name updated consistently.

The change from batch=state.batch to graph_idx=state.graph_idx correctly aligns with the updated calc_kT function signature and the broader semantic shift from "batch" to "graph" terminology.

torch_sim/typing.py (1)

18-18: LGTM! Type definition updated to match renamed attribute.

The StateKey type literal correctly reflects the renaming from "batch" to "graph_idx" in the SimState class, ensuring type safety is maintained throughout the codebase.

examples/tutorials/low_level_tutorial.py (1)

231-231: LGTM! Tutorial updated with correct API usage.

The parameter change from batch=state.batch to graph_idx=state.graph_idx correctly demonstrates the updated calc_kT function signature in the tutorial.

tests/models/conftest.py (2)

172-172: LGTM! Test updated for renamed attribute.

The change from sim_state.batch to sim_state.graph_idx correctly reflects the renamed attribute in the SimState class while maintaining the same test logic.


180-180: LGTM! Immutability assertion updated for renamed attribute.

The assertion correctly verifies that the model doesn't mutate the graph_idx attribute, maintaining the same test coverage with the updated naming.

examples/scripts/3_Dynamics/3.12_MACE_NPT_Langevin.py (5)

71-71: LGTM! Parameter updated consistently in NVT loop.

The change from batch=state.batch to graph_idx=state.graph_idx in the calc_kT function call correctly uses the updated API.


86-86: LGTM! Parameter updated consistently in NPT loop.

The temperature calculation correctly uses the updated graph_idx parameter naming.


95-95: LGTM! Kinetic energy calculation updated consistently.

The calc_kinetic_energy function call correctly uses the updated graph_idx parameter.


110-110: LGTM! Final temperature calculation updated.

The final temperature calculation correctly uses the updated parameter naming.


120-120: LGTM! Final pressure calculation updated.

The final kinetic energy calculation for pressure determination correctly uses the updated graph_idx parameter.

torch_sim/models/graphpes.py (1)

70-71: LGTM: Consistent terminology update

The changes correctly update the iteration and masking logic to use the new graph-based terminology (n_graphs and graph_idx) while preserving the original functionality.

examples/scripts/3_Dynamics/3.7_Lennard_Jones_NPT_Nose_Hoover.py (1)

126-126: LGTM: Function calls updated correctly

All function calls to calc_kT and calc_kinetic_energy have been properly updated to use the new graph_idx parameter naming, consistent with the function signatures in torch_sim/quantities.py.

Also applies to: 133-133, 148-148, 155-157

torch_sim/workflows/a2c.py (1)

733-736: LGTM: Tensor shapes updated correctly

The logging tensor dimensions have been properly updated to use state.n_graphs instead of state.n_batches, maintaining the correct shape for tracking energy and stress over multiple systems during optimization.

examples/scripts/7_Others/7.3_Batched_neighbor_list.py (1)

21-21: LGTM: Variable renaming and function calls updated correctly

The variable has been correctly renamed from batch to graph_idx, the comment accurately reflects the new tensor shape notation, and both neighbor list function calls have been properly updated to use the new variable name.

Also applies to: 25-26, 29-29, 41-41

torch_sim/models/metatomic.py (2)

77-77: LGTM: Docstring updated correctly

The docstring has been properly updated to reference "graph indices" instead of "batch indices", consistent with the new terminology.


203-203: LGTM: Mask logic updated correctly

The system mask creation correctly uses state.graph_idx == b instead of state.batch == b, maintaining the same logic while using the updated attribute name.

tests/test_optimizers.py (7)

131-131: LGTM: Consistent parameter renaming

The parameter name change from batch to graph_idx aligns with the systematic terminology update across the codebase.


232-232: LGTM: Comment update maintains clarity

The comment update from "per-batch dt" to "per-graph dt" maintains clarity while adopting the new terminology.


265-265: LGTM: Consistent indexing attribute renaming

The indexing operations correctly use graph_idx instead of batch while preserving the same selection logic.

Also applies to: 268-268, 320-321


348-348: LGTM: Consistent constructor parameter update

The SimState constructor parameter correctly uses graph_idx instead of batch.


432-432: LGTM: Property name updates are consistent

The property name changes from n_batches to n_graphs align with the updated API and maintain the same functionality.

Also applies to: 456-456


459-459: LGTM: Consistent attribute usage in unique operation

The change from state.batch to state.graph_idx in the torch.unique call maintains the same logic for counting unique graph indices.


877-878: LGTM: Error message terminology updated

The error messages correctly use "graph" terminology instead of "batch", maintaining consistency with the new naming convention.

torch_sim/models/sevennet.py (2)

184-185: LGTM: Correct iteration and masking logic with new terminology

The iteration range and batch masking logic correctly use graph_idx instead of batch while preserving the same functionality for processing each graph separately.


248-248: LGTM: Tensor sizing correctly updated

The energy tensor sizing correctly uses state.graph_idx.max().item() + 1 to determine the number of graphs, maintaining the same logic with the updated attribute name.

torch_sim/models/orb.py (3)

105-105: LGTM: Node counting logic correctly updated

The torch.bincount operation correctly uses state.graph_idx to count nodes per graph, maintaining the same functionality with the updated attribute name.


146-146: LGTM: System count calculation correctly updated

The calculation of n_systems correctly uses state.graph_idx.max().item() + 1 to determine the number of graphs, preserving the same logic.


160-160: LGTM: Batch masking logic correctly updated

The batch mask creation correctly uses state.graph_idx == i to select atoms belonging to each graph, maintaining the same selection logic.

examples/tutorials/autobatching_tutorial.py (3)

252-252: LGTM: Property access correctly updated in tutorial

The change from fire_state.n_batches to fire_state.n_graphs correctly uses the updated property name while maintaining the same tracking functionality.


282-282: LGTM: Assertion correctly updated with new property name

The assertion correctly uses fire_state.n_graphs == 0 to verify that all graphs have been processed, maintaining the same validation logic.


286-286: LGTM: Property demonstration correctly updated

The property access correctly uses fire_state.n_graphs instead of fire_state.n_batches, consistent with the API update.

tests/test_io.py (6)

51-54: LGTM: Test assertions correctly updated for graph indexing

The assertions correctly validate state.graph_idx shape and values instead of state.batch, maintaining the same test coverage with the updated attribute name.


68-69: LGTM: Single atoms test correctly updated

The test correctly validates that state.graph_idx has the expected shape and that all atoms belong to graph 0 for a single structure.


83-87: LGTM: Multiple atoms test correctly updated

The test correctly validates state.graph_idx shape and values for multiple atom structures, ensuring proper graph index assignment.


175-179: LGTM: PhonopyAtoms test correctly updated

The test correctly validates state.graph_idx for PhonopyAtoms conversion, maintaining the same validation logic with the updated attribute name.


240-244: LGTM: Round-trip test setup correctly updated

The test correctly uses torch.unique(sim_state.graph_idx) to count unique graphs and validates that the intermediate format preserves the correct number of structures.


253-253: LGTM: Round-trip validation correctly updated

The assertion correctly validates that graph_idx is preserved through round-trip conversion, maintaining the same test coverage with the updated attribute name.

tests/test_autobatching.py (4)

118-121: LGTM! Consistent terminology update.

The assertions correctly use the new n_graphs and graph_idx properties instead of the old batch-related terminology. The logic remains unchanged.


475-482: LGTM! Graph-based convergence function is correctly updated.

The convergence function properly uses state.n_graphs and state.graph_idx for computing graph-wise maximum forces. The semantic meaning is preserved while using the clearer terminology.


517-538: LGTM! Optimal batch counting updated consistently.

The variables tracking optimal number of graphs and the counting logic have been correctly updated to use graph-based terminology while maintaining the same computational logic.


564-577: LGTM! Convergence tensor creation uses correct graph count.

The convergence tensor initialization correctly uses state.n_graphs to create tensors with the appropriate size for tracking convergence per graph.

torch_sim/neighbors.py (3)

769-769: LGTM! Parameter renamed for better semantic clarity.

Renaming batch to graph_idx makes the function signature more descriptive, clearly indicating that this parameter represents the graph index for each atom.


787-787: LGTM! Docstring correctly updated.

The parameter documentation properly reflects the new graph_idx parameter name and maintains the same semantic meaning.


809-809: LGTM! Function usage updated consistently.

The torch.bincount(graph_idx) call correctly uses the renamed parameter while maintaining the same computational logic.

torch_sim/autobatching.py (7)

237-237: LGTM! Print statement correctly updated.

The diagnostic message now properly reports the number of graphs instead of batches, aligning with the new terminology.


296-297: LGTM! Variable naming updated consistently.

The variable n_graphs better represents what it's counting compared to the previous batch-related naming.


346-346: LGTM! Condition check uses correct property.

The check for multiple graphs using state.n_graphs > 1 is semantically correct and consistent with the terminology update.


408-409: LGTM! Print statement terminology updated appropriately.

The diagnostic message correctly refers to "graphs" instead of "batches" when describing the systems, making the output more accurate.


431-431: LGTM! Docstring updates improve clarity.

The documentation correctly changes "per batch" to "per graph" in descriptions of the maximum memory scaler, making the parameter's purpose clearer.

Also applies to: 480-480, 719-719, 779-779


936-942: LGTM! Batch size determination variable naming updated.

The variable n_graphs is more descriptive than the previous naming and correctly represents what's being counted for memory estimation.


1022-1024: LGTM! Validation checks correctly updated.

All validation checks now use state.n_graphs consistently, maintaining the same validation logic while using the clearer terminology.

Also applies to: 1028-1030, 1060-1060

torch_sim/models/particle_life.py (2)

226-229: LGTM! Docstring updates align with graph terminology.

The docstring changes correctly reflect the shift from batch-based to graph-based indexing for tensor shapes.


242-245: LGTM! Code changes correctly implement the batch→graph renaming.

The attribute access and iteration logic remain identical - only the terminology has been updated from batch/n_batches to graph_idx/n_graphs.

tests/test_integrators.py (3)

112-112: LGTM! Function calls correctly updated to use graph_idx parameter.

The calc_kT function calls have been properly updated from batch=state.batch to graph_idx=state.graph_idx, which aligns with the function signature shown in the relevant code snippets.

Also applies to: 175-175, 216-216, 276-276


375-376: LGTM! Test function renamed consistently with terminology shift.

The function name and docstring have been updated from "atoms_per_batch" to "atoms_per_graph" while preserving the same test logic.


392-392: LGTM! Constructor call updated with correct parameter name.

The NPTLangevinState constructor call has been correctly updated from batch= to graph_idx= parameter.

examples/scripts/7_Others/7.6_Compare_ASE_to_VV_FIRE.py (4)

144-144: LGTM! Property access correctly updated to use n_graphs.

The property access has been systematically updated from n_batches to n_graphs throughout the optimization functions, maintaining the same logic flow.

Also applies to: 171-171, 222-222, 233-233


332-332: LGTM! Variable names consistently renamed from batch to graph terminology.

All variable names have been systematically updated:

  • all_batches_for_gdall_graphs_for_gd
  • batch_idxgraph_idx
  • concatenated_batch_indicesconcatenated_graph_indices

The logic and data flow remain unchanged.

Also applies to: 337-337, 353-357, 397-397


364-364: LGTM! Print statements updated with consistent terminology.

Error messages and print statements have been updated to use graph_idx terminology while maintaining the same informational content.

Also applies to: 378-378


416-416: LGTM! Constructor call updated with correct parameter name.

The GDState constructor call has been correctly updated from batch= to graph_idx= parameter.

tests/test_monte_carlo.py (3)

53-53: LGTM! Function calls correctly updated to use graph_idx parameter.

The validate_permutation function calls have been properly updated to use graph_idx parameter, which aligns with the function signature shown in the relevant code snippets.

Also applies to: 98-98, 108-108


67-69: LGTM! Test logic correctly updated with graph terminology.

The comment and assertions have been updated to use graph_idx while preserving the same validation logic for ensuring swaps occur within the same group.


150-163: LGTM! Monte Carlo validation updated with consistent terminology.

The test code has been systematically updated to use graph_idx for grouping and validation while maintaining the same test logic for verifying atomic number distributions and graph assignments.

tests/test_correlations.py (2)

34-37: LGTM! MockState attributes correctly updated to match SimState interface.

The mock state attributes have been properly updated from n_batches/batch to n_graphs/graph_idx, aligning with the real SimState interface changes shown in the relevant code snippets.


40-42: LGTM! Comments updated with consistent terminology.

The docstring and comments have been updated to use "graph" terminology while maintaining the same functional description.

torch_sim/models/morse.py (2)

359-363: LGTM! Tensor shape documentation correctly updated.

The docstring updates properly reflect the new graph-based terminology, changing from [n_batches] to [n_graphs] for energy and stress tensor shapes.


385-385: LGTM! Iteration logic correctly updated.

The change from state.n_batches to state.n_graphs properly reflects the new terminology while preserving the iteration logic.

torch_sim/models/soft_sphere.py (2)

394-399: LGTM! Documentation properly updated for graph terminology.

The tensor shapes and parameter descriptions correctly reflect the change from batch-based to graph-based indexing.


857-859: LGTM! Consistent error handling in multi-model.

The SoftSphereMultiModel class correctly implements the same graph indexing logic and error handling as the base model.

torch_sim/models/fairchem.py (2)

352-353: LGTM! Graph index initialization correctly updated.

The change from state.batch to state.graph_idx properly reflects the new terminology, and the tensor initialization logic remains sound.


361-362: LGTM! Tensor operations correctly updated for graph indexing.

The torch.bincount(state.graph_idx) and subsequent tensor initialization properly use the new graph indexing scheme while preserving the original computational logic.

tests/test_runners.py (4)

152-152: LGTM! Test trajectory file naming updated correctly.

The change from n_batches to n_graphs in the list comprehension properly reflects the new terminology while maintaining the test logic.


801-801: LGTM! Energy tensor shape assertion correctly updated.

The assertion now properly checks against n_graphs instead of n_batches, maintaining test correctness with the new terminology.


815-817: LGTM! Mock state graph indexing properly implemented.

The mock state correctly uses graph_idx with torch.repeat_interleave and torch.arange(n_graphs) to simulate the new graph indexing scheme.


933-935: LGTM! Controlled mock state maintains consistent graph indexing.

The ControlledMockState class properly implements the graph indexing pattern, ensuring test reliability with the new terminology.

torch_sim/runners.py (1)

175-175: LGTM! Consistent batch-to-graph terminology updates.

All changes correctly update progress bar operations and docstrings from n_batches/(n_batches,) to n_graphs/(n_graphs,). The logic remains unchanged while improving terminology clarity.

Also applies to: 197-197, 310-311, 346-347, 375-375, 437-437, 548-548, 571-571

torch_sim/integrators/npt.py (1)

34-42: LGTM! Comprehensive and consistent batch-to-graph renaming.

This file demonstrates excellent systematic refactoring:

  • All variable references updated from batch/n_batches to graph_idx/n_graphs
  • Docstrings and type annotations properly updated with new tensor shapes
  • Indexing operations consistently use state.graph_idx instead of state.batch
  • Algorithm logic remains unchanged while improving terminology clarity

The changes align perfectly with the PR objective of freeing up "batch" terminology for actual batching operations.

Also applies to: 89-96, 167-179, 231-236, 271-275, 318-321, 406-414, 477-481, 507-511, 547-550, 567-571, 646-647, 680-681, 730-736, 748-749, 852-856, 884-885, 887-893, 950-954, 962-964, 970-974, 990-996, 1013-1017, 1083-1085, 1148-1150, 1177-1178, 1188-1199, 1207-1221, 1269-1271, 1284-1296, 1409-1414, 1421-1425, 1434-1444, 1462-1463, 1477-1478, 1484-1485, 1541-1542, 1591-1610, 1620-1627

torch_sim/models/mace.py (1)

94-94: LGTM! Correct batch-to-graph interface updates with preserved model compatibility.

The changes properly update the external interface to use graph_idx terminology while correctly maintaining batch=state.graph_idx in line 337 for the underlying MACE model interface. This approach:

  • Updates the TorchSim interface to use clearer "graph" terminology
  • Preserves compatibility with the existing MACE model API that expects "batch"
  • Maintains consistency with the broader codebase renaming effort

The method rename from setup_from_batch could be considered for future cleanup, but the current approach correctly balances interface clarity with model compatibility.

Also applies to: 115-115, 132-133, 189-195, 197-199, 208-209, 212-212, 282-287, 298-298, 308-308, 337-337

torch_sim/integrators/md.py (4)

24-24: Docstring updates look accurate.

The terminology changes from "batch" to "graph" in the docstrings correctly reflect the new semantic understanding where each graph represents an independent system.

Also applies to: 27-27, 29-29, 34-34


54-54: Function signature and documentation updated correctly.

The parameter rename from batch to graph_idx and corresponding docstring updates are consistent with the codebase-wide terminology shift.

Also applies to: 67-68, 82-83


150-152: Comment and function call updates are consistent.

The comment update clarifies the graph-based approach, and the function call to pbc_wrap_batched correctly uses state.graph_idx.


90-96: calculate_momenta renaming verified; no changes required

The mechanical rename from batchgraph in torch_sim/integrators/md.py (lines 90–96) preserves the original center-of-mass removal logic. Existing tests in tests/test_integrators.py already cover both multi-atom and single-atom branches of calculate_momenta, so the flagged coverage gap is pre-existing and does not block approval.

torch_sim/monte_carlo.py (4)

44-44: Function documentation and initial variable updates are correct.

The docstring and initial parameter usage correctly reflect the shift from batch-based to graph-based terminology.

Also applies to: 54-54, 57-57


60-78: Complex graph-based swap generation logic preserved correctly.

The renaming from batch-related variables to graph-related variables maintains the same computational logic:

  • graph_lengths replaces batch_lengths
  • n_graphs replaces n_batches
  • Graph indexing and range calculations are preserved
  • The core algorithm for generating swaps within the same graph remains intact

The logic correctly ensures swaps only occur between atoms of different types within the same graph.

Also applies to: 82-103


127-141: Parameter and validation logic updated consistently.

The function parameter change from batch to graph_idx and the corresponding validation logic update correctly enforce that swaps must occur within the same graph.


236-236: State initialization and validation calls updated appropriately.

The graph_idx parameter usage in both init_swap_mc_state and the validation call in swap_monte_carlo_step correctly reflects the terminology change.

Also applies to: 268-268

torch_sim/optimizers.py (6)

47-47: GDState docstring updates are accurate.

The tensor shape annotations correctly reflect the graph-based indexing with [n_graphs] replacing [n_batches].

Also applies to: 50-50, 52-52


71-72: Gradient descent function updates preserve logic.

The learning rate documentation and indexing logic correctly map from graph-based learning rates to per-atom rates using state.graph_idx.

Also applies to: 132-132, 134-134


273-273: Graph counting and indexing logic updated correctly.

The changes to use state.n_graphs and state.graph_idx for counting and indexing operations maintain the same computational semantics with the new terminology.

Also applies to: 278-278, 321-321, 374-374


571-571: Dimension calculations updated consistently across optimizers.

All optimizer initialization functions correctly use state.n_graphs for determining tensor dimensions, ensuring consistency across different optimization methods.

Also applies to: 798-798, 1083-1083


1242-1242: FIRE step functions maintain correct graph-based power calculations.

The batched_vdot calls correctly use state.graph_idx for computing per-graph power values, preserving the FIRE algorithm's velocity-force dot product calculations.

Also applies to: 1369-1369, 1460-1460


1280-1280: Graph iteration loops updated correctly.

The for loops that iterate over graphs correctly use range(n_graphs) and maintain the same computational logic for per-graph operations in both Velocity Verlet and ASE FIRE implementations.

Also applies to: 1344-1344, 1650-1650

add .vscode to gitignore

rename per_batch to per_graph

wip convert many batches to graphs

convert more batches to graphs

rename all of batch indices

rename all of batch indices

wip fix tests

fix more tests

more test renaming

more test renaming again

fix test_deform_grad_batched

rename more batch to use graphs

update mock state to use graphs

precommit

fix bug

rename in calculate_momenta

fix more precommit

rename more batch to graphs

more renames

more renaming

fix deprecated text in docstring

added test for deprecated batch properties in simstate

rename batch to graph

more renames

cleanup

minor typo
@CompRhys
Copy link
Collaborator

CompRhys commented Jul 8, 2025

i'm okay with this but I would probably prefer the word system to graph just because of potential for systems that are not captured in a single graph i.e. two atoms separated at large distances by vacuum. There are some ambiguities in the use of batch to reference systems within batched simulations.

Also need to update the version, whilst this is breaking API change I don't think it really looks like a MAJOR version increment so would bump a MINOR version.

@curtischong
Copy link
Collaborator Author

closing since #217 supersedes this

@curtischong curtischong closed this Jul 9, 2025
@curtischong curtischong deleted the rename-mdstate branch July 9, 2025 03:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
breaking Breaking changes cla-signed Contributor license agreement signed
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants