Major restructuring

[smparker]

Lots of intertwined restructuring is done here:

• uses velocities as primary object rather than momenta, to better match with what most other codes out there do
• restructure MD classes to use a Propagator object that can be switched out
• implement a Nose-Hoover thermostat for AdiabaticMD
• rename TrajectorySH -> SurfaceHoppingMD
• make cumulative surface hopping an option to SurfaceHoppingMD, rather than a distinct class
• SurfaceHoppingMD defaults to cumulative SH!
• new type of cumulative surface hopping, cumulative_integrated, following the way described in the Parker, Schiltz appendix.
• models now have more descriptive ways to describe the dimensionality
  • nparticles (e.g., number of atoms)
  • ndims (i.e., 1D or 3D space)
  • ndof (defaults to nparticles x ndims)
  • dimensionality -> (nparticles, ndims)
  • atom_types -> list of elements or what have you
• lots of interface changes to enforce read-only nature of models and to make Trace_ work well
• a few more examples
  • OpenMM examples of NVT and NVE dynamics
  • Tully avoided crossing
  • Harmonic model of water

[Copilot]

Pull Request Overview

This PR refactors trajectory infrastructure to use velocities as the primary variable, introduces a Propagator abstraction for both adiabatic and surface-hopping MD, adds a Nose–Hoover thermostat, and reorganizes batch drivers and examples.

• Swapped “momentum” inputs and storage to “velocity” everywhere and updated generators and trajectories accordingly
• Introduced Propagator classes (e.g. VVPropagator, NoseHooverChainPropagator, AFSSHVVPropagator) and factories (AdiabaticPropagator, AFSSHPropagator)
• Restructured BatchedTraj, renamed TrajectorySH→SurfaceHoppingMD, unified cumulative hopping option, and updated CLI and docs

Reviewed Changes

Copilot reviewed 110 out of 110 changed files in this pull request and generated 2 comments.

File	Description
mudslide/batch.py	Switched to velocities in generators, restructured batch API
mudslide/main.py	Updated CLI to use SurfaceHoppingMD and velocity sampling
mudslide/afssh.py	Added Propagator classes and updated A-FSSH implementation
mudslide/adiabatic_propagator.py	New module for MD propagators including NHC thermostat

Comments suppressed due to low confidence (2)

mudslide/afssh.py:75

• The return type annotation 'SHPropagator' is incorrect—update it to AFSSHVVPropagator or a common base Propagator_ to match actual return types.

def __new__(cls, model: Any, prop_options: Any = "vv") -> 'SHPropagator':

mudslide/main.py:141

• Assigning trace_type to a string will break the TraceManager constructor which expects a trace class. Restore the mapping to actual classes (e.g. {'memory': InMemoryTrace, 'yaml': YAMLTrace}[args.log]).

trace_type = args.log

[Copilot]

Currently self.traj_options is reused and mutated in each loop iteration, leading to accumulated parameters across trajectories. Use a copy (e.g. traj_input = self.traj_options.copy()) before updating with params.

Suggested change

	traj_input = self.traj_options
	traj_input = self.traj_options.copy()

[Copilot]

[nitpick] Use the project logger instead of print for consistency and better control. For example: logger.info("Nose–Hoover chain thermostat initialized with:").

Suggested change

	print("Nose-Hoover chain thermostat initialized with:")
	print(f" Temperature: {temperature:.2f} K")
	print(f" Number of chains: {nchains}")
	print(f" Timescale: {timescale / fs_to_au:.2f} fs")
	print(f" Thermostat mass: {self.nh_mass}")
	logger.info("Nose-Hoover chain thermostat initialized with:")
	logger.info(f" Temperature: {temperature:.2f} K")
	logger.info(f" Number of chains: {nchains}")
	logger.info(f" Timescale: {timescale / fs_to_au:.2f} fs")
	logger.info(f" Thermostat mass: {self.nh_mass}")