hillclimber 0.1.0a1__tar.gz → 0.1.0a3__tar.gz

hillclimber-0.1.0a3/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "Bash(find:*)",
+      "Bash(uv run pytest:*)",
+      "WebFetch(domain:www.plumed.org)",
+      "WebSearch",
+      "Bash(uv run:*)",
+      "WebFetch(domain:www.plumed-nest.org)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

{hillclimber-0.1.0a1 → hillclimber-0.1.0a3}/.gitignore

@@ -9,3 +9,4 @@ wheels/
 # Virtual environments
 .venv
 *.local
+tmp/

hillclimber-0.1.0a3/AGENTS.md

@@ -0,0 +1,32 @@
+# Hillclimber
+A Python wrapper around PLUMED.
+
+This package uses numpy style docstrings and type hinting.
+Use `t.Literal[]` instead of plain strings for fixed options.
+To run tests, use `uv run pytest tests/`.
+There must be unit tests added for all new functionality!
+The test should expect the full output like
+```
+expected = [
+        "d12_g1_0_com: COM ATOMS=1,2,3,4,5,6,7,8,9",
+        "d12_g2_0_com: COM ATOMS=19,20,21",
+        "d12: DISTANCE ATOMS=d12_g1_0_com,d12_g2_0_com",
+    ]
+
+assert plumed_str == expected
+```
+and not just parts of it, e.g.
+```
+assert any("COM ATOMS=1,2,3,4,5,6,7,8,9" in cmd for cmd in plumed_str)
+```
+
+The goal of the package is to provide abstractions for collective variables and biases and to interface with ASE and ZnTrack.
+
+The package uses ASE units, e.g. distances are in Angstrom, energies in eV and time in fs.
+If available, reference the `https://www.plumed.org/doc-master/user-doc/html/` inside the docstrings to get more information about the underlying PLUMED functionality!
+
+This is a new package, backwards compatibility is not required!
+Make design decisions for good code structure and usability, not for backwards compatibility!
+Use KISS, DRY, SOLID and YAGNI principles.
+
+Ask before you create or plan summary documents!

hillclimber-0.1.0a3/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

hillclimber-0.1.0a3/Getting_started.md

@@ -0,0 +1,253 @@
+# 🚀 HillClimber Quick Start Guide
+
+Selectors pick atoms.
+VirtualAtoms reduce groups (COM/COG).
+CVs measure things (distance, coordination, etc.).
+
+Three clean layers, one clear mental model. 🧠
+
+---
+
+## 1. Selectors — "Pick What You Want"
+
+Selectors identify groups of atoms in your system.
+Every selector returns a list of groups, each a list of atom indices:
+
+[[atoms_of_group_0], [atoms_of_group_1], ...]
+
+**Example:**
+
+```python
+ethanol_sel = hc.SMARTSSelector("CCO")  # Matches 2 ethanols
+water_sel = hc.SMARTSSelector("O")      # Matches 3 waters
+```
+
+---
+
+### Indexing — Two Levels Deep
+
+- **Level 1:** Pick which groups
+- **Level 2:** Pick which atoms within those groups
+
+| Syntax | Meaning |
+|--------|---------|
+| `sel` | All groups |
+| `sel[0]` | First group |
+| `sel[0:2]` | First two groups |
+| `sel[[0, 2]]` | Groups 0 and 2 |
+| `sel[:][0]` | First atom of each group |
+| `sel[0][0]` | First atom of the first group |
+
+```python
+# First oxygen of each water
+oxygens = water_sel[:][0]
+
+# First two waters only
+first_two = water_sel[0:2]
+```
+
+---
+
+### Combining Selectors
+
+Combine any selectors using `+`:
+
+```python
+all_mols = water_sel + ethanol_sel
+```
+
+→ "Select all waters and ethanols."
+
+---
+
+## 2. VirtualAtoms — "Reduce to COM/COG"
+
+A VirtualAtom creates virtual sites (e.g., centers of mass).
+
+**Key concept:** One virtual site per group in the selector.
+
+```python
+water_coms = hc.VirtualAtom(water_sel, "com")  # 3 COMs
+ethanol_coms = hc.VirtualAtom(ethanol_sel, "com")  # 2 COMs
+```
+
+### Common Patterns
+
+| Code | Meaning |
+|------|---------|
+| `VirtualAtom(sel, "com")` | COM of each group |
+| `VirtualAtom(sel[0], "com")` | COM of the first group only |
+| `VirtualAtom(va, "com")` | COM of COMs (nested) |
+| `va1 + va2` | Combine multiple COM sets |
+
+**Example:**
+
+```python
+# COM for each water
+water_coms = hc.VirtualAtom(water_sel, "com")
+
+# COM for ethanol[0]
+ethanol_0_com = hc.VirtualAtom(ethanol_sel[0], "com")
+
+# Combine both
+all_coms = ethanol_0_com + water_coms
+```
+
+💡 **Important:** Indexing happens at the selector, not the VirtualAtom.
+
+---
+
+## 3. CVs — "Measure Things Between Groups or COMs"
+
+CVs use Selectors or VirtualAtoms as inputs.
+
+### DistanceCV
+
+Measures distances between atom groups or virtual sites.
+
+```python
+# Distance between ethanol[0] COM and water[0] COM
+dist = hc.DistanceCV(
+    x1=hc.VirtualAtom(ethanol_sel[0], "com"),
+    x2=hc.VirtualAtom(water_sel[0], "com"),
+    prefix="d_com"
+)
+```
+
+**One-to-Many / Many-to-Many:**
+
+```python
+# Distance from one ethanol to each water
+dist = hc.DistanceCV(
+    x1=hc.VirtualAtom(ethanol_sel[0], "com"),
+    x2=hc.VirtualAtom(water_sel, "com"),
+)
+# → Creates 3 CVs: d_0, d_1, d_2
+```
+
+---
+
+### CoordinationCV
+
+Measures how "close" groups are — like solvation or clustering.
+
+```python
+cn = hc.CoordinationCV(
+    x1=hc.VirtualAtom(water_sel, "com"),
+    x2=hc.VirtualAtom(water_sel, "com"),
+    r_0=5.0,
+    prefix="cn_water"
+)
+# → One CV: coordination among all water COMs
+```
+
+---
+
+### Flattening
+
+Controls whether multi-atom groups are flattened or grouped in PLUMED:
+
+| Option | Effect | PLUMED Output |
+|--------|--------|---------------|
+| `flatten=True` | Atoms merged into one list | `DISTANCE ATOMS=1,2,3,4` |
+| `flatten=False` | Each group becomes a GROUP | `G1: GROUP ATOMS=...` |
+
+```python
+dist = hc.DistanceCV(
+    x1=water_sel[0],
+    x2=ethanol_sel[0],
+    flatten=False
+)
+```
+
+---
+
+## 4. Quick Visual Cheat Sheet
+
+```
+Selector      → picks atoms or groups
+                e.g. water_sel[0:2]
+
+VirtualAtom   → reduces groups (COM/COG)
+                e.g. VirtualAtom(water_sel, "com")
+
+CV            → measures between selectors or virtual sites
+                e.g. DistanceCV(x1, x2)
+```
+
+---
+
+## 5. Common Real-World Examples
+
+| Goal | Code | Output |
+|------|------|--------|
+| Distance between two specific atoms | `hc.DistanceCV(x1=sel1[0][0], x2=sel2[0][0])` | `DISTANCE ATOMS=1,2` |
+| Distance between molecule COMs | `hc.DistanceCV(x1=hc.VirtualAtom(sel1[0],"com"), x2=hc.VirtualAtom(sel2[0],"com"))` | `COM ATOMS=...` |
+| Distance from one COM to all COMs | `hc.DistanceCV(x1=va1[0], x2=va2)` | Multiple CVs |
+| Coordination between all COMs | `hc.CoordinationCV(x1=va, x2=va, r_0=5.0)` | One CN CV |
+| COM of COMs (e.g., cluster center) | `hc.VirtualAtom(hc.VirtualAtom(sel, "com"), "com")` | Single virtual site |
+
+---
+
+## 6. Mental Model
+
+| You Think | You Write | PLUMED Thinks |
+|-----------|-----------|---------------|
+| "Select these atoms" | `selector` | atom indices |
+| "Group them by molecule" | `selector[0:2]` | grouped atoms |
+| "Compute their COM" | `VirtualAtom(selector, "com")` | `COM ATOMS=...` |
+| "Measure a distance" | `DistanceCV(x1, x2)` | `DISTANCE ATOMS=...` |
+| "Compute coordination" | `CoordinationCV(x1, x2)` | `COORDINATION GROUPA=...,GROUPB=...` |
+
+---
+
+## 7. Golden Rules
+
+1. **Selectors select.**
+   - Always use selectors for picking atoms and groups.
+2. **VirtualAtoms reduce.**
+   - Use them only for COM/COG — never for indexing.
+3. **CVs measure.**
+   - They combine selectors or virtual sites to produce observables.
+4. **Index at the selector level.**
+   - e.g., `VirtualAtom(sel[0], "com")`, not `VirtualAtom(sel, "com")[0]`.
+5. **Combine with `+`.**
+   - `sel1 + sel2` or `va1 + va2` to merge sets.
+6. **Flatten mindfully.**
+   - `flatten=True` → single atom list
+   - `flatten=False` → PLUMED GROUPs
+
+---
+
+## 8. Typical PLUMED Translations
+
+| Python Expression | PLUMED Output |
+|-------------------|---------------|
+| `hc.VirtualAtom(water_sel, "com")` | `water_0_com: COM ATOMS=...` |
+| `hc.DistanceCV(x1=va1, x2=va2)` | `DISTANCE ATOMS=va1_0,va2_0` |
+| `hc.CoordinationCV(x1=va, x2=va, r_0=5.0)` | `COORDINATION GROUPA=va_0,... GROUPB=va_0,... R_0=5.0` |
+
+---
+
+## 9. Summary of Best Practices
+
+| Task | Recommended Approach |
+|------|---------------------|
+| Select atoms or molecules | SMARTSSelector, use indexing |
+| Combine multiple groups | `sel1 + sel2` |
+| Create COM/COG | `VirtualAtom(sel, "com" / "cog")` |
+| Compute distances | `DistanceCV(x1, x2)` |
+| Compute coordination numbers | `CoordinationCV(x1, x2)` |
+| Preserve group structure | `flatten=False` |
+| Build hierarchical centers | `VirtualAtom(VirtualAtom(sel, "com"), "com")` |
+
+---
+
+## TL;DR
+
+Think modular:
+- **Selectors** → choose what
+- **VirtualAtoms** → define where
+- **CVs** → measure how
+
+No hidden behavior. No implicit COMs. Just clean, explicit, composable logic — fully PLUMED-compatible.

{hillclimber-0.1.0a1 → hillclimber-0.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hillclimber
-Version: 0.1.0a1
+Version: 0.1.0a3
 Summary: Python interfaces for the plumed library with enhanced sampling.
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -124,6 +124,64 @@ with project:
 project.build()
 ```
 
+## Units
+
+hillclimber uses **ASE units** throughout the package:
+
+- **Distances**: Ångström (Å)
+- **Energies**: electronvolt (eV)
+- **Time**: femtoseconds (fs)
+- **Temperature**: Kelvin (K)
+- **Mass**: atomic mass units (amu)
+
+### Unit Conversion with PLUMED
+
+PLUMED internally uses different units (nm, kJ/mol, ps). hillclimber automatically handles the conversion by adding a `UNITS` line to the PLUMED input:
+
+```
+UNITS LENGTH=A TIME=0.001 ENERGY=96.48533288249877
+```
+
+This tells PLUMED to interpret all input parameters in ASE units:
+- `LENGTH=A`: Distances are in Ångström
+- `TIME=0.001`: Time values are in fs (1 fs = 0.001 ps)
+- `ENERGY=96.485`: Energies are in eV (1 eV = 96.485 kJ/mol)
+
+**All PLUMED parameters (HEIGHT, BARRIER, KAPPA, SIGMA, etc.) should be specified in ASE units (eV, Å, fs).** The UNITS line ensures PLUMED interprets them correctly.
+
+### Example with Units
+
+```python
+config = hc.MetaDynamicsConfig(
+    height=0.5,        # eV - Gaussian hill height
+    pace=150,          # MD steps - deposition frequency
+    biasfactor=10.0,   # Dimensionless - well-tempered factor
+    temp=300.0         # Kelvin - system temperature
+)
+
+bias = hc.MetadBias(
+    cv=distance_cv,
+    sigma=0.1,         # Å - Gaussian width for distance CV
+    grid_min=0.0,      # Å - minimum grid value
+    grid_max=5.0,      # Å - maximum grid value
+    grid_bin=100       # Number of bins
+)
+
+# Restraint example
+restraint = hc.RestraintBias(
+    cv=distance_cv,
+    kappa=200.0,       # eV/Ų - force constant
+    at=2.5             # Å - restraint center
+)
+
+metad_model = hc.MetaDynamicsModel(
+    config=config,
+    bias_cvs=[bias],
+    actions=[restraint],
+    timestep=0.5       # fs - MD timestep
+)
+```
+
 ## Collective Variables
 
 hillclimber supports multiple types of collective variables:

{hillclimber-0.1.0a1 → hillclimber-0.1.0a3}/README.md

@@ -112,6 +112,64 @@ with project:
 project.build()
 ```
 
+## Units
+
+hillclimber uses **ASE units** throughout the package:
+
+- **Distances**: Ångström (Å)
+- **Energies**: electronvolt (eV)
+- **Time**: femtoseconds (fs)
+- **Temperature**: Kelvin (K)
+- **Mass**: atomic mass units (amu)
+
+### Unit Conversion with PLUMED
+
+PLUMED internally uses different units (nm, kJ/mol, ps). hillclimber automatically handles the conversion by adding a `UNITS` line to the PLUMED input:
+
+```
+UNITS LENGTH=A TIME=0.001 ENERGY=96.48533288249877
+```
+
+This tells PLUMED to interpret all input parameters in ASE units:
+- `LENGTH=A`: Distances are in Ångström
+- `TIME=0.001`: Time values are in fs (1 fs = 0.001 ps)
+- `ENERGY=96.485`: Energies are in eV (1 eV = 96.485 kJ/mol)
+
+**All PLUMED parameters (HEIGHT, BARRIER, KAPPA, SIGMA, etc.) should be specified in ASE units (eV, Å, fs).** The UNITS line ensures PLUMED interprets them correctly.
+
+### Example with Units
+
+```python
+config = hc.MetaDynamicsConfig(
+    height=0.5,        # eV - Gaussian hill height
+    pace=150,          # MD steps - deposition frequency
+    biasfactor=10.0,   # Dimensionless - well-tempered factor
+    temp=300.0         # Kelvin - system temperature
+)
+
+bias = hc.MetadBias(
+    cv=distance_cv,
+    sigma=0.1,         # Å - Gaussian width for distance CV
+    grid_min=0.0,      # Å - minimum grid value
+    grid_max=5.0,      # Å - maximum grid value
+    grid_bin=100       # Number of bins
+)
+
+# Restraint example
+restraint = hc.RestraintBias(
+    cv=distance_cv,
+    kappa=200.0,       # eV/Ų - force constant
+    at=2.5             # Å - restraint center
+)
+
+metad_model = hc.MetaDynamicsModel(
+    config=config,
+    bias_cvs=[bias],
+    actions=[restraint],
+    timestep=0.5       # fs - MD timestep
+)
+```
+
 ## Collective Variables
 
 hillclimber supports multiple types of collective variables: