hillclimber 0.1.0a1__py3-none-any.whl → 0.1.0a2__py3-none-any.whl

hillclimber/__init__.py

@@ -1,18 +1,29 @@
-from hillclimber.actions import PrintCVAction
-from hillclimber.cvs import DistanceCV, CoordinationNumberCV, TorsionCV, RadiusOfGyrationCV
-from hillclimber.metadynamics import MetaDBiasCV, MetaDynamicsConfig, MetaDynamicsModel
+from hillclimber.actions import PrintAction
+from hillclimber.biases import RestraintBias, UpperWallBias, LowerWallBias
+from hillclimber.cvs import DistanceCV, AngleCV, CoordinationNumberCV, TorsionCV, RadiusOfGyrationCV
+from hillclimber.metadynamics import MetadBias, MetaDynamicsConfig, MetaDynamicsModel
+from hillclimber.opes import OPESBias, OPESConfig, OPESModel
 from hillclimber.selectors import IndexSelector, SMARTSSelector, SMILESSelector
+from hillclimber.virtual_atoms import VirtualAtom
 
 __all__ = [
-    "PrintCVAction",
+    "PrintAction",
     "DistanceCV",
+    "AngleCV",
     "CoordinationNumberCV",
     "TorsionCV",
     "RadiusOfGyrationCV",
     "IndexSelector",
     "SMILESSelector",
     "SMARTSSelector",
+    "VirtualAtom",
     "MetaDynamicsModel",
-    "MetaDBiasCV",
+    "MetadBias",
     "MetaDynamicsConfig",
+    "OPESModel",
+    "OPESBias",
+    "OPESConfig",
+    "RestraintBias",
+    "UpperWallBias",
+    "LowerWallBias",
 ]

hillclimber/actions.py

@@ -2,12 +2,38 @@ import dataclasses
 
 import ase
 
-from hillclimber.interfaces import CollectiveVariable
+from hillclimber.interfaces import CollectiveVariable, PlumedGenerator
 
 
 @dataclasses.dataclass
-class PrintCVAction:
-    """Node for PRINT action."""
+class PrintAction(PlumedGenerator):
+    """PLUMED PRINT action for outputting collective variables.
+
+    This action prints the values of collective variables to a file during
+    the simulation. Multiple CVs can be printed to the same file.
+
+    Parameters
+    ----------
+    cvs : list[CollectiveVariable]
+        List of collective variables to print.
+    stride : int, optional
+        Print every N steps, by default 1.
+    file : str, optional
+        Output file name, by default "COLVAR".
+
+    Examples
+    --------
+    >>> import hillclimber as hc
+    >>> print_action = hc.PrintAction(
+    ...     cvs=[cv1, cv2, cv3],
+    ...     stride=100,
+    ...     file="COLVAR"
+    ... )
+
+    Resources
+    ---------
+    - https://www.plumed.org/doc-master/user-doc/html/PRINT/
+    """
 
     cvs: list[CollectiveVariable]
     stride: int = 1

hillclimber/biases.py

@@ -0,0 +1,293 @@
+"""Bias potentials and restraints for collective variables.
+
+This module provides classes for applying bias potentials to collective variables,
+including harmonic restraints and wall potentials.
+"""
+
+# --- IMPORTS ---
+import dataclasses
+
+import ase
+
+from hillclimber.interfaces import BiasProtocol, CollectiveVariable
+
+
+# --- RESTRAINT ---
+@dataclasses.dataclass
+class RestraintBias(BiasProtocol):
+    """Apply a harmonic restraint to a collective variable.
+
+    This class implements the BiasProtocol interface and can be used in the
+    `actions` parameter of MetaDynamicsModel.
+
+    The restraint creates a harmonic potential that restrains a collective variable
+    around a specified value. The restraint potential has the form:
+    V(s) = (1/2) * kappa * (s - at)^2
+
+    Parameters
+    ----------
+    cv : CollectiveVariable
+        The collective variable to restrain.
+    kappa : float
+        The force constant of the restraint in kJ/(mol·unit^2), where unit
+        depends on the CV (e.g., Å for distances, radians for angles).
+    at : float
+        The center/target value of the restraint.
+    label : str, optional
+        A custom label for this restraint. If not provided, uses cv.prefix + "_restraint".
+
+    Examples
+    --------
+    >>> import hillclimber as hc
+    >>> # Restrain a distance around 2.5 Å
+    >>> distance_cv = hc.DistanceCV(...)
+    >>> restraint = hc.RestraintBias(cv=distance_cv, kappa=200.0, at=2.5)
+
+    Resources
+    ---------
+    - https://www.plumed.org/doc-master/user-doc/html/RESTRAINT/
+
+    Notes
+    -----
+    The force constant kappa is in kJ/(mol·unit^2). For typical CV units:
+    - Distances (Å): kappa in kJ/(mol·Å^2)
+    - Angles (radians): kappa in kJ/(mol·rad^2)
+    - Dimensionless CVs: kappa in kJ/mol
+
+    The restraint creates a bias force: F = -kappa * (s - at)
+    """
+
+    cv: CollectiveVariable
+    kappa: float
+    at: float
+    label: str | None = None
+
+    def to_plumed(self, atoms: ase.Atoms) -> list[str]:
+        """Generate PLUMED input strings for the harmonic restraint.
+
+        Parameters
+        ----------
+        atoms : ase.Atoms
+            The atomic structure to use for generating the PLUMED string.
+
+        Returns
+        -------
+        list[str]
+            List of PLUMED command strings. First defines the CV (if needed),
+            then applies the restraint.
+        """
+        # Get CV definition
+        cv_labels, cv_commands = self.cv.to_plumed(atoms)
+
+        # Determine restraint label
+        restraint_label = self.label if self.label else f"{self.cv.prefix}_restraint"
+
+        # Build restraint command
+        # PLUMED expects ARG to be comma-separated CV labels
+        arg_str = ",".join(cv_labels)
+        restraint_cmd = f"{restraint_label}: RESTRAINT ARG={arg_str} KAPPA={self.kappa} AT={self.at}"
+
+        # Combine CV commands and restraint
+        commands = cv_commands + [restraint_cmd]
+        return commands
+
+
+# --- WALLS ---
+@dataclasses.dataclass
+class UpperWallBias(BiasProtocol):
+    """Apply an upper wall restraint to a collective variable.
+
+    This class implements the BiasProtocol interface and can be used in the
+    `actions` parameter of MetaDynamicsModel.
+
+    The wall creates a repulsive bias potential that acts when a collective
+    variable exceeds a specified threshold. The wall potential has the form:
+    V(s) = kappa * ((s - at) / offset)^exp  if s > at, else 0
+
+    Parameters
+    ----------
+    cv : CollectiveVariable
+        The collective variable to apply the wall to.
+    at : float
+        The position of the wall (threshold value).
+    kappa : float
+        The force constant of the wall in kJ/mol.
+    exp : int, optional
+        The exponent of the wall potential. Default is 2 (harmonic).
+        Higher values create steeper walls.
+    eps : float, optional
+        A small offset to avoid numerical issues. Default is 0.0.
+    offset : float, optional
+        The offset parameter for the wall. Default is 0.0.
+    label : str, optional
+        A custom label for this wall. If not provided, uses cv.prefix + "_uwall".
+
+    Examples
+    --------
+    >>> import hillclimber as hc
+    >>> # Prevent distance from exceeding 3.0 Å
+    >>> distance_cv = hc.DistanceCV(...)
+    >>> upper_wall = hc.UpperWallBias(cv=distance_cv, at=3.0, kappa=100.0, exp=2)
+
+    Resources
+    ---------
+    - https://www.plumed.org/doc-master/user-doc/html/UPPER_WALLS/
+
+    Notes
+    -----
+    The wall only acts when the CV value exceeds 'at'. The steepness of the
+    wall is controlled by both 'kappa' and 'exp':
+    - exp=2: harmonic wall (smooth)
+    - exp=4,6,...: steeper walls
+    - Higher exp values create harder walls but may cause numerical issues
+    """
+
+    cv: CollectiveVariable
+    at: float
+    kappa: float
+    exp: int = 2
+    eps: float = 0.0
+    offset: float = 0.0
+    label: str | None = None
+
+    def to_plumed(self, atoms: ase.Atoms) -> list[str]:
+        """Generate PLUMED input strings for the upper wall.
+
+        Parameters
+        ----------
+        atoms : ase.Atoms
+            The atomic structure to use for generating the PLUMED string.
+
+        Returns
+        -------
+        list[str]
+            List of PLUMED command strings. First defines the CV (if needed),
+            then applies the upper wall.
+        """
+        # Get CV definition
+        cv_labels, cv_commands = self.cv.to_plumed(atoms)
+
+        # Determine wall label
+        wall_label = self.label if self.label else f"{self.cv.prefix}_uwall"
+
+        # Build wall command
+        arg_str = ",".join(cv_labels)
+        wall_parts = [
+            f"{wall_label}: UPPER_WALLS",
+            f"ARG={arg_str}",
+            f"AT={self.at}",
+            f"KAPPA={self.kappa}",
+            f"EXP={self.exp}",
+        ]
+
+        # Add optional parameters only if non-zero
+        if self.eps != 0.0:
+            wall_parts.append(f"EPS={self.eps}")
+        if self.offset != 0.0:
+            wall_parts.append(f"OFFSET={self.offset}")
+
+        wall_cmd = " ".join(wall_parts)
+
+        # Combine CV commands and wall
+        commands = cv_commands + [wall_cmd]
+        return commands
+
+
+@dataclasses.dataclass
+class LowerWallBias(BiasProtocol):
+    """Apply a lower wall restraint to a collective variable.
+
+    This class implements the BiasProtocol interface and can be used in the
+    `actions` parameter of MetaDynamicsModel.
+
+    The wall creates a repulsive bias potential that acts when a collective
+    variable falls below a specified threshold. The wall potential has the form:
+    V(s) = kappa * ((at - s) / offset)^exp  if s < at, else 0
+
+    Parameters
+    ----------
+    cv : CollectiveVariable
+        The collective variable to apply the wall to.
+    at : float
+        The position of the wall (threshold value).
+    kappa : float
+        The force constant of the wall in kJ/mol.
+    exp : int, optional
+        The exponent of the wall potential. Default is 2 (harmonic).
+        Higher values create steeper walls.
+    eps : float, optional
+        A small offset to avoid numerical issues. Default is 0.0.
+    offset : float, optional
+        The offset parameter for the wall. Default is 0.0.
+    label : str, optional
+        A custom label for this wall. If not provided, uses cv.prefix + "_lwall".
+
+    Examples
+    --------
+    >>> import hillclimber as hc
+    >>> # Prevent distance from going below 1.0 Å
+    >>> distance_cv = hc.DistanceCV(...)
+    >>> lower_wall = hc.LowerWallBias(cv=distance_cv, at=1.0, kappa=100.0, exp=2)
+
+    Resources
+    ---------
+    - https://www.plumed.org/doc-master/user-doc/html/LOWER_WALLS
+
+    Notes
+    -----
+    The wall only acts when the CV value falls below 'at'. The steepness of the
+    wall is controlled by both 'kappa' and 'exp':
+    - exp=2: harmonic wall (smooth)
+    - exp=4,6,...: steeper walls
+    - Higher exp values create harder walls but may cause numerical issues
+    """
+
+    cv: CollectiveVariable
+    at: float
+    kappa: float
+    exp: int = 2
+    eps: float = 0.0
+    offset: float = 0.0
+    label: str | None = None
+
+    def to_plumed(self, atoms: ase.Atoms) -> list[str]:
+        """Generate PLUMED input strings for the lower wall.
+
+        Parameters
+        ----------
+        atoms : ase.Atoms
+            The atomic structure to use for generating the PLUMED string.
+
+        Returns
+        -------
+        list[str]
+            List of PLUMED command strings. First defines the CV (if needed),
+            then applies the lower wall.
+        """
+        # Get CV definition
+        cv_labels, cv_commands = self.cv.to_plumed(atoms)
+
+        # Determine wall label
+        wall_label = self.label if self.label else f"{self.cv.prefix}_lwall"
+
+        # Build wall command
+        arg_str = ",".join(cv_labels)
+        wall_parts = [
+            f"{wall_label}: LOWER_WALLS",
+            f"ARG={arg_str}",
+            f"AT={self.at}",
+            f"KAPPA={self.kappa}",
+            f"EXP={self.exp}",
+        ]
+
+        # Add optional parameters only if non-zero
+        if self.eps != 0.0:
+            wall_parts.append(f"EPS={self.eps}")
+        if self.offset != 0.0:
+            wall_parts.append(f"OFFSET={self.offset}")
+
+        wall_cmd = " ".join(wall_parts)
+
+        # Combine CV commands and wall
+        commands = cv_commands + [wall_cmd]
+        return commands