flashmd 0.2.3__tar.gz → 0.2.4__tar.gz

{flashmd-0.2.3 → flashmd-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashmd
-Version: 0.2.3
+Version: 0.2.4
 Summary: Accelerated molecular dynamics with large-time-step predictions
 Author: flashmd developers
 License: Apache-2.0
@@ -65,14 +65,15 @@ time_step = 64  # 64 fs; also available: 1, 2, 4, 8, 16, 32, 128 fs
 # Create a structure and initialize velocities
 atoms = ase.build.bulk("Al", "fcc", cubic=True)
 MaxwellBoltzmannDistribution(atoms, temperature_K=300)
-
-# It is generally a good idea to remove any net velocity from the system
-atoms.set_velocities(atoms.get_velocities() - atoms.get_momenta().sum(axis=0) / atoms.get_masses().sum())
+atoms.set_velocities(  # it is generally a good idea to remove any net velocity
+    atoms.get_velocities() - atoms.get_momenta().sum(axis=0) / atoms.get_masses().sum()
+)
 
 # Load models
 device="cuda" if torch.cuda.is_available() else "cpu"
 energy_model, flashmd_model = get_pretrained("pet-omatpes", time_step)  
 
+# Set the energy model (see below for more precise usage)
 calculator = MetatomicCalculator(energy_model, device=device)
 atoms.calc = calculator
 
@@ -98,6 +99,60 @@ Other available integrators:
   from flashmd.ase.bussi import Bussi
 ```
 
+Common pitfalls
+---------------
+
+Stick to 10-30x what you would use in normal MD for your system! The 64 fs example
+above is good for metals. However,
+- for most materials: try 32 fs (aggressive) or 16 fs (conservative)
+- for aqueous and/or organic systems: try 16 fs (aggressive) or 8 fs (conservative)
+
+
+Companion energy models and exact energy conservation
+-----------------------------------------------------
+
+You might have noticed that ``get_pretrained()`` does not only return a FlashMD model,
+but also an energy model, which is itself just a machine-learned interatomic potential.
+This is the energy model that the FlashMD model was trained on. You might want to use it
+if...
+
+Case 1: you want to run FlashMD with exact energy conservation, available through the
+integrator's (``dyn`` above) parameter ``rescale_energy=True`` (this is enabled by
+default only when targeting the NVE ensemble with ``VelocityVerlet``). In that case,
+besides setting this flag, you should attach the energy calculator to the atoms before
+running FlashMD, exactly as shown above (and below with the more precise
+``do_gradients_with_energy=False`` which will save you memory and computation):
+
+```
+from metatomic.torch.ase_calculator import MetatomicCalculator
+
+...  # setting up atoms
+calculator = MetatomicCalculator(energy_model, device=device, do_gradients_with_energy=False)
+atoms.calc = calculator
+...  # running FlashMD
+```
+
+Case 2: you want to compute energies after running FlashMD for your own analysis. In
+this case, you can create the calculator just like in case 1, but possibly after running
+FlashMD and/or in a different script.
+
+Case 3: you found something interesting during a FlashMD run and you want to confirm it
+with traditional MD. Then, you can just use ASE's MD modules as usual after attaching
+the energy calculator:
+
+```
+from metatomic.torch.ase_calculator import MetatomicCalculator
+
+...  # setting up atoms
+calculator = MetatomicCalculator(energy_model, device=device)
+atoms.calc = calculator
+...  # running MD
+```
+
+In general, the energy models are slower and have a larger memory footprint compared to
+the FlashMD models. As summarized above, you should use `do_gradients_with_energy=False`
+to save computation and memory when you don't need forces.
+
 Disclaimer
 ----------
 

{flashmd-0.2.3 → flashmd-0.2.4}/README.md

@@ -36,14 +36,15 @@ time_step = 64  # 64 fs; also available: 1, 2, 4, 8, 16, 32, 128 fs
 # Create a structure and initialize velocities
 atoms = ase.build.bulk("Al", "fcc", cubic=True)
 MaxwellBoltzmannDistribution(atoms, temperature_K=300)
-
-# It is generally a good idea to remove any net velocity from the system
-atoms.set_velocities(atoms.get_velocities() - atoms.get_momenta().sum(axis=0) / atoms.get_masses().sum())
+atoms.set_velocities(  # it is generally a good idea to remove any net velocity
+    atoms.get_velocities() - atoms.get_momenta().sum(axis=0) / atoms.get_masses().sum()
+)
 
 # Load models
 device="cuda" if torch.cuda.is_available() else "cpu"
 energy_model, flashmd_model = get_pretrained("pet-omatpes", time_step)  
 
+# Set the energy model (see below for more precise usage)
 calculator = MetatomicCalculator(energy_model, device=device)
 atoms.calc = calculator
 
@@ -69,6 +70,60 @@ Other available integrators:
   from flashmd.ase.bussi import Bussi
 ```
 
+Common pitfalls
+---------------
+
+Stick to 10-30x what you would use in normal MD for your system! The 64 fs example
+above is good for metals. However,
+- for most materials: try 32 fs (aggressive) or 16 fs (conservative)
+- for aqueous and/or organic systems: try 16 fs (aggressive) or 8 fs (conservative)
+
+
+Companion energy models and exact energy conservation
+-----------------------------------------------------
+
+You might have noticed that ``get_pretrained()`` does not only return a FlashMD model,
+but also an energy model, which is itself just a machine-learned interatomic potential.
+This is the energy model that the FlashMD model was trained on. You might want to use it
+if...
+
+Case 1: you want to run FlashMD with exact energy conservation, available through the
+integrator's (``dyn`` above) parameter ``rescale_energy=True`` (this is enabled by
+default only when targeting the NVE ensemble with ``VelocityVerlet``). In that case,
+besides setting this flag, you should attach the energy calculator to the atoms before
+running FlashMD, exactly as shown above (and below with the more precise
+``do_gradients_with_energy=False`` which will save you memory and computation):
+
+```
+from metatomic.torch.ase_calculator import MetatomicCalculator
+
+...  # setting up atoms
+calculator = MetatomicCalculator(energy_model, device=device, do_gradients_with_energy=False)
+atoms.calc = calculator
+...  # running FlashMD
+```
+
+Case 2: you want to compute energies after running FlashMD for your own analysis. In
+this case, you can create the calculator just like in case 1, but possibly after running
+FlashMD and/or in a different script.
+
+Case 3: you found something interesting during a FlashMD run and you want to confirm it
+with traditional MD. Then, you can just use ASE's MD modules as usual after attaching
+the energy calculator:
+
+```
+from metatomic.torch.ase_calculator import MetatomicCalculator
+
+...  # setting up atoms
+calculator = MetatomicCalculator(energy_model, device=device)
+atoms.calc = calculator
+...  # running MD
+```
+
+In general, the energy models are slower and have a larger memory footprint compared to
+the FlashMD models. As summarized above, you should use `do_gradients_with_energy=False`
+to save computation and memory when you don't need forces.
+
 Disclaimer
 ----------
 

{flashmd-0.2.3 → flashmd-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flashmd"
-version = "0.2.3"
+version = "0.2.4"
 requires-python = ">=3.9"
 
 readme = "README.md"

{flashmd-0.2.3 → flashmd-0.2.4}/src/flashmd/ase/velocity_verlet.py

@@ -95,6 +95,37 @@ class VelocityVerlet(MolecularDynamics):
             alpha = np.sqrt(1.0 - (new_energy - old_energy) / old_kinetic_energy)
             self.atoms.set_momenta(alpha * self.atoms.get_momenta())
 
+    def irun(self, steps=50):
+        # We have to override irun to avoid calling MolecularDynamics.irun(), which
+        # calls gradients to check convergence (optimizer-like behavior) or to log the
+        # forces, depending on the ASE version. This function is a copy of
+        # Dynamics.irun(), where the calls to the forces are commented out.
+
+        # update the maximum number of steps
+        self.max_steps = self.nsteps + steps
+
+        if self.nsteps == 0:
+            # For historical reasons we do a magical incantation
+            # here with forces, log, observers.
+            # self.atoms.get_forces()
+            self.log()
+            self.call_observers()
+
+        yield self.nsteps == self.max_steps
+
+        # run the algorithm until converged or max_steps reached
+        while self.nsteps < self.max_steps:
+            self.step()
+            self.nsteps += 1
+            # self.atoms.get_forces()
+            self.log()
+            self.call_observers()
+            yield self.nsteps == self.max_steps
+
+    def run(self, steps=50):
+        # needed for ASE <= 3.26.0; in 3.27.0 Dynamics.run() works well for us
+        for _ in self.irun(steps=steps):
+            pass
 
 def _convert_atoms_to_system(
     atoms: ase.Atoms, dtype: str, device: str | torch.device

{flashmd-0.2.3 → flashmd-0.2.4}/src/flashmd.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashmd
-Version: 0.2.3
+Version: 0.2.4
 Summary: Accelerated molecular dynamics with large-time-step predictions
 Author: flashmd developers
 License: Apache-2.0
@@ -65,14 +65,15 @@ time_step = 64  # 64 fs; also available: 1, 2, 4, 8, 16, 32, 128 fs
 # Create a structure and initialize velocities
 atoms = ase.build.bulk("Al", "fcc", cubic=True)
 MaxwellBoltzmannDistribution(atoms, temperature_K=300)
-
-# It is generally a good idea to remove any net velocity from the system
-atoms.set_velocities(atoms.get_velocities() - atoms.get_momenta().sum(axis=0) / atoms.get_masses().sum())
+atoms.set_velocities(  # it is generally a good idea to remove any net velocity
+    atoms.get_velocities() - atoms.get_momenta().sum(axis=0) / atoms.get_masses().sum()
+)
 
 # Load models
 device="cuda" if torch.cuda.is_available() else "cpu"
 energy_model, flashmd_model = get_pretrained("pet-omatpes", time_step)  
 
+# Set the energy model (see below for more precise usage)
 calculator = MetatomicCalculator(energy_model, device=device)
 atoms.calc = calculator
 
@@ -98,6 +99,60 @@ Other available integrators:
   from flashmd.ase.bussi import Bussi
 ```
 
+Common pitfalls
+---------------
+
+Stick to 10-30x what you would use in normal MD for your system! The 64 fs example
+above is good for metals. However,
+- for most materials: try 32 fs (aggressive) or 16 fs (conservative)
+- for aqueous and/or organic systems: try 16 fs (aggressive) or 8 fs (conservative)
+
+
+Companion energy models and exact energy conservation
+-----------------------------------------------------
+
+You might have noticed that ``get_pretrained()`` does not only return a FlashMD model,
+but also an energy model, which is itself just a machine-learned interatomic potential.
+This is the energy model that the FlashMD model was trained on. You might want to use it
+if...
+
+Case 1: you want to run FlashMD with exact energy conservation, available through the
+integrator's (``dyn`` above) parameter ``rescale_energy=True`` (this is enabled by
+default only when targeting the NVE ensemble with ``VelocityVerlet``). In that case,
+besides setting this flag, you should attach the energy calculator to the atoms before
+running FlashMD, exactly as shown above (and below with the more precise
+``do_gradients_with_energy=False`` which will save you memory and computation):
+
+```
+from metatomic.torch.ase_calculator import MetatomicCalculator
+
+...  # setting up atoms
+calculator = MetatomicCalculator(energy_model, device=device, do_gradients_with_energy=False)
+atoms.calc = calculator
+...  # running FlashMD
+```
+
+Case 2: you want to compute energies after running FlashMD for your own analysis. In
+this case, you can create the calculator just like in case 1, but possibly after running
+FlashMD and/or in a different script.
+
+Case 3: you found something interesting during a FlashMD run and you want to confirm it
+with traditional MD. Then, you can just use ASE's MD modules as usual after attaching
+the energy calculator:
+
+```
+from metatomic.torch.ase_calculator import MetatomicCalculator
+
+...  # setting up atoms
+calculator = MetatomicCalculator(energy_model, device=device)
+atoms.calc = calculator
+...  # running MD
+```
+
+In general, the energy models are slower and have a larger memory footprint compared to
+the FlashMD models. As summarized above, you should use `do_gradients_with_energy=False`
+to save computation and memory when you don't need forces.
+
 Disclaimer
 ----------