flashmd 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashmd
-Version: 0.2.2
+Version: 0.2.4
 Summary: Accelerated molecular dynamics with large-time-step predictions
 Author: flashmd developers
 License: Apache-2.0
@@ -60,17 +60,20 @@ from flashmd.ase.langevin import Langevin
 
 
 # Choose your time step (go for 10-30x what you would use in normal MD for your system)
-time_step = 16  # 16 fs; also available: 1, 2, 4, 8, 32, 64, 128 fs
+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)
-atoms.set_velocities(atoms.get_velocities() - atoms.get_velocities().mean(axis=0))
+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
 
@@ -96,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
 ----------
 
@@ -132,3 +189,6 @@ pip install flashmd==0.1.2 ase==3.24.0 pet-mad==1.4.3
 
 and using the "PET-MAD" models (PBEsol) from https://huggingface.co/lab-cosmo/flashmd.
 Note that the results were obtained through the i-PI interface.
+
+Instructions and material to reproduce the results in the paper are available on
+Materials Cloud at https://doi.org/10.24435/materialscloud:b7-xq.

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

@@ -31,17 +31,20 @@ from flashmd.ase.langevin import Langevin
 
 
 # Choose your time step (go for 10-30x what you would use in normal MD for your system)
-time_step = 16  # 16 fs; also available: 1, 2, 4, 8, 32, 64, 128 fs
+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)
-atoms.set_velocities(atoms.get_velocities() - atoms.get_velocities().mean(axis=0))
+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
 
@@ -67,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
 ----------
 
@@ -103,3 +160,6 @@ pip install flashmd==0.1.2 ase==3.24.0 pet-mad==1.4.3
 
 and using the "PET-MAD" models (PBEsol) from https://huggingface.co/lab-cosmo/flashmd.
 Note that the results were obtained through the i-PI interface.
+
+Instructions and material to reproduce the results in the paper are available on
+Materials Cloud at https://doi.org/10.24435/materialscloud:b7-xq.

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

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

{flashmd-0.2.2 → flashmd-0.2.4}/src/flashmd/ase/langevin.py

@@ -27,7 +27,7 @@ class Langevin(VelocityVerlet):
         self.friction = 1.0 / time_constant
         self.fixcm = fixcm
         if self.fixcm:
-            self.atoms.set_velocities(self.atoms.get_velocities() - self.atoms.get_velocities().mean(axis=0))
+            self.atoms.set_velocities(self.atoms.get_velocities() - self.atoms.get_momenta().sum(axis=0) / self.atoms.get_masses().sum())
 
     def step(self):
         self.apply_langevin_half_step()
@@ -43,4 +43,4 @@ class Langevin(VelocityVerlet):
         ) * np.random.randn(*old_momenta.shape)
         self.atoms.set_momenta(new_momenta)
         if self.fixcm:
-            self.atoms.set_velocities(self.atoms.get_velocities() - self.atoms.get_velocities().mean(axis=0))
+            self.atoms.set_velocities(self.atoms.get_velocities() - self.atoms.get_momenta().sum(axis=0) / self.atoms.get_masses().sum())

{flashmd-0.2.2 → 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.2 → flashmd-0.2.4}/src/flashmd.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashmd
-Version: 0.2.2
+Version: 0.2.4
 Summary: Accelerated molecular dynamics with large-time-step predictions
 Author: flashmd developers
 License: Apache-2.0
@@ -60,17 +60,20 @@ from flashmd.ase.langevin import Langevin
 
 
 # Choose your time step (go for 10-30x what you would use in normal MD for your system)
-time_step = 16  # 16 fs; also available: 1, 2, 4, 8, 32, 64, 128 fs
+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)
-atoms.set_velocities(atoms.get_velocities() - atoms.get_velocities().mean(axis=0))
+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
 
@@ -96,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
 ----------
 
@@ -132,3 +189,6 @@ pip install flashmd==0.1.2 ase==3.24.0 pet-mad==1.4.3
 
 and using the "PET-MAD" models (PBEsol) from https://huggingface.co/lab-cosmo/flashmd.
 Note that the results were obtained through the i-PI interface.
+
+Instructions and material to reproduce the results in the paper are available on
+Materials Cloud at https://doi.org/10.24435/materialscloud:b7-xq.