{"id":46146492,"url":"https://github.com/zincware/hillclimber","last_synced_at":"2026-03-02T07:32:02.221Z","repository":{"id":322399668,"uuid":"1040170856","full_name":"zincware/hillclimber","owner":"zincware","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-12T16:25:21.000Z","size":1047,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T19:10:13.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zincware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-18T15:02:55.000Z","updated_at":"2026-01-12T16:25:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zincware/hillclimber","commit_stats":null,"previous_names":["zincware/hillclimber"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zincware/hillclimber","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2Fhillclimber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2Fhillclimber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2Fhillclimber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2Fhillclimber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zincware","download_url":"https://codeload.github.com/zincware/hillclimber/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2Fhillclimber/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29995000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-02T07:31:59.707Z","updated_at":"2026-03-02T07:32:02.216Z","avatar_url":"https://github.com/zincware.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zincware/hillclimber)\n\n# hillclimber\n\n\n**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.\n\n## Installation\n\n```bash\nuv add hillclimber\n```\n\nOr with pip:\n\n```bash\npip install hillclimber\n```\n\n## Units\n\nhillclimber uses **ASE units** throughout the package:\n\n- **Distances**: Ångström / Å\n- **Energies**: electronvolt / eV\n- **Time**: femtoseconds / fs\n- **Temperature**: Kelvin / K\n\n## Python Collective Variables (PyCV)\n\nhillclimber 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.\n\n### Defining a PyCV\n\nCreate a subclass of `PyCV` with a `compute` method:\n\n```python\n# cv.py\nimport numpy as np\nfrom ase import Atoms\nfrom hillclimber.pycv import PyCV\n\n\nclass DistanceCV(PyCV):\n    \"\"\"Custom distance CV between first two selected atoms.\"\"\"\n\n    def compute(self, atoms: Atoms) -\u003e tuple[float, np.ndarray]:\n        \"\"\"Compute CV value and gradients.\n\n        Parameters\n        ----------\n        atoms : Atoms\n            ASE Atoms object containing ONLY the selected atoms.\n            Indices start at 0 and go up to len(atoms) - 1.\n\n        Returns\n        -------\n        tuple[float, np.ndarray]\n            CV value and gradients array of shape (n_atoms, 3).\n        \"\"\"\n        positions = atoms.get_positions()\n        diff = positions[1] - positions[0]\n        distance = float(np.linalg.norm(diff))\n\n        # Compute gradients for the selected atoms\n        grad = np.zeros((len(atoms), 3))\n        grad[0] = -diff / distance\n        grad[1] = diff / distance\n\n        return distance, grad\n```\n\n### Atom Selection Options\n\nThe `atoms` parameter in PyCV accepts three types of input:\n\n```python\n# Option 1: Direct indices (0-based)\ncv = DistanceCV(atoms=[0, 1], prefix=\"dist\")\n\n# Option 2: None to select all atoms\ncv = DistanceCV(atoms=None, prefix=\"dist_all\")\n\n# Option 3: AtomSelector for dynamic selection\nimport hillclimber as hc\n\ncv = DistanceCV(atoms=hc.HeavyAtomSelector(), prefix=\"heavy\")\ncv = DistanceCV(atoms=hc.ElementSelector(symbols=[\"C\", \"O\"]), prefix=\"co\")\ncv = DistanceCV(atoms=hc.SMARTSSelector(pattern=\"[OH]\"), prefix=\"oh\")\n```\n\n**Important**: In your `compute()` method:\n- The `atoms` parameter is an ASE Atoms object containing **only the selected atoms** (not the full system). Indices in this object start at 0.\n- `self.atoms` is still your original selector/list/None if you need to access it for any reason.\n\n### Using PyCV with ZnTrack\n\nPyCV integrates seamlessly with ZnTrack workflows:\n\n```python\n# main.py\nimport zntrack\nimport ipsuite as ips\nimport hillclimber as hc\nfrom cv import DistanceCV  # Import from standalone module\n\n\n# Define your model (e.g., MACE, LJ, etc.)\nclass MyModel(zntrack.Node):\n    def get_calculator(self, **kwargs):\n        # Return your ASE calculator\n        ...\n\n\nproject = zntrack.Project()\n\nwith project:\n    data = ...  # Your data node providing atoms\n\n    # Create the PyCV\n    cv = DistanceCV(atoms=[0, 1], prefix=\"dist\")\n\n    # Configure the bias\n    bias = hc.MetadBias(\n        cv=cv,\n        sigma=0.1,\n        grid_min=2.0,\n        grid_max=6.0,\n        grid_bin=100,\n    )\n\n    # Configure metadynamics\n    config = hc.MetaDynamicsConfig(\n        height=0.01,\n        pace=10,\n        temp=300.0,\n    )\n\n    # Create the biased model\n    metad = hc.MetaDynamicsModel(\n        config=config,\n        data=data.frames,\n        bias_cvs=[bias],\n        model=MyModel(),\n    )\n\n    # Run MD with ipsuite\n    md = ips.ASEMD(\n        data=data.frames,\n        data_ids=-1,\n        model=metad,\n        thermostat=ips.LangevinThermostat(\n            temperature=300.0,\n            friction=0.01,\n            time_step=1.0,\n        ),\n        steps=1000,\n        sampling_rate=10,\n    )\n\nproject.repro()\n```\n\n**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.\n\n## Documentation\n\nCurrently, there is no documentation available. Please refer to `/examples` for usage examples.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzincware%2Fhillclimber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzincware%2Fhillclimber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzincware%2Fhillclimber/lists"}