hillclimber 0.1.6__cp313-cp313-macosx_15_0_x86_64.whl

hillclimber/virtual_atoms.py

@@ -0,0 +1,341 @@
+"""Virtual atom definitions for creating points in space from atom groups.
+
+Virtual atoms reduce groups of atoms to single points (or multiple points, one per group)
+using strategies like center of mass (COM), center of geometry (COG), or first atom.
+
+Resources
+---------
+- https://www.plumed.org/doc-master/user-doc/html/COM
+- https://www.plumed.org/doc-master/user-doc/html/CENTER
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import typing as tp
+
+import ase
+
+from hillclimber.interfaces import AtomSelector
+
+
+@dataclasses.dataclass
+class VirtualAtom:
+    """Creates virtual atom(s) from atom groups.
+
+    Creates ONE virtual atom for EACH group returned by the selector.
+    To select specific groups, use selector indexing before creating the VirtualAtom.
+
+    Parameters
+    ----------
+    atoms : AtomSelector | VirtualAtom
+        Source atoms or nested virtual atoms.
+        Use selector indexing to choose specific groups: VirtualAtom(selector[0], "com")
+    reduction : {"com", "cog", "first", "flatten"}, default="com"
+        How to reduce atoms to points:
+
+        - "com": Center of mass for each group (creates virtual site)
+        - "cog": Center of geometry for each group (creates virtual site)
+        - "first": First atom of each group (no virtual site needed)
+        - "flatten": Combine all groups into one, then apply reduction
+    label : str | None, default=None
+        Optional label for PLUMED virtual site commands.
+
+    Examples
+    --------
+    Create COM for each molecule:
+
+    >>> import hillclimber as hc
+    >>> # Two ethanols → two virtual atoms (COMs)
+    >>> selector = hc.SMARTSSelector("CCO")
+    >>> ethanols = hc.VirtualAtom(selector, reduction="com")
+
+    Select specific virtual atom using selector indexing:
+
+    >>> # Select first ethanol's COM
+    >>> ethanol_0 = hc.VirtualAtom(selector[0], "com")
+
+    Select multiple virtual atoms using selector slicing:
+
+    >>> # Select first two ethanols
+    >>> first_two = hc.VirtualAtom(selector[0:2], "com")
+    >>> # Select every other water
+    >>> water_sel = hc.SMARTSSelector("O")
+    >>> every_other = hc.VirtualAtom(water_sel[::2], "com")
+
+    Select specific virtual atoms using selector list indexing:
+
+    >>> # Select specific ethanols by indices
+    >>> selected = hc.VirtualAtom(selector[[0, 2, 4]], "com")
+
+    Flatten all groups into one virtual atom:
+
+    >>> # All water oxygens → one COM
+    >>> all_waters = hc.VirtualAtom(hc.SMARTSSelector("O"), reduction="flatten")
+
+    Nested virtual atoms (COM of COMs):
+
+    >>> # First: create COM for each water
+    >>> water_coms = hc.VirtualAtom(hc.SMARTSSelector("O"), reduction="com")
+    >>> # Then: create COM of all those COMs
+    >>> center = hc.VirtualAtom(water_coms, reduction="flatten")
+
+    Use in distance CVs:
+
+    >>> # Single distance (using selector indexing)
+    >>> ethanol_sel = hc.SMARTSSelector("CCO")
+    >>> water_sel = hc.SMARTSSelector("O")
+    >>> dist = hc.DistanceCV(
+    ...     x1=hc.VirtualAtom(ethanol_sel[0], "com"),
+    ...     x2=hc.VirtualAtom(water_sel[0], "com"),
+    ...     prefix="d"
+    ... )
+    >>>
+    >>> # Multiple distances (first ethanol to all waters)
+    >>> dist = hc.DistanceCV(
+    ...     x1=hc.VirtualAtom(ethanol_sel[0], "com"),
+    ...     x2=hc.VirtualAtom(water_sel, "com"),
+    ...     prefix="d"
+    ... )
+    >>>
+    >>> # Multiple distances (first two ethanols to first three waters)
+    >>> dist = hc.DistanceCV(
+    ...     x1=hc.VirtualAtom(ethanol_sel[0:2], "com"),
+    ...     x2=hc.VirtualAtom(water_sel[0:3], "com"),
+    ...     prefix="d"
+    ... )
+    >>>
+    >>> # All pairwise distances
+    >>> dist = hc.DistanceCV(
+    ...     x1=hc.VirtualAtom(water_sel, "com"),
+    ...     x2=hc.VirtualAtom(water_sel, "com"),
+    ...     prefix="d"
+    ... )
+
+    Resources
+    ---------
+    - https://www.plumed.org/doc-master/user-doc/html/COM
+    - https://www.plumed.org/doc-master/user-doc/html/CENTER
+    """
+
+    atoms: AtomSelector | "VirtualAtom"
+    reduction: tp.Literal["com", "cog", "first", "flatten"] = "com"
+    label: str | None = None
+
+    def __add__(self, other: "VirtualAtom") -> "VirtualAtom":
+        """Combine two VirtualAtoms.
+
+        Returns a new VirtualAtom that represents both sets of virtual sites.
+        The underlying selectors are combined using the selector's __add__ method.
+
+        Parameters
+        ----------
+        other : VirtualAtom
+            Another VirtualAtom to combine with this one.
+
+        Returns
+        -------
+        VirtualAtom
+            New VirtualAtom with combined underlying selectors.
+
+        Raises
+        ------
+        ValueError
+            If the two VirtualAtoms have different reduction strategies.
+
+        Examples
+        --------
+        >>> water_coms = hc.VirtualAtom(water_sel, "com")
+        >>> ethanol_coms = hc.VirtualAtom(ethanol_sel, "com")
+        >>> all_coms = water_coms + ethanol_coms
+        >>>
+        >>> # Combine with indexed selectors
+        >>> first_water = hc.VirtualAtom(water_sel[0], "com")
+        >>> first_ethanol = hc.VirtualAtom(ethanol_sel[0], "com")
+        >>> combined = first_water + first_ethanol  # 2 COMs
+        """
+        # Reduction must be the same
+        if self.reduction != other.reduction:
+            raise ValueError(
+                f"Cannot combine VirtualAtoms with different reductions: "
+                f"{self.reduction} vs {other.reduction}"
+            )
+
+        # Combine the underlying selectors
+        combined_atoms = self.atoms + other.atoms
+
+        return VirtualAtom(
+            atoms=combined_atoms,
+            reduction=self.reduction,
+            label=None,  # Reset label for combined VirtualAtom
+        )
+
+    def select(self, atoms: ase.Atoms) -> list[list[int]]:
+        """Select atom groups for virtual atom creation.
+
+        Returns list of atom groups. Each group represents the atoms for
+        one virtual site.
+
+        Parameters
+        ----------
+        atoms : ase.Atoms
+            The atomic structure to select from.
+
+        Returns
+        -------
+        list[list[int]]
+            Groups of atom indices. Each inner list is one group.
+        """
+        # Get groups from source
+        if isinstance(self.atoms, VirtualAtom):
+            # Nested: inner VirtualAtom returns groups
+            groups = self.atoms.select(atoms)
+        else:
+            groups = self.atoms.select(atoms)
+
+        # Apply reduction strategy
+        if self.reduction == "flatten":
+            # Combine all groups into one
+            flat = [idx for group in groups for idx in group]
+            return [flat]
+        else:
+            # com, cog, first: keep groups separate
+            # Actual point creation happens in to_plumed()
+            return groups
+
+    def to_plumed(self, atoms: ase.Atoms) -> tuple[list[str], list[str]]:
+        """Generate PLUMED virtual site commands.
+
+        Handles nested VirtualAtoms by first generating commands for the inner
+        VirtualAtom, then using those labels to create the outer virtual site.
+
+        Parameters
+        ----------
+        atoms : ase.Atoms
+            The atomic structure to use for generating commands.
+
+        Returns
+        -------
+        labels : list[str]
+            Labels for the virtual sites/atoms created. These can be used
+            in subsequent PLUMED commands.
+        commands : list[str]
+            PLUMED command strings for creating virtual sites.
+            Empty if reduction="first" (no virtual sites needed).
+
+        Examples
+        --------
+        >>> va = hc.VirtualAtom(hc.SMARTSSelector("O"), reduction="com")
+        >>> labels, commands = va.to_plumed(atoms)
+        >>> print(labels)
+        ['vsite_123_0', 'vsite_123_1']
+        >>> print(commands)
+        ['vsite_123_0: COM ATOMS=1,2,3', 'vsite_123_1: COM ATOMS=4,5,6']
+
+        >>> # Nested VirtualAtom (COM of COMs)
+        >>> water_coms = hc.VirtualAtom(water_sel, "com")
+        >>> center = hc.VirtualAtom(water_coms, "com")
+        >>> labels, commands = center.to_plumed(atoms)
+        >>> # Commands will include both the individual COMs and the center COM
+        """
+        # Check if this is a nested VirtualAtom
+        if isinstance(self.atoms, VirtualAtom):
+            # First, generate commands for the inner VirtualAtom
+            inner_labels, inner_commands = self.atoms.to_plumed(atoms)
+
+            # Now create virtual site using the inner labels
+            commands = list(inner_commands)  # Copy inner commands
+            labels = []
+
+            if self.reduction == "first":
+                # Just use the first inner label
+                labels = [inner_labels[0]]
+            elif self.reduction == "flatten":
+                # Create COM/COG of all inner virtual sites
+                base_label = self.label or f"vsite_{id(self)}"
+                cmd_type = "COM" if self.reduction == "com" else "CENTER"
+                atom_list = ",".join(inner_labels)
+                commands.append(f"{base_label}: {cmd_type} ATOMS={atom_list}")
+                labels = [base_label]
+            elif self.reduction in ["com", "cog"]:
+                # For COM/COG with nested VirtualAtoms, we create a single
+                # virtual site from all inner labels (similar to flatten)
+                base_label = self.label or f"vsite_{id(self)}"
+                cmd_type = "COM" if self.reduction == "com" else "CENTER"
+                atom_list = ",".join(inner_labels)
+                commands.append(f"{base_label}: {cmd_type} ATOMS={atom_list}")
+                labels = [base_label]
+            else:
+                # This shouldn't typically happen, but handle it
+                # Just pass through the inner labels
+                labels = inner_labels
+
+            return labels, commands
+
+        # Non-nested case: regular selector
+        groups = self.select(atoms)
+        labels = []
+        commands = []
+
+        for i, group in enumerate(groups):
+            if self.reduction == "first" or (
+                self.reduction == "flatten" and len(group) == 1
+            ):
+                # No virtual site needed, use atom index directly
+                labels.append(str(group[0] + 1))
+            else:
+                # Create virtual site (COM or CENTER)
+                base_label = self.label or f"vsite_{id(self)}"
+                label = base_label if len(groups) == 1 else f"{base_label}_{i}"
+
+                cmd_type = "COM" if self.reduction == "com" else "CENTER"
+                atom_list = ",".join(str(idx + 1) for idx in group)
+                commands.append(f"{label}: {cmd_type} ATOMS={atom_list}")
+                labels.append(label)
+
+        return labels, commands
+
+    def count(self, atoms: ase.Atoms) -> int:
+        """Return number of virtual atoms this represents.
+
+        Parameters
+        ----------
+        atoms : ase.Atoms
+            The atomic structure to count groups in.
+
+        Returns
+        -------
+        int
+            Number of virtual atoms (groups) this will create.
+
+        Examples
+        --------
+        >>> water_sel = hc.SMARTSSelector("O")
+        >>> va = hc.VirtualAtom(water_sel, reduction="com")
+        >>> va.count(atoms)  # Number of water molecules
+        3
+        >>> # Use selector indexing to get single group
+        >>> va_single = hc.VirtualAtom(water_sel[0], reduction="com")
+        >>> va_single.count(atoms)  # Single water - always 1
+        1
+        >>> va_flat = hc.VirtualAtom(water_sel, reduction="flatten")
+        >>> va_flat.count(atoms)  # Flattened - always 1
+        1
+        >>> # Nested VirtualAtom
+        >>> water_coms = hc.VirtualAtom(water_sel, "com")  # 3 COMs
+        >>> center = hc.VirtualAtom(water_coms, "com")  # 1 COM of 3 COMs
+        >>> center.count(atoms)
+        1
+        """
+        # For nested VirtualAtoms with com/cog/flatten reduction, we create a single virtual site
+        if isinstance(self.atoms, VirtualAtom) and self.reduction in [
+            "com",
+            "cog",
+            "flatten",
+        ]:
+            return 1
+        # For nested VirtualAtoms with "first" reduction, pass through
+        elif isinstance(self.atoms, VirtualAtom) and self.reduction == "first":
+            return 1
+        # For non-nested or other cases, count the groups
+        return len(self.select(atoms))

hillclimber-0.1.6.dist-info/METADATA

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: hillclimber
+Version: 0.1.6
+Summary: Python interfaces for the plumed library with enhanced sampling.
+License: 		   GNU LESSER GENERAL PUBLIC LICENSE
+                               Version 3, 29 June 2007
+        
+         Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+         Everyone is permitted to copy and distribute verbatim copies
+         of this license document, but changing it is not allowed.
+        
+        
+          This version of the GNU Lesser General Public License incorporates
+        the terms and conditions of version 3 of the GNU General Public
+        License, supplemented by the additional permissions listed below.
+        
+          0. Additional Definitions. 
+        
+          As used herein, "this License" refers to version 3 of the GNU Lesser
+        General Public License, and the "GNU GPL" refers to version 3 of the GNU
+        General Public License.
+        
+          "The Library" refers to a covered work governed by this License,
+        other than an Application or a Combined Work as defined below.
+        
+          An "Application" is any work that makes use of an interface provided
+        by the Library, but which is not otherwise based on the Library.
+        Defining a subclass of a class defined by the Library is deemed a mode
+        of using an interface provided by the Library.
+        
+          A "Combined Work" is a work produced by combining or linking an
+        Application with the Library.  The particular version of the Library
+        with which the Combined Work was made is also called the "Linked
+        Version".
+        
+          The "Minimal Corresponding Source" for a Combined Work means the
+        Corresponding Source for the Combined Work, excluding any source code
+        for portions of the Combined Work that, considered in isolation, are
+        based on the Application, and not on the Linked Version.
+        
+          The "Corresponding Application Code" for a Combined Work means the
+        object code and/or source code for the Application, including any data
+        and utility programs needed for reproducing the Combined Work from the
+        Application, but excluding the System Libraries of the Combined Work.
+        
+          1. Exception to Section 3 of the GNU GPL.
+        
+          You may convey a covered work under sections 3 and 4 of this License
+        without being bound by section 3 of the GNU GPL.
+        
+          2. Conveying Modified Versions.
+        
+          If you modify a copy of the Library, and, in your modifications, a
+        facility refers to a function or data to be supplied by an Application
+        that uses the facility (other than as an argument passed when the
+        facility is invoked), then you may convey a copy of the modified
+        version:
+        
+           a) under this License, provided that you make a good faith effort to
+           ensure that, in the event an Application does not supply the
+           function or data, the facility still operates, and performs
+           whatever part of its purpose remains meaningful, or
+        
+           b) under the GNU GPL, with none of the additional permissions of
+           this License applicable to that copy.
+        
+          3. Object Code Incorporating Material from Library Header Files.
+        
+          The object code form of an Application may incorporate material from
+        a header file that is part of the Library.  You may convey such object
+        code under terms of your choice, provided that, if the incorporated
+        material is not limited to numerical parameters, data structure
+        layouts and accessors, or small macros, inline functions and templates
+        (ten or fewer lines in length), you do both of the following:
+        
+           a) Give prominent notice with each copy of the object code that the
+           Library is used in it and that the Library and its use are
+           covered by this License.
+        
+           b) Accompany the object code with a copy of the GNU GPL and this license
+           document.
+        
+          4. Combined Works.
+        
+          You may convey a Combined Work under terms of your choice that,
+        taken together, effectively do not restrict modification of the
+        portions of the Library contained in the Combined Work and reverse
+        engineering for debugging such modifications, if you also do each of
+        the following:
+        
+           a) Give prominent notice with each copy of the Combined Work that
+           the Library is used in it and that the Library and its use are
+           covered by this License.
+        
+           b) Accompany the Combined Work with a copy of the GNU GPL and this license
+           document.
+        
+           c) For a Combined Work that displays copyright notices during
+           execution, include the copyright notice for the Library among
+           these notices, as well as a reference directing the user to the
+           copies of the GNU GPL and this license document.
+        
+           d) Do one of the following:
+        
+               0) Convey the Minimal Corresponding Source under the terms of this
+               License, and the Corresponding Application Code in a form
+               suitable for, and under terms that permit, the user to
+               recombine or relink the Application with a modified version of
+               the Linked Version to produce a modified Combined Work, in the
+               manner specified by section 6 of the GNU GPL for conveying
+               Corresponding Source.
+        
+               1) Use a suitable shared library mechanism for linking with the
+               Library.  A suitable mechanism is one that (a) uses at run time
+               a copy of the Library already present on the user's computer
+               system, and (b) will operate properly with a modified version
+               of the Library that is interface-compatible with the Linked
+               Version. 
+        
+           e) Provide Installation Information, but only if you would otherwise
+           be required to provide such information under section 6 of the
+           GNU GPL, and only to the extent that such information is
+           necessary to install and execute a modified version of the
+           Combined Work produced by recombining or relinking the
+           Application with a modified version of the Linked Version. (If
+           you use option 4d0, the Installation Information must accompany
+           the Minimal Corresponding Source and Corresponding Application
+           Code. If you use option 4d1, you must provide the Installation
+           Information in the manner specified by section 6 of the GNU GPL
+           for conveying Corresponding Source.)
+        
+          5. Combined Libraries.
+        
+          You may place library facilities that are a work based on the
+        Library side by side in a single library together with other library
+        facilities that are not Applications and are not covered by this
+        License, and convey such a combined library under terms of your
+        choice, if you do both of the following:
+        
+           a) Accompany the combined library with a copy of the same work based
+           on the Library, uncombined with any other library facilities,
+           conveyed under the terms of this License.
+        
+           b) Give prominent notice with the combined library that part of it
+           is a work based on the Library, and explaining where to find the
+           accompanying uncombined form of the same work.
+        
+          6. Revised Versions of the GNU Lesser General Public License.
+        
+          The Free Software Foundation may publish revised and/or new versions
+        of the GNU Lesser General Public License from time to time. Such new
+        versions will be similar in spirit to the present version, but may
+        differ in detail to address new problems or concerns.
+        
+          Each version is given a distinguishing version number. If the
+        Library as you received it specifies that a certain numbered version
+        of the GNU Lesser General Public License "or any later version"
+        applies to it, you have the option of following the terms and
+        conditions either of that published version or of any later version
+        published by the Free Software Foundation. If the Library as you
+        received it does not specify a version number of the GNU Lesser
+        General Public License, you may choose any version of the GNU Lesser
+        General Public License ever published by the Free Software Foundation.
+        
+          If the Library as you received it specifies that a proxy can decide
+        whether future versions of the GNU Lesser General Public License shall
+        apply, that proxy's public statement of acceptance of any version is
+        permanent authorization for you to choose that version for the
+        Library.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: ase>=3.25.0
+Requires-Dist: metadynminer>=0.9.1
+Requires-Dist: molify>=0.2.0
+Requires-Dist: rdkit2ase>=0.1.13
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: zntrack>=0.8.9
+Description-Content-Type: text/markdown
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zincware/hillclimber)
+
+# hillclimber
+
+
+**hillclimber** is a Python framework for enhanced sampling with PLUMED. It provides high-level, Pythonic interfaces for configuring metadynamics simulations, making it easy to explore rare events and climb energy barriers in molecular dynamics simulations.
+
+## Installation
+
+```bash
+uv add hillclimber
+```
+
+Or with pip:
+
+```bash
+pip install hillclimber
+```
+
+## Units
+
+hillclimber uses **ASE units** throughout the package:
+
+- **Distances**: Ångström / Å
+- **Energies**: electronvolt / eV
+- **Time**: femtoseconds / fs
+- **Temperature**: Kelvin / K
+
+## Python Collective Variables (PyCV)
+
+hillclimber supports custom Python-based collective variables through PLUMED's `PYCVINTERFACE`. This allows you to define arbitrary CVs in Python with full access to atomic coordinates and gradients.
+
+### Defining a PyCV
+
+Create a subclass of `PyCV` with a `compute` method:
+
+```python
+# cv.py
+import numpy as np
+from ase import Atoms
+from hillclimber.pycv import PyCV
+
+
+class DistanceCV(PyCV):
+    """Custom distance CV between two atoms."""
+
+    atoms: list[int]  # Atom indices to use
+
+    def compute(self, atoms: Atoms) -> tuple[float, np.ndarray]:
+        """Compute CV value and gradients.
+
+        Parameters
+        ----------
+        atoms : Atoms
+            ASE Atoms object with current positions.
+
+        Returns
+        -------
+        tuple[float, np.ndarray]
+            CV value and gradients array of shape (n_atoms, 3).
+        """
+        positions = atoms.get_positions()
+        diff = positions[self.atoms[1]] - positions[self.atoms[0]]
+        distance = float(np.linalg.norm(diff))
+
+        # Compute gradients
+        grad = np.zeros((len(atoms), 3))
+        grad[self.atoms[0]] = -diff / distance
+        grad[self.atoms[1]] = diff / distance
+
+        return distance, grad
+```
+
+### Using PyCV with ZnTrack
+
+PyCV integrates seamlessly with ZnTrack workflows:
+
+```python
+# main.py
+import zntrack
+import ipsuite as ips
+import hillclimber as hc
+from cv import DistanceCV  # Import from standalone module
+
+
+# Define your model (e.g., MACE, LJ, etc.)
+class MyModel(zntrack.Node):
+    def get_calculator(self, **kwargs):
+        # Return your ASE calculator
+        ...
+
+
+project = zntrack.Project()
+
+with project:
+    data = ...  # Your data node providing atoms
+
+    # Create the PyCV
+    cv = DistanceCV(atoms=[0, 1], prefix="dist")
+
+    # Configure the bias
+    bias = hc.MetadBias(
+        cv=cv,
+        sigma=0.1,
+        grid_min=2.0,
+        grid_max=6.0,
+        grid_bin=100,
+    )
+
+    # Configure metadynamics
+    config = hc.MetaDynamicsConfig(
+        height=0.01,
+        pace=10,
+        temp=300.0,
+    )
+
+    # Create the biased model
+    metad = hc.MetaDynamicsModel(
+        config=config,
+        data=data.frames,
+        bias_cvs=[bias],
+        model=MyModel(),
+    )
+
+    # Run MD with ipsuite
+    md = ips.ASEMD(
+        data=data.frames,
+        data_ids=-1,
+        model=metad,
+        thermostat=ips.LangevinThermostat(
+            temperature=300.0,
+            friction=0.01,
+            time_step=1.0,
+        ),
+        steps=1000,
+        sampling_rate=10,
+    )
+
+project.repro()
+```
+
+**Important**: The PyCV class should be defined in a standalone module (not `__main__`) that can be imported by PLUMED's Python interface. The module should only import what's necessary for the CV computation to avoid import issues in the PLUMED subprocess.
+
+## Documentation
+
+Currently, there is no documentation available. Please refer to `/examples` for usage examples.