Onboard hyper into rush-py

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+### Added
+- Onboarded `hyper_solvate`, `hyper_run` and `hyper_minimize`
+
 ## 7.0.0
 
 No new changes since 7.0.0rc3.

docs/modules.rst

@@ -7,6 +7,9 @@ Rush Modules
    rush.exess_optimization
    rush.exess_qmmm
    rush.nnxtb
+   rush.hyper
+   rush.hyper_minimize_sumo
+   rush.hyper_run_sumo
    rush.prepare
    rush.auto3d
    rush.mmseqs2

docs/rush.hyper.rst

@@ -0,0 +1,31 @@
+:tocdepth: 3
+
+Hyper Solvation
+===============
+
+.. automodule:: rush.hyper._hyper_solvate_sumo
+
+.. currentmodule:: rush.hyper
+
+Run Submission
+--------------
+
+.. autofunction:: hyper_solvate_sumo
+
+Input Types
+-----------
+
+.. autoclass:: HyperConfig
+   :members:
+   :undoc-members:
+
+Result Types
+------------
+
+.. autoclass:: ItemError
+   :members:
+   :undoc-members:
+
+.. autoclass:: TRCBatchResultRef
+   :members:
+   :undoc-members:

docs/rush.hyper_minimize_sumo.rst

@@ -0,0 +1,30 @@
+:tocdepth: 3
+
+Hyper Minimize
+==============
+
+.. automodule:: rush.hyper._hyper_minimize_sumo
+
+.. currentmodule:: rush.hyper
+
+Run Submission
+--------------
+
+.. autofunction:: hyper_minimize_sumo
+
+Input Types
+-----------
+
+.. autoclass:: HyperMinimizeConfig
+   :members:
+   :undoc-members:
+
+.. autoclass:: MinimizeInput
+   :members:
+   :undoc-members:
+
+Result Types
+------------
+
+Minimization returns :class:`rush.hyper.TRCBatchResultRef` with per-item
+results that can be fetched as ``TRC`` objects or ``ItemError`` values.

docs/rush.hyper_run_sumo.rst

@@ -0,0 +1,43 @@
+:tocdepth: 3
+
+Hyper Run
+=========
+
+.. automodule:: rush.hyper._hyper_run_sumo
+
+.. currentmodule:: rush.hyper
+
+Run Submission
+--------------
+
+.. autofunction:: hyper_run_sumo
+
+Input Types
+-----------
+
+.. autoclass:: HyperRunConfig
+   :members:
+   :undoc-members:
+
+.. autoclass:: RunInput
+   :members:
+   :undoc-members:
+
+Result Types
+------------
+
+.. autoclass:: RunOutput
+   :members:
+   :undoc-members:
+
+.. autoclass:: RunOutputRef
+   :members:
+   :undoc-members:
+
+.. autoclass:: RunOutputPaths
+   :members:
+   :undoc-members:
+
+.. autoclass:: RunResultRef
+   :members:
+   :undoc-members:

docs/tutorials.rst

@@ -11,3 +11,6 @@ Tutorials
    tutorials/05-exess-interaction-energy
    tutorials/06-exess-qmmm
    tutorials/07-nnxtb-energy
+   tutorials/08-hyper-solvate_sumo
+   tutorials/09-hyper-minimize_sumo
+   tutorials/10-hyper-run_sumo

docs/tutorials/08-hyper-solvate_sumo.md

@@ -0,0 +1,51 @@
+# Tutorial 8: Hyper Solvate Sumo
+
+**What you get:** A solvated `TRC` structure that you can pass directly into minimization or MD.
+
+| | |
+|---|---|
+| **Time** | ~2-5 minutes |
+| **Skill level** | Beginner |
+| **Prerequisites** | Python 3.12+, `rush-py` installed, `RUSH_TOKEN` and `RUSH_PROJECT` set |
+
+---
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from rush import RunOpts, TRC, hyper
+
+input_trc = Path("tests/data/hyper/valid_trc.json")
+
+run = hyper.hyper_solvate_sumo(
+    [input_trc],
+    config=hyper.HyperConfig(max_inputs=8, padding_nm=0.8, seed=12345, timeout_seconds=120),
+    run_opts=RunOpts(name="Tutorial: Hyper Solvate", tags=["rush-py", "tutorial", "hyper", "solvate"]),
+)
+
+item = run.fetch()[0]
+if not isinstance(item, TRC):
+    raise RuntimeError(f"Unexpected per-item error: {item}")
+
+print("Solvated atoms:", len(item.topology.symbols))
+```
+
+---
+
+## Output Contract
+
+`hyper_solvate_sumo()` returns `Run[hyper.TRCBatchResultRef]`.
+
+- `run.collect()` -> `TRCBatchResultRef`
+- `result_ref.fetch()` -> `list[TRC | ItemError]`
+- `result_ref.save()` -> `list[Path | ItemError]`
+
+---
+
+## See Also
+
+- {doc}`Hyper Minimize tutorial <09-hyper-minimize_sumo>`
+- {doc}`Hyper Run tutorial <10-hyper-run_sumo>`
+- {doc}`Hyper API reference <../rush.hyper>`

docs/tutorials/09-hyper-minimize_sumo.md

@@ -0,0 +1,56 @@
+# Tutorial 9: Hyper Minimize Sumo
+
+**What you get:** An energy-minimized structure from a structure/topology pair.
+
+| | |
+|---|---|
+| **Time** | ~2-8 minutes |
+| **Skill level** | Beginner |
+| **Prerequisites** | Python 3.12+, `rush-py` installed, `RUSH_TOKEN` and `RUSH_PROJECT` set |
+
+---
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from rush import RunOpts, TRC, hyper
+
+data_dir = Path("tests/data/hyper")
+
+run = hyper.hyper_minimize_sumo(
+    [
+        hyper.MinimizeInput(
+            structure=data_dir / "methanol_trc.json",
+            topology=data_dir / "methanol_topology.json",
+        )
+    ],
+    config=hyper.HyperMinimizeConfig(max_inputs=4, steps=100, gtol=100.0, timeout_seconds=900),
+    run_opts=RunOpts(name="Tutorial: Hyper Minimize", tags=["rush-py", "tutorial", "hyper", "minimize"]),
+)
+
+item = run.fetch()[0]
+if not isinstance(item, TRC):
+    raise RuntimeError(f"Unexpected per-item error: {item}")
+
+print("Minimized atoms:", len(item.topology.symbols))
+```
+
+---
+
+## Output Contract
+
+`hyper_minimize_sumo()` returns `Run[hyper.TRCBatchResultRef]`.
+
+- `run.collect()` -> `TRCBatchResultRef`
+- `result_ref.fetch()` -> `list[TRC | ItemError]`
+- `result_ref.save()` -> `list[Path | ItemError]`
+
+---
+
+## See Also
+
+- {doc}`Hyper Solvate tutorial <08-hyper-solvate_sumo>`
+- {doc}`Hyper Run tutorial <10-hyper-run_sumo>`
+- {doc}`Hyper Minimize API reference <../rush.hyper_minimize_sumo>`

docs/tutorials/10-hyper-run_sumo.md

@@ -0,0 +1,69 @@
+# Tutorial 10: Hyper Run Sumo
+
+**What you get:** Trajectory and optional checkpoint artifacts from short molecular dynamics runs.
+
+| | |
+|---|---|
+| **Time** | ~3-10 minutes |
+| **Skill level** | Intermediate |
+| **Prerequisites** | Python 3.12+, `rush-py` installed, `RUSH_TOKEN` and `RUSH_PROJECT` set |
+
+---
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from rush import RunOpts, hyper
+
+data_dir = Path("tests/data/hyper")
+
+run = hyper.hyper_run_sumo(
+    [
+        hyper.RunInput(
+            sim_config=data_dir / "sim_config.json",
+            topology=data_dir / "methanol_topology.json",
+            coordinates=data_dir / "methanol_trc.json",
+        )
+    ],
+    config=hyper.HyperRunConfig(
+        max_inputs=4,
+        nsteps=20,
+        dt_ps=0.001,
+        temperature_k=300.0,
+        ensemble="Nvt",
+        minimize_before_run=False,
+        solvate_before_run=False,
+        use_gpu=False,
+        nthreads=1,
+        timeout_seconds=900,
+    ),
+    run_opts=RunOpts(name="Tutorial: Hyper Run", tags=["rush-py", "tutorial", "hyper", "run"]),
+)
+
+item = run.fetch()[0]
+if isinstance(item, hyper.ItemError):
+    raise RuntimeError(f"Hyper run failed: {item}")
+
+print("Trajectory bytes:", len(item.trajectory))
+print("Checkpoint bytes:", 0 if item.checkpoint is None else len(item.checkpoint))
+```
+
+---
+
+## Output Contract
+
+`hyper_run_sumo()` returns `Run[hyper.RunResultRef]`.
+
+- `run.collect()` -> `RunResultRef`
+- `result_ref.fetch()` -> `list[RunOutput | ItemError]`
+- `result_ref.save()` -> `list[RunOutputPaths | ItemError]`
+
+---
+
+## See Also
+
+- {doc}`Hyper Solvate tutorial <08-hyper-solvate_sumo>`
+- {doc}`Hyper Minimize tutorial <09-hyper-minimize_sumo>`
+- {doc}`Hyper Run API reference <../rush.hyper_run_sumo>`

examples/hyper-minimize_sumo/09_hyper_minimize_sumo.py

@@ -0,0 +1,39 @@
+"""Example: Hyper minimization workflow."""
+
+from pathlib import Path
+
+from rush import RunOpts, TRC, hyper
+
+DATA_DIR = Path(__file__).parent / "data"
+
+run = hyper.hyper_minimize_sumo(
+    [
+        hyper.MinimizeInput(
+            structure=DATA_DIR / "methanol_trc.json",
+            topology=DATA_DIR / "methanol_topology.json",
+        )
+    ],
+    config=hyper.HyperMinimizeConfig(max_inputs=4, steps=100, gtol=100.0, timeout_seconds=900),
+    run_opts=RunOpts(name="Example: Hyper Minimize", tags=["rush-py", "example", "hyper", "minimize"]),
+)
+
+result_ref = run.collect()
+fetched = result_ref.fetch()
+if len(fetched) != 1:
+    raise RuntimeError(f"Expected 1 output item, got {len(fetched)}")
+
+item = fetched[0]
+if not isinstance(item, TRC):
+    raise RuntimeError(f"Expected TRC output, got {item}")
+
+print("Minimized atom count:", len(item.topology.symbols))
+
+saved = result_ref.save()
+if len(saved) != 1:
+    raise RuntimeError(f"Expected 1 saved item, got {len(saved)}")
+
+saved_item = saved[0]
+if isinstance(saved_item, hyper.ItemError):
+    raise RuntimeError(f"Unexpected per-item save error: {saved_item}")
+
+print("Saved output:", saved_item)

examples/hyper-minimize_sumo/README.md

@@ -0,0 +1,27 @@
+# Hyper Minimize Sumo Example
+
+Demonstrates `hyper.hyper_minimize_sumo()` with one structure/topology job.
+
+## Quick Start
+
+```bash
+export RUSH_TOKEN="your-token"
+export RUSH_PROJECT="your-project"
+
+python 09_hyper_minimize_sumo.py
+```
+
+## What This Example Covers
+
+1. Building a `MinimizeInput` job from local JSON files
+2. Running Hyper minimization with explicit config bounds
+3. Fetching and saving successful TRC output
+
+## Input Data
+
+- `data/methanol_trc.json`
+- `data/methanol_topology.json`
+
+## Tutorial
+
+See: [Tutorial 9: Hyper Minimize Sumo](../../docs/tutorials/09-hyper-minimize_sumo.md)