From 82fe1678eb8ad525a9c8bd8533eee16de474607f Mon Sep 17 00:00:00 2001
From: xraymemory <me.anzuoni@gmail.com>
Date: Thu, 28 May 2026 12:36:47 -0400
Subject: [PATCH 1/4] feat(runs): add analysis preset harness

---
 Dockerfile                           |   8 +-
 README.md                            |  26 ++-
 analyses/all.toml                    |  56 +++++
 analyses/altloc_classify.toml        |  25 ++
 analyses/altloc_find.toml            |  23 ++
 analyses/external_tools.toml         |  32 +++
 analyses/grid_search.toml            |  40 ++++
 docker-entrypoint.sh                 |  19 +-
 pyproject.toml                       |   2 +
 run_analysis                         | 338 +++++++++++++++++++++++++++
 run_analysis.sh                      |  17 ++
 scripts/eval/EVALUATION.md           |  17 ++
 src/sampleworks/runs/__init__.py     |   6 +-
 src/sampleworks/runs/analysis_cli.py |  51 ++++
 src/sampleworks/runs/cli.py          | 204 +++++++++++-----
 src/sampleworks/runs/loader.py       | 124 +++++++---
 src/sampleworks/runs/runner.py       | 154 ++++++++++--
 src/sampleworks/runs/schema.py       |  49 +++-
 tests/runs/test_runner.py            |  82 ++++++-
 19 files changed, 1142 insertions(+), 131 deletions(-)
 create mode 100644 analyses/all.toml
 create mode 100644 analyses/altloc_classify.toml
 create mode 100644 analyses/altloc_find.toml
 create mode 100644 analyses/external_tools.toml
 create mode 100644 analyses/grid_search.toml
 create mode 100755 run_analysis
 create mode 100755 run_analysis.sh
 create mode 100644 src/sampleworks/runs/analysis_cli.py

diff --git a/Dockerfile b/Dockerfile
index 439421e3..0d96eaac 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -120,7 +120,8 @@ COPY --from=harbor.astera.sh/library/sampleworks-checkpoints:latest /checkpoints
 # smaller CI runners (ubuntu-latest can be 72 GB or 145 GB).
 RUN pixi install -e boltz --frozen && \
     pixi install -e protenix --frozen && \
-    pixi install -e rf3 --frozen
+    pixi install -e rf3 --frozen && \
+    pixi install -e analysis --frozen
 
 # ============================================================================
 # Pre-compile CUDA extensions to avoid JIT compilation at runtime
@@ -133,10 +134,11 @@ print('CUDA extensions compiled successfully')" || echo "CUDA extension pre-comp
 # This image carries pixi environments and checkpoints. Runtime source should
 # come from ACTL's synced checkout at /home/dev/workspace, not from stale code
 # baked into /app during image construction.
-RUN rm -rf /app/src /app/scripts /app/experiments /app/run_grid_search.py \
+RUN rm -rf /app/src /app/scripts /app/experiments /app/analyses \
+    /app/run_grid_search.py /app/run_analysis \
     && mkdir -p /home/dev/workspace
 
-COPY --chmod=755 run_experiments run_experiments.sh run_all_models.sh /usr/local/bin/
+COPY --chmod=755 run_experiments run_experiments.sh run_all_models.sh run_analysis run_analysis.sh /usr/local/bin/
 RUN printf '\n# ACTL scientist workflow: land in the synced Sampleworks checkout.\nif [[ $- == *i* ]] && [ -z "${SAMPLEWORKS_NO_AUTO_CD:-}" ] && [ -d /home/dev/workspace ]; then\n    cd /home/dev/workspace\nfi\n' >> /root/.bashrc
 
 ENV SAMPLEWORKS_PIXI_PROJECT_DIR=/app \
diff --git a/README.md b/README.md
index f9f31aa8..a069a7c0 100644
--- a/README.md
+++ b/README.md
@@ -149,7 +149,8 @@ Output layout: `grid_search_results/<protein>/<model>[_<method>]/<scaler>/ens<N>
 
 > **Note**: Jobs are skipped if a `refined.cif` file already exists in the output directory. Some flags (e.g., `--use-tweedie`, `--gradient-normalization`) are not reflected in the directory structure, so changing them alone won't trigger a re-run. Use `--force-all` to re-run all jobs regardless. This is under active development and will likely change soon.
 
-Instructions for running evaluation and metrics scripts are coming soon.
+Evaluation and metrics scripts can be run through `run_analysis`; see the ACTL
+section below and `scripts/eval/EVALUATION.md`.
 
 
 ## Running preset experiments on ACTL (`run_experiments`)
@@ -246,6 +247,29 @@ debugging only, opt into an on-pod pixi update with
 rebuilt `pixi-with-checkpoints:sampleworks` image instead.
 
 
+## Running preset analyses on ACTL (`run_analysis`)
+
+`run_analysis` uses the same TOML runner as `run_experiments`, but loads presets
+from `analyses/*.toml` and runs the scripts under `scripts/eval/`.
+
+```bash
+export GRID_SEARCH_RESULTS_DIR=/mnt/diffuse-shared/results/sampleworks/<pod>/full_8gpu
+export GRID_SEARCH_INPUTS_DIR=/mnt/diffuse-shared/raw/sampleworks/initial_dataset_40_occ_sweeps
+export PROTEIN_CONFIGS_CSV="$GRID_SEARCH_INPUTS_DIR/protein_analysis_config.csv"
+
+run_analysis --list
+run_analysis --dry-run rscc
+run_analysis grid_search --jobs rscc,lddt
+run_analysis altloc_find
+run_analysis altloc_classify
+run_analysis all  # includes tortoize and phenix.clashscore jobs
+```
+
+Use `--set` for one-off changes, for example
+`run_analysis rscc --set shared_args.target-filename=refined.cif` or
+`run_analysis rscc --set jobs.rscc.gpus=0`.
+
+
 ## Docker
 
 TODO: Docker container documentation
diff --git a/analyses/all.toml b/analyses/all.toml
new file mode 100644
index 00000000..02294cfa
--- /dev/null
+++ b/analyses/all.toml
@@ -0,0 +1,56 @@
+description = "All grid-search evaluations, including optional external-tool checks."
+
+[defaults]
+GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
+GRID_SEARCH_INPUTS_DIR = "/data/inputs"
+PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
+TARGET_FILENAME = "refined-patched.cif"
+N_JOBS = "16"
+
+[shared_args]
+grid-search-results-path = "${GRID_SEARCH_RESULTS_DIR}"
+grid-search-inputs-path = "${GRID_SEARCH_INPUTS_DIR}"
+protein-configs-csv = "${PROTEIN_CONFIGS_CSV}"
+target-filename = "${TARGET_FILENAME}"
+occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
+n-jobs = "${N_JOBS}"
+
+[[jobs]]
+name = "rscc"
+env = "analysis"
+gpu_count = 1
+script = "scripts/eval/rscc_grid_search_script.py"
+output_arg = ""
+output_subdir = "analysis/rscc"
+
+[[jobs]]
+name = "lddt"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/lddt_evaluation_script.py"
+output_arg = ""
+output_subdir = "analysis/lddt"
+
+[[jobs]]
+name = "bond_geometry"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/bond_geometry_eval.py"
+output_arg = ""
+output_subdir = "analysis/bond_geometry"
+
+[[jobs]]
+name = "tortoize"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/run_and_process_tortoize.py"
+output_arg = ""
+output_subdir = "analysis/tortoize"
+
+[[jobs]]
+name = "phenix_clashscore"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/run_and_process_phenix_clashscore.py"
+output_arg = ""
+output_subdir = "analysis/phenix_clashscore"
diff --git a/analyses/altloc_classify.toml b/analyses/altloc_classify.toml
new file mode 100644
index 00000000..cd7cf730
--- /dev/null
+++ b/analyses/altloc_classify.toml
@@ -0,0 +1,25 @@
+description = "Classify altloc selections into side-chain, loop, and domain-shift categories."
+
+[defaults]
+GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
+GRID_SEARCH_INPUTS_DIR = "/data/inputs"
+ALTLOC_SELECTIONS_CSV = "${GRID_SEARCH_RESULTS_DIR}/analysis/altloc_selections.csv"
+ALTLOC_CLASSIFICATIONS_CSV = "${GRID_SEARCH_RESULTS_DIR}/analysis/altloc_region_classifications.csv"
+CIF_ROOT = "${GRID_SEARCH_INPUTS_DIR}"
+DOMAIN_SHIFT_MIN_SPAN = "50"
+LOOP_LDDT_THRESHOLD = "0.75"
+
+[shared_args]
+input-csv = "${ALTLOC_SELECTIONS_CSV}"
+cif-root = "${CIF_ROOT}"
+output-file = "${ALTLOC_CLASSIFICATIONS_CSV}"
+domain-shift-min-span = "${DOMAIN_SHIFT_MIN_SPAN}"
+loop-lddt-threshold = "${LOOP_LDDT_THRESHOLD}"
+
+[[jobs]]
+name = "classify_altloc_regions"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/classify_altloc_regions.py"
+output_arg = ""
+output_subdir = "analysis/altloc_classify"
diff --git a/analyses/altloc_find.toml b/analyses/altloc_find.toml
new file mode 100644
index 00000000..e6d2718b
--- /dev/null
+++ b/analyses/altloc_find.toml
@@ -0,0 +1,23 @@
+description = "Build an analysis protein-config CSV by finding altloc selections in input CIFs."
+
+[defaults]
+GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
+GRID_SEARCH_INPUTS_DIR = "/data/inputs"
+PROTEINS_CSV = "${GRID_SEARCH_INPUTS_DIR}/proteins.csv"
+ALTLOC_SELECTIONS_CSV = "${GRID_SEARCH_RESULTS_DIR}/analysis/altloc_selections.csv"
+ALTLOC_MIN_SPAN = "5"
+ALTLOC_LABEL = "label_alt_id"
+
+[shared_args]
+input-csv = "${PROTEINS_CSV}"
+output-file = "${ALTLOC_SELECTIONS_CSV}"
+min-span = "${ALTLOC_MIN_SPAN}"
+altloc-label = "${ALTLOC_LABEL}"
+
+[[jobs]]
+name = "find_altloc_selections"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/find_altloc_selections.py"
+output_arg = ""
+output_subdir = "analysis/altloc_find"
diff --git a/analyses/external_tools.toml b/analyses/external_tools.toml
new file mode 100644
index 00000000..2ffa8226
--- /dev/null
+++ b/analyses/external_tools.toml
@@ -0,0 +1,32 @@
+description = "Evaluation jobs that require external executables: tortoize and phenix.clashscore."
+
+[defaults]
+GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
+GRID_SEARCH_INPUTS_DIR = "/data/inputs"
+PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
+TARGET_FILENAME = "refined-patched.cif"
+N_JOBS = "16"
+
+[shared_args]
+grid-search-results-path = "${GRID_SEARCH_RESULTS_DIR}"
+grid-search-inputs-path = "${GRID_SEARCH_INPUTS_DIR}"
+protein-configs-csv = "${PROTEIN_CONFIGS_CSV}"
+target-filename = "${TARGET_FILENAME}"
+occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
+n-jobs = "${N_JOBS}"
+
+[[jobs]]
+name = "tortoize"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/run_and_process_tortoize.py"
+output_arg = ""
+output_subdir = "analysis/tortoize"
+
+[[jobs]]
+name = "phenix_clashscore"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/run_and_process_phenix_clashscore.py"
+output_arg = ""
+output_subdir = "analysis/phenix_clashscore"
diff --git a/analyses/grid_search.toml b/analyses/grid_search.toml
new file mode 100644
index 00000000..5cf68419
--- /dev/null
+++ b/analyses/grid_search.toml
@@ -0,0 +1,40 @@
+description = "Core grid-search evaluations: RSCC, LDDT clustering, and bond geometry."
+
+[defaults]
+GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
+GRID_SEARCH_INPUTS_DIR = "/data/inputs"
+PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
+TARGET_FILENAME = "refined-patched.cif"
+N_JOBS = "16"
+
+[shared_args]
+grid-search-results-path = "${GRID_SEARCH_RESULTS_DIR}"
+grid-search-inputs-path = "${GRID_SEARCH_INPUTS_DIR}"
+protein-configs-csv = "${PROTEIN_CONFIGS_CSV}"
+target-filename = "${TARGET_FILENAME}"
+occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
+n-jobs = "${N_JOBS}"
+
+[[jobs]]
+name = "rscc"
+env = "analysis"
+gpu_count = 1
+script = "scripts/eval/rscc_grid_search_script.py"
+output_arg = ""
+output_subdir = "analysis/rscc"
+
+[[jobs]]
+name = "lddt"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/lddt_evaluation_script.py"
+output_arg = ""
+output_subdir = "analysis/lddt"
+
+[[jobs]]
+name = "bond_geometry"
+env = "analysis"
+gpus = "none"
+script = "scripts/eval/bond_geometry_eval.py"
+output_arg = ""
+output_subdir = "analysis/bond_geometry"
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
index 0477a7dc..facdebea 100755
--- a/docker-entrypoint.sh
+++ b/docker-entrypoint.sh
@@ -6,7 +6,7 @@
 #   docker run pixi-with-checkpoints -e boltz run_grid_search.py --proteins /data/proteins.csv ...
 #   docker run pixi-with-checkpoints bash  # interactive shell
 #
-# Available pixi environments: boltz, protenix, rf3
+# Available pixi environments: boltz, protenix, rf3, analysis
 #
 # Examples:
 #   # Run grid search with RF3
@@ -36,7 +36,7 @@ IMPORTANT:
     Always use --shm-size=16g (or larger) to avoid shared memory errors with DataLoaders.
 
 OPTIONS:
-    -e, --env <env>     Pixi environment to use (boltz, protenix, rf3)
+    -e, --env <env>     Pixi environment to use (boltz, protenix, rf3, analysis)
     -h, --help          Show this help message
     bash                Start an interactive shell
 
@@ -44,6 +44,7 @@ ENVIRONMENTS:
     boltz       For boltz1 and boltz2 models
     protenix    For protenix model  
     rf3         For RF3 model
+    analysis    For scripts/eval analysis jobs
 
 EXAMPLES:
     # Run grid search with RF3 model
@@ -190,6 +191,10 @@ PROTEINS CSV FORMAT:
       1abc,/data/structures/1abc.cif,/data/maps/1abc.ccp4,2.0
       2xyz,/data/structures/2xyz.cif,/data/maps/2xyz.mrc,1.8
 
+ACTL helper commands:
+    run_experiments         Run experiments/*.toml presets
+    run_analysis            Run analyses/*.toml presets for scripts/eval
+
 For full argument details, run:
     docker run pixi-with-checkpoints -e boltz run_grid_search.py --help
 EOF
@@ -202,7 +207,7 @@ if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
 fi
 
 # Handle scientist workflow helpers and interactive shells
-if [ "$1" = "run_experiments" ] || [ "$1" = "run_experiments.sh" ] || [ "$1" = "run_all_models.sh" ]; then
+if [ "$1" = "run_experiments" ] || [ "$1" = "run_experiments.sh" ] || [ "$1" = "run_all_models.sh" ] || [ "$1" = "run_analysis" ] || [ "$1" = "run_analysis.sh" ]; then
     exec "$@"
 fi
 
@@ -216,7 +221,7 @@ while [[ $# -gt 0 ]]; do
     case $1 in
         -e|--env)
             if [ -z "$2" ] || [[ "$2" == -* ]]; then
-                echo "Error: -e/--env requires an environment name (boltz, protenix, rf3)"
+                echo "Error: -e/--env requires an environment name (boltz, protenix, rf3, analysis)"
                 exit 1
             fi
             ENV="$2"
@@ -236,7 +241,7 @@ done
 
 # Validate environment
 if [[ -z "$ENV" ]]; then
-    echo "Error: Environment not specified. Use -e <env> where env is boltz, protenix, or rf3"
+    echo "Error: Environment not specified. Use -e <env> where env is boltz, protenix, rf3, or analysis"
     echo ""
     echo "Usage: docker run pixi-with-checkpoints -e <env> <script> [args...]"
     echo ""
@@ -248,10 +253,10 @@ if [[ -z "$ENV" ]]; then
 fi
 
 case $ENV in
-    boltz|protenix|rf3)
+    boltz|protenix|rf3|analysis)
         ;;
     *)
-        echo "Error: Invalid environment '$ENV'. Must be one of: boltz, protenix, rf3"
+        echo "Error: Invalid environment '$ENV'. Must be one of: boltz, protenix, rf3, analysis"
         exit 1
         ;;
 esac
diff --git a/pyproject.toml b/pyproject.toml
index 682e086e..5cbb01a9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,10 +36,12 @@ requires-python = ">= 3.11, <3.14"
 version = "0.7.0"
 
 [project.scripts]
+sampleworks-analysis = "sampleworks.runs.analysis_cli:main"
 sampleworks-guidance = "sampleworks.cli.guidance:main"
 sampleworks-runs = "sampleworks.runs.cli:main"
 
 [tool.hatch.build.targets.wheel.force-include]
+"analyses" = "analyses"
 "experiments" = "experiments"
 
 [tool.hatch.metadata]
diff --git a/run_analysis b/run_analysis
new file mode 100755
index 00000000..54a55539
--- /dev/null
+++ b/run_analysis
@@ -0,0 +1,338 @@
+#!/usr/bin/env bash
+# ACTL-native entry point for Sampleworks analysis/evaluation preset runs.
+#
+# The TOML preset is the source of truth. This wrapper mirrors run_experiments
+# but targets analyses/*.toml presets and executes scripts/eval jobs through the
+# shared Python runner backend.
+
+set -euo pipefail
+
+script_path="${BASH_SOURCE[0]}"
+while [[ -L "$script_path" ]]; do
+    script_dir="$(cd -- "$(dirname -- "$script_path")" && pwd)"
+    script_target="$(readlink "$script_path")"
+    if [[ "$script_target" == /* ]]; then
+        script_path="$script_target"
+    else
+        script_path="$script_dir/$script_target"
+    fi
+done
+script_dir="$(cd -- "$(dirname -- "$script_path")" && pwd)"
+
+is_sampleworks_root() {
+    local candidate="$1"
+    [[ -f "$candidate/pyproject.toml" && -d "$candidate/src/sampleworks" && -d "$candidate/scripts/eval" ]]
+}
+
+find_sampleworks_root_upwards() {
+    local candidate="$1"
+    while [[ -n "$candidate" && "$candidate" != "/" ]]; do
+        if is_sampleworks_root "$candidate"; then
+            printf '%s\n' "$candidate"
+            return 0
+        fi
+        candidate="$(dirname -- "$candidate")"
+    done
+    return 1
+}
+
+truthy_env() {
+    local name="$1"
+    [[ "${!name:-}" =~ ^(1|true|yes)$ ]]
+}
+
+require_env_var() {
+    local name="$1"
+    local help_text="$2"
+    if [[ -z "${!name:-}" ]]; then
+        cat >&2 <<EOF
+$name must be set explicitly for run_analysis.
+
+$help_text
+EOF
+        return 2
+    fi
+}
+
+pixi_inputs_match_image() {
+    local image_root="$1"
+    local source_root="$2"
+
+    [[ -f "$image_root/pyproject.toml" && -f "$image_root/pixi.lock" ]] || return 0
+    [[ -f "$source_root/pyproject.toml" && -f "$source_root/pixi.lock" ]] || return 0
+
+    cmp -s "$image_root/pyproject.toml" "$source_root/pyproject.toml" && \
+        cmp -s "$image_root/pixi.lock" "$source_root/pixi.lock"
+}
+
+resolve_repo_root() {
+    local source_override="${SAMPLEWORKS_SOURCE_DIR:-}"
+    if [[ -n "$source_override" ]]; then
+        if ! is_sampleworks_root "$source_override"; then
+            cat >&2 <<EOF
+SAMPLEWORKS_SOURCE_DIR does not point to a Sampleworks checkout:
+  $source_override
+EOF
+            return 2
+        fi
+        printf '%s\n' "$source_override"
+        return 0
+    fi
+
+    if is_sampleworks_root "/home/dev/workspace"; then
+        printf '%s\n' "/home/dev/workspace"
+        return 0
+    fi
+
+    find_sampleworks_root_upwards "$PWD" && return 0
+
+    local app_override="${SAMPLEWORKS_APP_DIR:-}"
+    if [[ -n "$app_override" ]] && is_sampleworks_root "$app_override"; then
+        printf '%s\n' "$app_override"
+        return 0
+    fi
+
+    if is_sampleworks_root "$script_dir"; then
+        printf '%s\n' "$script_dir"
+        return 0
+    fi
+
+    cat >&2 <<'EOF'
+Could not find the synced Sampleworks checkout.
+
+Expected ACTL to sync the repo to /home/dev/workspace. If you are using a
+custom layout, set SAMPLEWORKS_SOURCE_DIR=/path/to/sampleworks before running
+run_analysis.
+EOF
+    return 2
+}
+
+repo_root="$(resolve_repo_root)"
+
+env_preset="${SAMPLEWORKS_ANALYSIS_PRESET:-}"
+default_target="$env_preset"
+target=""
+explicit_preset=""
+explicit_jobs=""
+explicit_results_dir=""
+expect_value_for=""
+for arg in "$@"; do
+    if [[ -n "$expect_value_for" ]]; then
+        case "$expect_value_for" in
+            preset)
+                explicit_preset="$arg"
+                ;;
+            results-dir)
+                explicit_results_dir="$arg"
+                ;;
+            jobs)
+                explicit_jobs="$arg"
+                ;;
+        esac
+        expect_value_for=""
+        continue
+    fi
+
+    case "$arg" in
+        --preset)
+            expect_value_for="preset"
+            ;;
+        --preset=*)
+            explicit_preset="${arg#--preset=}"
+            ;;
+        --results-dir)
+            expect_value_for="results-dir"
+            ;;
+        --results-dir=*)
+            explicit_results_dir="${arg#--results-dir=}"
+            ;;
+        --jobs)
+            expect_value_for="jobs"
+            ;;
+        --jobs=*)
+            explicit_jobs="${arg#--jobs=}"
+            ;;
+        -*)
+            ;;
+        *)
+            if [[ -z "$target" ]]; then
+                target="$arg"
+            fi
+            ;;
+    esac
+done
+
+needs_run_config=1
+for arg in "$@"; do
+    case "$arg" in
+        --list|-h|--help)
+            needs_run_config=0
+            ;;
+    esac
+done
+
+if [[
+    "$needs_run_config" -eq 1 &&
+    -z "$target" &&
+    -z "$explicit_preset" &&
+    -z "$explicit_jobs" &&
+    -z "$env_preset"
+]]; then
+    target="grid_search"
+fi
+
+label_source="$default_target"
+if [[ -n "$explicit_preset" ]]; then
+    label_source="$explicit_preset"
+elif [[ -n "$explicit_jobs" && ( -z "$target" || "$target" == "all" || "$target" == "grid_search" ) ]]; then
+    label_source="$explicit_jobs"
+elif [[ -n "$target" ]]; then
+    label_source="$target"
+fi
+if [[ "$label_source" == *.toml || "$label_source" == */* ]]; then
+    if [[ "$label_source" != /* ]]; then
+        label_source="$repo_root/$label_source"
+    fi
+fi
+run_label="${label_source##*/}"
+run_label="${run_label%.toml}"
+run_label="${run_label//,/_}"
+
+run_name="${SAMPLEWORKS_ACTL_RUN_NAME:-$(hostname -s 2>/dev/null || printf 'sampleworks')}"
+default_grid_results_dir="/mnt/diffuse-shared/results/sampleworks/${run_name}/${run_label}"
+default_grid_inputs_dir="/mnt/diffuse-shared/raw/sampleworks/initial_dataset_40_occ_sweeps"
+
+if [[ -n "$explicit_results_dir" ]]; then
+    export GRID_SEARCH_RESULTS_DIR="$explicit_results_dir"
+else
+    export GRID_SEARCH_RESULTS_DIR="${GRID_SEARCH_RESULTS_DIR:-${RESULTS_DIR:-${SAMPLEWORKS_RESULTS_DIR:-$default_grid_results_dir}}}"
+fi
+export RESULTS_DIR="${RESULTS_DIR:-$GRID_SEARCH_RESULTS_DIR}"
+export GRID_SEARCH_INPUTS_DIR="${GRID_SEARCH_INPUTS_DIR:-${DATA_DIR:-${SAMPLEWORKS_DATA_DIR:-$default_grid_inputs_dir}}}"
+export PROTEIN_CONFIGS_CSV="${PROTEIN_CONFIGS_CSV:-${SAMPLEWORKS_PROTEIN_CONFIGS_CSV:-$GRID_SEARCH_INPUTS_DIR/protein_analysis_config.csv}}"
+export TARGET_FILENAME="${TARGET_FILENAME:-${SAMPLEWORKS_TARGET_FILENAME:-refined-patched.cif}}"
+export N_JOBS="${N_JOBS:-${SAMPLEWORKS_ANALYSIS_N_JOBS:-16}}"
+export SAMPLEWORKS_SOURCE_DIR="$repo_root"
+export SAMPLEWORKS_ANALYSES_DIR="${SAMPLEWORKS_ANALYSES_DIR:-$repo_root/analyses}"
+export SAMPLEWORKS_SCRIPT_ROOT="$repo_root"
+export PYTHONPATH="$repo_root/src${PYTHONPATH:+:$PYTHONPATH}"
+export PIXI_CACHE_DIR="${PIXI_CACHE_DIR:-/tmp/pixi-cache}"
+export UV_CACHE_DIR="${UV_CACHE_DIR:-/tmp/uv-cache}"
+
+if [[ "$needs_run_config" -eq 1 ]]; then
+    require_env_var GRID_SEARCH_RESULTS_DIR \
+        "Set GRID_SEARCH_RESULTS_DIR or pass --results-dir to the grid-search output directory you want to evaluate."
+    require_env_var GRID_SEARCH_INPUTS_DIR \
+        "Set GRID_SEARCH_INPUTS_DIR (or DATA_DIR) to the directory containing inputs, maps, and protein config CSVs."
+fi
+
+runner_env="${SAMPLEWORKS_ANALYSIS_RUNNER_ENV:-analysis}"
+if truthy_env RUNTIME_PIXI; then
+    export SAMPLEWORKS_ALLOW_RUNTIME_PIXI=1
+fi
+pixi_project_dir="${SAMPLEWORKS_PIXI_PROJECT_DIR:-}"
+if [[ -z "$pixi_project_dir" ]]; then
+    if ! pixi_inputs_match_image /app "$repo_root" && truthy_env SAMPLEWORKS_ALLOW_RUNTIME_PIXI; then
+        pixi_project_dir="$repo_root"
+    elif [[ -f /app/pyproject.toml && -d /app/.pixi ]]; then
+        pixi_project_dir="/app"
+    else
+        pixi_project_dir="$repo_root"
+    fi
+fi
+export SAMPLEWORKS_PIXI_PROJECT_DIR="$pixi_project_dir"
+
+if ! pixi_inputs_match_image /app "$repo_root"; then
+    if truthy_env SAMPLEWORKS_ALLOW_RUNTIME_PIXI; then
+        cat >&2 <<EOF
+Synced pyproject.toml or pixi.lock differs from the baked image. Runtime pixi
+updates are enabled, so using the synced checkout as the pixi project:
+  $repo_root
+EOF
+        export SAMPLEWORKS_REQUIRE_PREBUILT_PIXI="${SAMPLEWORKS_REQUIRE_PREBUILT_PIXI:-0}"
+        export SAMPLEWORKS_SKIP_ENV_PREPARE="${SAMPLEWORKS_SKIP_ENV_PREPARE:-0}"
+    else
+        cat >&2 <<EOF
+Synced pyproject.toml or pixi.lock differs from the baked pixi-with-checkpoints image.
+
+Rebuild/use an image produced from this checkout, or intentionally update pixi
+inside this pod by running with:
+
+  RUNTIME_PIXI=1 run_analysis ...
+
+Runtime pixi updates can be slow, so they are disabled by default for
+reproducible scientist runs.
+EOF
+        exit 2
+    fi
+else
+    export SAMPLEWORKS_REQUIRE_PREBUILT_PIXI="${SAMPLEWORKS_REQUIRE_PREBUILT_PIXI:-1}"
+    export SAMPLEWORKS_SKIP_ENV_PREPARE="${SAMPLEWORKS_SKIP_ENV_PREPARE:-1}"
+fi
+runner_python="${SAMPLEWORKS_ANALYSIS_RUNNER_PYTHON:-$pixi_project_dir/.pixi/envs/$runner_env/bin/python}"
+
+extra_cli_args=()
+if [[ $# -eq 0 && -n "$env_preset" ]]; then
+    extra_cli_args=(--preset "$env_preset")
+fi
+
+display_target="${target:-${explicit_preset:-$default_target}}"
+if [[ -n "$explicit_jobs" ]]; then
+    display_target="$display_target --jobs $explicit_jobs"
+fi
+
+cat >&2 <<EOF
+Sampleworks analysis run
+  target:        $display_target
+  grid results:  $GRID_SEARCH_RESULTS_DIR
+  grid inputs:   $GRID_SEARCH_INPUTS_DIR
+  configs CSV:   $PROTEIN_CONFIGS_CSV
+  source:        $repo_root
+  pixi project:  $pixi_project_dir
+  runner env:    $runner_env
+  runner python: $runner_python
+
+EOF
+
+if [[ -x "$runner_python" ]]; then
+    runner_env_dir="$(cd -- "$(dirname -- "$runner_python")/.." && pwd)"
+    export PATH="$runner_env_dir/bin${PATH:+:$PATH}"
+    export CONDA_PREFIX="$runner_env_dir"
+    export CUDA_HOME="${CUDA_HOME:-$runner_env_dir}"
+    export PYTHONNOUSERSITE=1
+    cd "$repo_root"
+    if [[ "${#extra_cli_args[@]}" -gt 0 ]]; then
+        exec "$runner_python" -m sampleworks.runs.analysis_cli \
+            --results-dir "$GRID_SEARCH_RESULTS_DIR" \
+            "${extra_cli_args[@]}" \
+            "$@"
+    fi
+    exec "$runner_python" -m sampleworks.runs.analysis_cli \
+        --results-dir "$GRID_SEARCH_RESULTS_DIR" \
+        "$@"
+fi
+
+if ! truthy_env SAMPLEWORKS_ALLOW_RUNTIME_PIXI; then
+    cat >&2 <<EOF
+Prebuilt analysis pixi environment is missing: $runner_python
+
+run_analysis is for the ACTL pixi-with-checkpoints image, which must contain
+ready-to-use environments under /app/.pixi. Refusing to run 'pixi run' because
+that would install or refresh packages inside the pod.
+
+Recreate the pod with the current pixi-with-checkpoints image. If you are
+intentionally debugging runtime pixi setup, set RUNTIME_PIXI=1.
+EOF
+    exit 2
+fi
+
+cd "$pixi_project_dir"
+if [[ "${#extra_cli_args[@]}" -gt 0 ]]; then
+    exec pixi run -e "$runner_env" python -m sampleworks.runs.analysis_cli \
+        --results-dir "$GRID_SEARCH_RESULTS_DIR" \
+        "${extra_cli_args[@]}" \
+        "$@"
+fi
+exec pixi run -e "$runner_env" python -m sampleworks.runs.analysis_cli \
+    --results-dir "$GRID_SEARCH_RESULTS_DIR" \
+    "$@"
diff --git a/run_analysis.sh b/run_analysis.sh
new file mode 100755
index 00000000..d909017d
--- /dev/null
+++ b/run_analysis.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Backward-compatible alias for the extensionless run_analysis command.
+set -euo pipefail
+
+script_path="${BASH_SOURCE[0]}"
+while [[ -L "$script_path" ]]; do
+    script_dir="$(cd -- "$(dirname -- "$script_path")" && pwd)"
+    script_target="$(readlink "$script_path")"
+    if [[ "$script_target" == /* ]]; then
+        script_path="$script_target"
+    else
+        script_path="$script_dir/$script_target"
+    fi
+done
+script_dir="$(cd -- "$(dirname -- "$script_path")" && pwd)"
+
+exec "$script_dir/run_analysis" "$@"
diff --git a/scripts/eval/EVALUATION.md b/scripts/eval/EVALUATION.md
index c129c26e..6cbbd4b2 100644
--- a/scripts/eval/EVALUATION.md
+++ b/scripts/eval/EVALUATION.md
@@ -56,6 +56,23 @@ file. These `refined-patched.cif` files can be used as input to the remaining ev
 The evaluation scripts have a common interface defined by the method 
 `sampleworks.eval.grid_search_eval_utils.parse_eval_args`. The general form of these commands is:
 
+The preferred ACTL entrypoint is `run_analysis`, which reads TOML presets from `analyses/` and uses
+the same backend runner as `run_experiments`:
+
+```shell
+export GRID_SEARCH_RESULTS_DIR=/home/ubuntu/grid_search_results
+export GRID_SEARCH_INPUTS_DIR=/home/ubuntu/grid_search_inputs
+export PROTEIN_CONFIGS_CSV=/home/ubuntu/protein_analysis_config.csv
+
+run_analysis --list
+run_analysis grid_search --jobs rscc,lddt,bond_geometry
+run_analysis altloc_find
+run_analysis altloc_classify
+run_analysis rscc --set shared_args.target-filename=refined.cif
+```
+
+For direct script invocation, the equivalent command shape is:
+
 ```shell
 pixi run -e analysis python scripts/eval/<script> \
 --grid-search-results-path /home/ubuntu/grid_search_results \
diff --git a/src/sampleworks/runs/__init__.py b/src/sampleworks/runs/__init__.py
index 8bb071ac..771ae1e3 100644
--- a/src/sampleworks/runs/__init__.py
+++ b/src/sampleworks/runs/__init__.py
@@ -1,5 +1,5 @@
-"""Preset-driven orchestrator for parallel run_grid_search.py invocations.
+"""Preset-driven orchestrator for parallel Sampleworks script invocations.
 
-Replaces the previous ACTL-native bash wrapper scripts with TOML presets +
-a thin Python runner. See ``sampleworks-runs --help``.
+Replaces ACTL-native bash-only wrappers with TOML presets plus a thin Python
+runner. See ``sampleworks-runs --help`` and ``sampleworks-analysis --help``.
 """
diff --git a/src/sampleworks/runs/analysis_cli.py b/src/sampleworks/runs/analysis_cli.py
new file mode 100644
index 00000000..4a9f37af
--- /dev/null
+++ b/src/sampleworks/runs/analysis_cli.py
@@ -0,0 +1,51 @@
+"""Command-line entry point for ``sampleworks-analysis``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import CliConfig, run_cli
+
+
+ANALYSIS_CLI_CONFIG = CliConfig(
+    prog="sampleworks-analysis",
+    description=(
+        "Run Sampleworks analysis/evaluation presets. With no target, runs the "
+        "grid_search preset. A target like 'all' runs that preset; comma-separated "
+        "targets like 'rscc,lddt' select jobs from grid_search."
+    ),
+    target_help=(
+        "Preset name from analyses/ (grid_search, all, external_tools, etc.) or "
+        "comma-separated job shortcut from grid_search."
+    ),
+    preset_help="Preset name from analyses/ or path to a .toml file. Default: grid_search.",
+    list_help="List analyses/*.toml presets and exit",
+    preset_dir_name="analyses",
+    preset_dir_env_var="SAMPLEWORKS_ANALYSES_DIR",
+    default_preset="grid_search",
+    default_aliases=frozenset({"grid_search"}),
+    results_default_keys=("GRID_SEARCH_RESULTS_DIR", "RESULTS_DIR"),
+    results_env_vars=("GRID_SEARCH_RESULTS_DIR", "RESULTS_DIR"),
+    results_fallback="./grid_search_results",
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``sampleworks-analysis`` console script.
+
+    Parameters
+    ----------
+    argv : list of str or None, optional
+        Command-line arguments excluding the program name. When ``None``
+        (the default), :mod:`argparse` reads from :data:`sys.argv`.
+
+    Returns
+    -------
+    int
+        Exit code suitable for ``sys.exit``.
+    """
+    return run_cli(argv, config=ANALYSIS_CLI_CONFIG)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/src/sampleworks/runs/cli.py b/src/sampleworks/runs/cli.py
index 008d3f99..5d61b06d 100644
--- a/src/sampleworks/runs/cli.py
+++ b/src/sampleworks/runs/cli.py
@@ -5,6 +5,7 @@
 import argparse
 import os
 import sys
+from dataclasses import dataclass
 from pathlib import Path
 
 from . import loader, runner
@@ -15,6 +16,76 @@
 DEFAULT_PRESET_ALIASES = frozenset({"all", "full", "full_8gpu"})
 
 
+@dataclass(frozen=True)
+class CliConfig:
+    """Configuration for one preset-driven runner CLI.
+
+    Parameters
+    ----------
+    prog : str
+        Program name shown by argparse.
+    description : str
+        Parser description.
+    target_help : str
+        Help text for the optional positional target.
+    preset_help : str
+        Help text for ``--preset``.
+    list_help : str
+        Help text for ``--list``.
+    preset_dir_name : str
+        Top-level directory containing TOML presets.
+    preset_dir_env_var : str
+        Environment variable that can override the preset directory.
+    default_preset : str
+        Preset to use when the user gives no target.
+    default_aliases : frozenset of str
+        Positional targets that resolve to ``default_preset``.
+    results_default_keys : tuple of str
+        Keys from ``preset.defaults`` to consult for the runner's results/log
+        root.
+    results_env_vars : tuple of str
+        Environment variables to consult after ``results_default_keys``.
+    results_fallback : str
+        Final fallback results/log root.
+    """
+
+    prog: str
+    description: str
+    target_help: str
+    preset_help: str
+    list_help: str
+    preset_dir_name: str
+    preset_dir_env_var: str
+    default_preset: str
+    default_aliases: frozenset[str]
+    results_default_keys: tuple[str, ...]
+    results_env_vars: tuple[str, ...]
+    results_fallback: str
+
+
+EXPERIMENT_CLI_CONFIG = CliConfig(
+    prog="sampleworks-runs",
+    description=(
+        "Run Sampleworks experiment presets. With no target, runs the full_8gpu preset. "
+        "A target like 'rf3', 'boltz', or 'protenix' runs that preset; "
+        "comma-separated targets like 'rf3,protenix' select jobs from full_8gpu."
+    ),
+    target_help=(
+        "Preset name from experiments/ (rf3, boltz, protenix, etc.), comma-separated "
+        "job shortcut from full_8gpu, or 'full'/'full_8gpu'."
+    ),
+    preset_help="Preset name from experiments/ or path to a .toml file. Default: full_8gpu.",
+    list_help="List experiments/*.toml presets and exit",
+    preset_dir_name="experiments",
+    preset_dir_env_var="SAMPLEWORKS_EXPERIMENTS_DIR",
+    default_preset=DEFAULT_PRESET,
+    default_aliases=DEFAULT_PRESET_ALIASES,
+    results_default_keys=("RESULTS_DIR",),
+    results_env_vars=("RESULTS_DIR",),
+    results_fallback="./grid_search_results",
+)
+
+
 def main(argv: list[str] | None = None) -> int:
     """Entry point for the ``sampleworks-runs`` console script.
 
@@ -30,16 +101,48 @@ def main(argv: list[str] | None = None) -> int:
         Exit code suitable for ``sys.exit``: ``0`` on success, non-zero on
         job failure or fatal CLI error.
     """
-    parser = _build_parser()
+    return run_cli(argv, config=EXPERIMENT_CLI_CONFIG)
+
+
+def run_cli(argv: list[str] | None = None, *, config: CliConfig) -> int:
+    """Run a configured preset CLI.
+
+    Parameters
+    ----------
+    argv : list of str or None, optional
+        Command-line arguments excluding the program name.
+    config : CliConfig
+        CLI behavior and preset-directory configuration.
+
+    Returns
+    -------
+    int
+        Exit code suitable for ``sys.exit``.
+    """
+    parser = _build_parser(config)
     args = parser.parse_args(argv)
 
     if args.list:
-        for name in loader.list_presets():
+        for name in loader.list_presets(
+            preset_dir_name=config.preset_dir_name,
+            preset_dir_env_var=config.preset_dir_env_var,
+        ):
             print(name)
         return 0
 
-    preset_name, job_filter = _resolve_target(args.target, args.preset, args.jobs, parser)
-    preset = loader.load_preset(preset_name, overrides=args.set)
+    preset_name, job_filter = _resolve_target(
+        args.target,
+        args.preset,
+        args.jobs,
+        parser,
+        config=config,
+    )
+    preset = loader.load_preset(
+        preset_name,
+        overrides=args.set,
+        preset_dir_name=config.preset_dir_name,
+        preset_dir_env_var=config.preset_dir_env_var,
+    )
     if job_filter:
         preset = _filter_jobs(preset, job_filter)
 
@@ -47,7 +150,7 @@ def main(argv: list[str] | None = None) -> int:
         _print_show(preset)
         return 0
 
-    results_dir = Path(args.results_dir or _default_results_dir(preset))
+    results_dir = Path(args.results_dir or _default_results_dir(preset, config=config))
     try:
         return runner.run(preset, results_dir=results_dir, dry_run=args.dry_run)
     except RuntimeError as exc:
@@ -55,41 +158,23 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
 
-def _build_parser() -> argparse.ArgumentParser:
-    """Construct the :mod:`argparse` parser for ``sampleworks-runs``.
+def _build_parser(config: CliConfig) -> argparse.ArgumentParser:
+    """Construct the :mod:`argparse` parser for a configured runner CLI.
+
+    Parameters
+    ----------
+    config : CliConfig
+        CLI behavior and help-text configuration.
 
     Returns
     -------
     argparse.ArgumentParser
         Parser covering preset selection, overrides, and execution flags.
     """
-    parser = argparse.ArgumentParser(
-        prog="sampleworks-runs",
-        description=(
-            "Run Sampleworks experiment presets. With no target, runs the "
-            "full_8gpu preset. A target like 'rf3', 'boltz', or 'protenix' "
-            "runs that preset; comma-separated targets like 'rf3,protenix' "
-            "select jobs from full_8gpu."
-        ),
-    )
-    parser.add_argument(
-        "target",
-        nargs="?",
-        help=(
-            "Preset name from experiments/ (rf3, boltz, protenix, etc.), "
-            "comma-separated job shortcut from full_8gpu, or 'full'/'full_8gpu'."
-        ),
-    )
-    parser.add_argument(
-        "--preset",
-        default="",
-        help="Preset name from experiments/ or path to a .toml file. Default: full_8gpu.",
-    )
-    parser.add_argument(
-        "--list",
-        action="store_true",
-        help="List experiments/*.toml presets and exit",
-    )
+    parser = argparse.ArgumentParser(prog=config.prog, description=config.description)
+    parser.add_argument("target", nargs="?", help=config.target_help)
+    parser.add_argument("--preset", default="", help=config.preset_help)
+    parser.add_argument("--list", action="store_true", help=config.list_help)
     parser.add_argument("--show", action="store_true", help="Print the resolved preset and exit")
     parser.add_argument(
         "--dry-run",
@@ -116,7 +201,7 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--results-dir",
         default=None,
-        help="Override RESULTS_DIR for this run (also controls per-job log location).",
+        help="Override the runner results/log directory for this run.",
     )
     return parser
 
@@ -126,6 +211,8 @@ def _resolve_target(
     preset: str,
     jobs: str,
     parser: argparse.ArgumentParser,
+    *,
+    config: CliConfig = EXPERIMENT_CLI_CONFIG,
 ) -> tuple[str, str]:
     """Resolve the user-facing target grammar into preset plus job filter.
 
@@ -133,15 +220,17 @@ def _resolve_target(
     ----------
     target : str or None
         Optional positional target. Without ``--preset`` this is either a
-        default preset alias (``full``/``full_8gpu``/``all``) or a job selector
-        from :data:`DEFAULT_PRESET`. With ``--preset`` it is a shorthand job
-        selector for that explicit preset.
+        default preset alias or a job selector from the configured default
+        preset. With ``--preset`` it is a shorthand job selector for that
+        explicit preset.
     preset : str
         Explicit preset name/path from ``--preset``.
     jobs : str
         Explicit comma-separated job selector from ``--jobs``.
     parser : argparse.ArgumentParser
         Parser used to report grammar errors.
+    config : CliConfig, optional
+        CLI behavior and preset-directory configuration.
 
     Returns
     -------
@@ -153,8 +242,8 @@ def _resolve_target(
             parser.error("pass jobs either as the positional target or with --jobs, not both")
         return preset, jobs or target or ""
 
-    if target is None or target in DEFAULT_PRESET_ALIASES:
-        return DEFAULT_PRESET, jobs
+    if target is None or target in config.default_aliases:
+        return config.default_preset, jobs
 
     if jobs:
         parser.error("pass jobs either as the positional target or with --jobs, not both")
@@ -162,10 +251,13 @@ def _resolve_target(
     if target.endswith(".toml") or "/" in target:
         parser.error("pass custom preset paths with --preset path/to/preset.toml")
 
-    if "," not in target and target in loader.list_presets():
+    if "," not in target and target in loader.list_presets(
+        preset_dir_name=config.preset_dir_name,
+        preset_dir_env_var=config.preset_dir_env_var,
+    ):
         return target, ""
 
-    return DEFAULT_PRESET, target
+    return config.default_preset, target
 
 
 def _filter_jobs(preset: Preset, jobs: str) -> Preset:
@@ -228,35 +320,39 @@ def _print_show(preset: Preset) -> None:
             print(f"    gpus: {j.gpus}")
         else:
             print(f"    gpu_count: {j.gpu_count}")
+        if j.script:
+            print(f"    script: {j.script}")
         print(f"    output_subdir: {j.output_subdir}")
+        if j.output_arg != "output-dir":
+            print(f"    output_arg: {j.output_arg!r}")
         print("    args:")
         for k, v in j.args.items():
             print(f"      {k} = {v!r}")
 
 
-def _default_results_dir(preset: Preset) -> str:
+def _default_results_dir(preset: Preset, *, config: CliConfig = EXPERIMENT_CLI_CONFIG) -> str:
     """Pick a sensible default ``--results-dir`` when none is given.
 
-    Order of preference:
-      1. The preset's ``[defaults]`` ``RESULTS_DIR``.
-      2. The ``RESULTS_DIR`` environment variable.
-      3. ``./grid_search_results``.
-
     Parameters
     ----------
     preset : Preset
         Resolved preset (its ``defaults`` have already been merged with env).
+    config : CliConfig, optional
+        CLI behavior and result-directory fallback configuration.
 
     Returns
     -------
     str
-        Path to use as the run's root output directory.
+        Path to use as the run's root output/log directory.
     """
-    return (
-        preset.defaults.get("RESULTS_DIR")
-        or os.environ.get("RESULTS_DIR")
-        or "./grid_search_results"
-    )
+    for key in config.results_default_keys:
+        if preset.defaults.get(key):
+            return preset.defaults[key]
+    for env_var in config.results_env_vars:
+        value = os.environ.get(env_var)
+        if value:
+            return value
+    return config.results_fallback
 
 
 if __name__ == "__main__":
diff --git a/src/sampleworks/runs/loader.py b/src/sampleworks/runs/loader.py
index fcec6441..c9e1d287 100644
--- a/src/sampleworks/runs/loader.py
+++ b/src/sampleworks/runs/loader.py
@@ -21,23 +21,39 @@
 
 
 _EXPERIMENTS_DIR_NAME = "experiments"
+_EXPERIMENTS_DIR_ENV_VAR = "SAMPLEWORKS_EXPERIMENTS_DIR"
 _MAX_EXPAND_ITERATIONS = 32
 _VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
 _TOP_LEVEL_KEYS = frozenset({"description", "defaults", "shared_args", "jobs"})
 
 
-def list_presets() -> list[str]:
-    """List experiment preset names from the top-level ``experiments`` directory.
+def list_presets(
+    *,
+    preset_dir_name: str = _EXPERIMENTS_DIR_NAME,
+    preset_dir_env_var: str = _EXPERIMENTS_DIR_ENV_VAR,
+) -> list[str]:
+    """List preset names from a top-level preset directory.
+
+    Parameters
+    ----------
+    preset_dir_name : str, optional
+        Top-level directory name to search, e.g. ``"experiments"`` or
+        ``"analyses"``.
+    preset_dir_env_var : str, optional
+        Environment variable that can override the preset directory path.
 
     Returns
     -------
     list of str
         Preset names (filename stems, no ``.toml`` extension), sorted
-        alphabetically. If multiple experiment directories are visible, the
-        first directory in the resolution order wins for duplicate names.
+        alphabetically. If multiple preset directories are visible, the first
+        directory in the resolution order wins for duplicate names.
     """
     names: dict[str, Path] = {}
-    for directory in _experiment_dirs():
+    for directory in _preset_dirs(
+        preset_dir_name=preset_dir_name,
+        preset_dir_env_var=preset_dir_env_var,
+    ):
         if not directory.is_dir():
             continue
         for path in directory.iterdir():
@@ -46,17 +62,28 @@ def list_presets() -> list[str]:
     return sorted(names)
 
 
-def load_preset(name_or_path: str, *, overrides: Iterable[str] = ()) -> Preset:
+def load_preset(
+    name_or_path: str,
+    *,
+    overrides: Iterable[str] = (),
+    preset_dir_name: str = _EXPERIMENTS_DIR_NAME,
+    preset_dir_env_var: str = _EXPERIMENTS_DIR_ENV_VAR,
+) -> Preset:
     """Load a preset by experiment name or filesystem path.
 
     Parameters
     ----------
     name_or_path : str
-        Either the name of a preset in the top-level ``experiments`` directory
+        Either the name of a preset in the configured top-level preset directory
         (as returned by :func:`list_presets`) or a path ending in ``.toml``.
     overrides : Iterable of str, optional
         ``KEY=VALUE`` strings as accepted by ``--set``. Applied before
         variable interpolation.
+    preset_dir_name : str, optional
+        Top-level directory name to search, e.g. ``"experiments"`` or
+        ``"analyses"``.
+    preset_dir_env_var : str, optional
+        Environment variable that can override the preset directory path.
 
     Returns
     -------
@@ -74,20 +101,33 @@ def load_preset(name_or_path: str, *, overrides: Iterable[str] = ()) -> Preset:
     ValueError
         If an override is malformed (missing ``=``).
     """
-    raw = _read_toml(name_or_path)
+    raw = _read_toml(
+        name_or_path,
+        preset_dir_name=preset_dir_name,
+        preset_dir_env_var=preset_dir_env_var,
+    )
     overrides_list = list(overrides)
     raw = _apply_overrides(raw, overrides_list)
     raw = _resolve_variables(raw)
     return _build_preset(name=_preset_name(name_or_path), raw=raw)
 
 
-def _read_toml(name_or_path: str) -> dict[str, Any]:
+def _read_toml(
+    name_or_path: str,
+    *,
+    preset_dir_name: str = _EXPERIMENTS_DIR_NAME,
+    preset_dir_env_var: str = _EXPERIMENTS_DIR_ENV_VAR,
+) -> dict[str, Any]:
     """Read raw TOML from a filesystem path or an experiment preset name.
 
     Parameters
     ----------
     name_or_path : str
         Experiment preset name or filesystem path ending in ``.toml``.
+    preset_dir_name : str, optional
+        Top-level directory name to search.
+    preset_dir_env_var : str, optional
+        Environment variable that can override the preset directory path.
 
     Returns
     -------
@@ -99,16 +139,26 @@ def _read_toml(name_or_path: str) -> dict[str, Any]:
     FileNotFoundError
         If neither location yields a TOML file.
     """
-    path = _find_preset_path(name_or_path)
+    path = _find_preset_path(
+        name_or_path,
+        preset_dir_name=preset_dir_name,
+        preset_dir_env_var=preset_dir_env_var,
+    )
     if path is not None:
         return tomllib.loads(path.read_text())
     raise FileNotFoundError(
-        f"No preset {name_or_path!r}. Experiments: {list_presets()}. "
-        "Put TOML presets in ./experiments or pass a path to a .toml file."
+        f"No preset {name_or_path!r}. Presets: "
+        f"{list_presets(preset_dir_name=preset_dir_name, preset_dir_env_var=preset_dir_env_var)}. "
+        f"Put TOML presets in ./{preset_dir_name} or pass a path to a .toml file."
     )
 
 
-def _find_preset_path(name_or_path: str) -> Path | None:
+def _find_preset_path(
+    name_or_path: str,
+    *,
+    preset_dir_name: str = _EXPERIMENTS_DIR_NAME,
+    preset_dir_env_var: str = _EXPERIMENTS_DIR_ENV_VAR,
+) -> Path | None:
     """Resolve a preset name or path to a TOML file.
 
     Parameters
@@ -116,6 +166,10 @@ def _find_preset_path(name_or_path: str) -> Path | None:
     name_or_path : str
         Preset name (``full_8gpu``), TOML filename (``full_8gpu.toml``), or
         filesystem path.
+    preset_dir_name : str, optional
+        Top-level directory name to search.
+    preset_dir_env_var : str, optional
+        Environment variable that can override the preset directory path.
 
     Returns
     -------
@@ -127,35 +181,47 @@ def _find_preset_path(name_or_path: str) -> Path | None:
         return path
 
     preset_filename = path.name if path.suffix == ".toml" else f"{name_or_path}.toml"
-    for directory in _experiment_dirs():
+    for directory in _preset_dirs(
+        preset_dir_name=preset_dir_name,
+        preset_dir_env_var=preset_dir_env_var,
+    ):
         candidate = directory / preset_filename
         if candidate.is_file():
             return candidate
     return None
 
 
-def _experiment_dirs() -> list[Path]:
-    """Return candidate top-level experiment directories in precedence order.
+def _preset_dirs(*, preset_dir_name: str, preset_dir_env_var: str) -> list[Path]:
+    """Return candidate top-level preset directories in precedence order.
+
+    Parameters
+    ----------
+    preset_dir_name : str
+        Top-level directory name to search.
+    preset_dir_env_var : str
+        Environment variable that can override the preset directory path.
 
     Returns
     -------
     list of pathlib.Path
-        Existing or candidate ``experiments`` directories. Duplicates are
-        removed while preserving order.
+        Existing or candidate preset directories. Duplicates are removed while
+        preserving order.
     """
     candidates: list[Path] = []
 
-    explicit = os.environ.get("SAMPLEWORKS_EXPERIMENTS_DIR")
+    explicit = os.environ.get(preset_dir_env_var)
     if explicit:
         candidates.append(Path(explicit))
 
     source_dir = os.environ.get("SAMPLEWORKS_SOURCE_DIR")
     if source_dir:
-        candidates.append(Path(source_dir) / _EXPERIMENTS_DIR_NAME)
+        candidates.append(Path(source_dir) / preset_dir_name)
 
-    candidates.append(Path("/home/dev/workspace") / _EXPERIMENTS_DIR_NAME)
-    candidates.extend(_find_upward_experiment_dirs(Path.cwd()))
-    candidates.extend(_find_upward_experiment_dirs(Path(__file__).resolve()))
+    candidates.append(Path("/home/dev/workspace") / preset_dir_name)
+    candidates.extend(_find_upward_preset_dirs(Path.cwd(), preset_dir_name=preset_dir_name))
+    candidates.extend(
+        _find_upward_preset_dirs(Path(__file__).resolve(), preset_dir_name=preset_dir_name)
+    )
 
     seen: set[Path] = set()
     unique: list[Path] = []
@@ -167,23 +233,25 @@ def _experiment_dirs() -> list[Path]:
     return unique
 
 
-def _find_upward_experiment_dirs(start: Path) -> list[Path]:
-    """Search parents of ``start`` for top-level ``experiments`` directories.
+def _find_upward_preset_dirs(start: Path, *, preset_dir_name: str) -> list[Path]:
+    """Search parents of ``start`` for top-level preset directories.
 
     Parameters
     ----------
     start : pathlib.Path
         Directory or file path to begin searching from.
+    preset_dir_name : str
+        Top-level directory name to search.
 
     Returns
     -------
     list of pathlib.Path
-        Candidate experiment directories nearest to farthest.
+        Candidate preset directories nearest to farthest.
     """
     current = start if start.is_dir() else start.parent
     dirs: list[Path] = []
     for parent in [current, *current.parents]:
-        candidate = parent / _EXPERIMENTS_DIR_NAME
+        candidate = parent / preset_dir_name
         if candidate.is_dir():
             dirs.append(candidate)
     return dirs
@@ -508,6 +576,8 @@ def _build_preset(*, name: str, raw: dict[str, Any]) -> Preset:
             output_subdir=str(j["output_subdir"]),
             gpus=str(j.get("gpus", "")),
             gpu_count=_optional_int(j.get("gpu_count")),
+            script=str(j.get("script", "")),
+            output_arg=str(j.get("output_arg", "output-dir")),
             args=dict(j.get("args", {})),
         )
         for j in raw_jobs
diff --git a/src/sampleworks/runs/runner.py b/src/sampleworks/runs/runner.py
index 4f6a44d9..33dbee58 100644
--- a/src/sampleworks/runs/runner.py
+++ b/src/sampleworks/runs/runner.py
@@ -17,6 +17,7 @@
 
 DEFAULT_GRID_SEARCH_SCRIPT = "/app/run_grid_search.py"
 WORKSPACE_GRID_SEARCH_SCRIPT = "/home/dev/workspace/run_grid_search.py"
+DISABLE_GPU_ASSIGNMENTS = frozenset({"none", "void", "nodevfiles"})
 PROCESS_SHUTDOWN_TIMEOUT_SECONDS = 10
 TEE_THREAD_JOIN_TIMEOUT_SECONDS = 5
 
@@ -31,7 +32,7 @@ class JobInvocation:
         Originating :class:`Job` (kept for introspection in logs).
     argv : list of str
         Subprocess command line, preferably the baked pixi env Python followed
-        by ``run_grid_search.py``.
+        by the job script.
     env : dict of str to str
         Process environment, including ``CUDA_VISIBLE_DEVICES``.
     gpus : str
@@ -40,8 +41,9 @@ class JobInvocation:
     log_path : Path
         File to tee stdout+stderr into.
     output_dir : Path
-        Resolved ``--output-dir`` value (mkdir'd by the runner before launch
-        because ``run_grid_search.py`` assumes its existence).
+        Directory mkdir'd by the runner before launch. Experiment jobs use this
+        as their injected ``--output-dir``; analysis jobs can use it only as a
+        side-effect directory for logs or scratch space.
     """
 
     job: Job
@@ -55,9 +57,9 @@ class JobInvocation:
 def build_invocations(preset: Preset, *, results_dir: Path) -> list[JobInvocation]:
     """Build the subprocess invocation for every job in the preset.
 
-    Per-job ``args`` are merged on top of :attr:`Preset.shared_args`, with
-    ``--output-dir`` auto-injected from ``results_dir / job.output_subdir`` if
-    not already present.
+    Per-job ``args`` are merged on top of :attr:`Preset.shared_args`, with a
+    job-specific output argument auto-injected from
+    ``results_dir / job.output_subdir`` when configured and absent.
 
     Parameters
     ----------
@@ -75,12 +77,14 @@ def build_invocations(preset: Preset, *, results_dir: Path) -> list[JobInvocatio
     invocations: list[JobInvocation] = []
     for job in preset.jobs:
         args = preset.effective_args(job)
-        args.setdefault("output-dir", str(results_dir / job.output_subdir))
-        argv = _build_argv(job.env, args)
+        output_dir = results_dir / job.output_subdir
+        if job.output_arg:
+            args.setdefault(job.output_arg, str(output_dir))
+            output_dir = Path(args[job.output_arg])
+        argv = _build_argv(job.env, args, script=job.script or None)
         gpus = gpu_assignments[job.name]
         env = _job_env(job.env, {**os.environ, "CUDA_VISIBLE_DEVICES": gpus})
         log_path = results_dir / f"{job.name}_run.log"
-        output_dir = Path(args["output-dir"])
         invocations.append(
             JobInvocation(
                 job=job,
@@ -163,6 +167,22 @@ def _split_gpu_list(value: str) -> list[str]:
     return [part.strip() for part in value.split(",") if part.strip()]
 
 
+def _gpu_assignment_disables_gpus(value: str) -> bool:
+    """Return True when an explicit assignment intentionally hides all GPUs.
+
+    Parameters
+    ----------
+    value : str
+        CUDA_VISIBLE_DEVICES assignment from a job, such as ``"none"``.
+
+    Returns
+    -------
+    bool
+        True when ``value`` is one of the CUDA-recognized no-GPU tokens.
+    """
+    return value.strip().lower() in DISABLE_GPU_ASSIGNMENTS
+
+
 def _all_integer_tokens(values: list[str]) -> bool:
     """Return True when every GPU token is a CUDA ordinal.
 
@@ -211,11 +231,7 @@ def _detect_available_gpus() -> list[str]:
 
 def _cuda_visible_devices_disables_gpus() -> bool:
     """Return True when CUDA_VISIBLE_DEVICES explicitly hides all GPUs."""
-    return os.environ.get("CUDA_VISIBLE_DEVICES", "").strip().lower() in {
-        "none",
-        "void",
-        "nodevfiles",
-    }
+    return _gpu_assignment_disables_gpus(os.environ.get("CUDA_VISIBLE_DEVICES", ""))
 
 
 def _validate_gpu_assignments(invocations: list[JobInvocation]) -> None:
@@ -239,6 +255,8 @@ def _validate_gpu_assignments(invocations: list[JobInvocation]) -> None:
 
     requested: dict[str, list[str]] = {}
     for inv in invocations:
+        if _gpu_assignment_disables_gpus(inv.gpus):
+            continue
         for gpu in _split_gpu_list(inv.gpus):
             requested.setdefault(gpu, []).append(inv.job.name)
 
@@ -274,7 +292,7 @@ def _validate_gpu_assignments(invocations: list[JobInvocation]) -> None:
         )
 
 
-def _build_argv(pixi_env: str, args: dict[str, Any]) -> list[str]:
+def _build_argv(pixi_env: str, args: dict[str, Any], *, script: str | None = None) -> list[str]:
     """Assemble the ``pixi run`` argv list for one job's args dict.
 
     ``True`` bools become bare flags, ``False``/``None`` are dropped, all other
@@ -286,31 +304,56 @@ def _build_argv(pixi_env: str, args: dict[str, Any]) -> list[str]:
         Pixi environment name passed to ``-e``.
     args : dict of str to Any
         Flag-name to value map (kebab-case keys, no leading ``--``).
+    script : str or None, optional
+        Script path to execute. If ``None``, the default grid-search script is
+        used for backward-compatible experiment presets.
 
     Returns
     -------
     list of str
         Subprocess argv.
     """
+    script_path = _resolve_script_path(script)
     env_python = _pixi_env_python(pixi_env)
     if env_python:
-        argv = [env_python, _grid_search_script()]
+        argv = [env_python, script_path]
     elif _require_prebuilt_envs():
         raise RuntimeError(_missing_prebuilt_env_message(pixi_env))
     else:
-        argv = ["pixi", "run", "-e", pixi_env, "python", _grid_search_script()]
+        argv = ["pixi", "run", "-e", pixi_env, "python", script_path]
     for key, value in args.items():
-        flag = f"--{key}"
-        if isinstance(value, bool):
-            if value:
-                argv.append(flag)
-        elif value is None:
-            continue
-        else:
-            argv.extend([flag, str(value)])
+        _append_cli_arg(argv, key, value)
     return argv
 
 
+def _append_cli_arg(argv: list[str], key: str, value: Any) -> None:
+    """Append one TOML-configured CLI argument to ``argv``.
+
+    Parameters
+    ----------
+    argv : list of str
+        Mutable command vector to extend.
+    key : str
+        Flag name without leading ``--``.
+    value : Any
+        TOML value. ``True`` emits a bare flag, ``False``/``None`` are omitted,
+        lists emit one flag followed by one value per element, and all other
+        values are stringified.
+    """
+    flag = f"--{key}"
+    if isinstance(value, bool):
+        if value:
+            argv.append(flag)
+    elif value is None:
+        return
+    elif isinstance(value, (list, tuple)):
+        if value:
+            argv.append(flag)
+            argv.extend(str(item) for item in value)
+    else:
+        argv.extend([flag, str(value)])
+
+
 def _pixi_env_python(pixi_env: str) -> str | None:
     """Return the direct Python binary for a baked pixi environment when available.
 
@@ -466,6 +509,67 @@ def _grid_search_script() -> str:
     return DEFAULT_GRID_SEARCH_SCRIPT
 
 
+def _resolve_script_path(script: str | None) -> str:
+    """Resolve a job script path for subprocess execution.
+
+    Parameters
+    ----------
+    script : str or None
+        Script configured by a TOML job. Empty/``None`` selects the historical
+        ``run_grid_search.py`` default.
+
+    Returns
+    -------
+    str
+        Absolute path when the script can be found in a known Sampleworks
+        checkout, otherwise the original expanded path so subprocess startup
+        errors remain clear.
+    """
+    if not script:
+        return _grid_search_script()
+
+    expanded = Path(os.path.expandvars(script)).expanduser()
+    if expanded.is_absolute():
+        return str(expanded)
+
+    for root in _source_root_candidates():
+        candidate = root / expanded
+        if candidate.exists():
+            return str(candidate)
+    return str(expanded)
+
+
+def _source_root_candidates() -> list[Path]:
+    """Return likely Sampleworks checkout roots for relative script paths.
+
+    Returns
+    -------
+    list of pathlib.Path
+        Candidate directories in precedence order, deduplicated after
+        expansion. The synced ACTL checkout and current working directory are
+        preferred over stale files under the baked image.
+    """
+    candidates: list[Path] = []
+    for env_var in ("SAMPLEWORKS_SOURCE_DIR", "SAMPLEWORKS_SCRIPT_ROOT"):
+        override = os.environ.get(env_var)
+        if override:
+            candidates.append(Path(override))
+
+    candidates.append(Path("/home/dev/workspace"))
+    candidates.extend([Path.cwd(), *Path.cwd().parents])
+    module_path = Path(__file__).resolve()
+    candidates.extend([module_path.parent, *module_path.parents])
+
+    seen: set[Path] = set()
+    unique: list[Path] = []
+    for candidate in candidates:
+        resolved = candidate.expanduser().resolve(strict=False)
+        if resolved not in seen:
+            seen.add(resolved)
+            unique.append(resolved)
+    return unique
+
+
 def run(preset: Preset, *, results_dir: Path, dry_run: bool = False) -> int:
     """Launch every job in parallel and wait for completion.
 
diff --git a/src/sampleworks/runs/schema.py b/src/sampleworks/runs/schema.py
index 9cb99fac..f9b84201 100644
--- a/src/sampleworks/runs/schema.py
+++ b/src/sampleworks/runs/schema.py
@@ -1,9 +1,11 @@
-"""Dataclasses for the preset schema.
-
-A preset describes one or more parallel ``run_grid_search.py`` jobs. Each job
-runs in its configured model environment, either through ``pixi run`` or a
-baked environment Python, with ``CUDA_VISIBLE_DEVICES`` set from an explicit
-GPU assignment or an automatically allocated ``gpu_count``.
+"""Dataclasses for the run preset schema.
+
+A preset describes one or more parallel script jobs. Experiment presets default
+to ``run_grid_search.py`` while analysis presets set ``script`` explicitly to
+one of the evaluation scripts. Each job runs in its configured pixi environment,
+either through ``pixi run`` or a baked environment Python, with
+``CUDA_VISIBLE_DEVICES`` set from an explicit GPU assignment or an automatically
+allocated ``gpu_count``.
 """
 
 from __future__ import annotations
@@ -12,12 +14,22 @@
 from typing import Any
 
 
-VALID_PIXI_ENVS = ("boltz", "protenix", "rf3")
+VALID_PIXI_ENVS = (
+    "analysis",
+    "analysis-dev",
+    "boltz",
+    "boltz-analysis",
+    "boltz-dev",
+    "protenix",
+    "protenix-dev",
+    "rf3",
+    "rf3-dev",
+)
 
 
 @dataclass(frozen=True)
 class Job:
-    """One parallel `run_grid_search.py` invocation within a preset.
+    """One parallel script invocation within a preset.
 
     Parameters
     ----------
@@ -29,13 +41,24 @@ class Job:
         :data:`VALID_PIXI_ENVS`.
     gpus : str
         Explicit value to set as ``CUDA_VISIBLE_DEVICES`` for the subprocess
-        (e.g. ``"4"`` or ``"0,1"``). Mutually exclusive with ``gpu_count``.
+        (e.g. ``"4"``, ``"0,1"``, or ``"none"`` for CPU-only jobs). Mutually
+        exclusive with ``gpu_count``.
     gpu_count : int or None, optional
         Number of visible GPUs to auto-assign for this job. The runner assigns
         concrete GPU IDs in declaration order.
     output_subdir : str
         Path appended to the run's ``results_dir`` to form the job's
-        ``--output-dir`` argument, when one is not given explicitly in ``args``.
+        output argument, when one is not given explicitly in ``args``. Also used
+        as the directory the runner creates before launch.
+    script : str, optional
+        Script path to execute for this job. Relative paths are resolved against
+        the active Sampleworks checkout. If empty, the runner uses its default
+        experiment script.
+    output_arg : str, optional
+        CLI flag name that should receive ``results_dir / output_subdir`` when
+        absent from ``args``. The default is ``"output-dir"`` for experiment
+        runs. Set to ``""`` for scripts, such as analysis/eval scripts, that do
+        not accept an output directory flag.
     args : dict of str to Any, optional
         Per-job overrides merged on top of the preset's
         :attr:`Preset.shared_args`. Keys are CLI flag names (without the
@@ -54,6 +77,8 @@ class Job:
     output_subdir: str
     gpus: str = ""
     gpu_count: int | None = None
+    script: str = ""
+    output_arg: str = "output-dir"
     args: dict[str, Any] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
@@ -68,6 +93,10 @@ def __post_init__(self) -> None:
             raise ValueError(f"Job {self.name!r}: gpu_count must be positive")
         if not self.output_subdir:
             raise ValueError(f"Job {self.name!r}: output_subdir must be non-empty")
+        if self.output_arg.startswith("--"):
+            raise ValueError(
+                f"Job {self.name!r}: output_arg must omit leading dashes, got {self.output_arg!r}"
+            )
 
 
 @dataclass(frozen=True)
diff --git a/tests/runs/test_runner.py b/tests/runs/test_runner.py
index 04a4b1b0..02c5e294 100644
--- a/tests/runs/test_runner.py
+++ b/tests/runs/test_runner.py
@@ -5,7 +5,7 @@
 from pathlib import Path
 
 import pytest
-from sampleworks.runs import loader, runner
+from sampleworks.runs import analysis_cli, loader, runner
 
 
 def test_argv_for_rf3_partial_matches_bash(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -267,6 +267,86 @@ def test_dry_run_does_not_create_directories(
     assert not (results_dir / "rf3").exists()
 
 
+def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Analysis TOML presets run eval scripts without injecting --output-dir."""
+    repo_root = Path(__file__).resolve().parents[2]
+    monkeypatch.setenv("HOME", "/home/test")
+    monkeypatch.setenv("SAMPLEWORKS_SOURCE_DIR", str(repo_root))
+    monkeypatch.setattr(runner, "_detect_available_gpus", lambda: ["0"])
+    preset = loader.load_preset(
+        "grid_search",
+        overrides=[
+            "defaults.GRID_SEARCH_RESULTS_DIR=/grid/results",
+            "defaults.GRID_SEARCH_INPUTS_DIR=/grid/inputs",
+            "defaults.PROTEIN_CONFIGS_CSV=/grid/inputs/protein_analysis_config.csv",
+            "shared_args.n-jobs=2",
+        ],
+        preset_dir_name="analyses",
+        preset_dir_env_var="SAMPLEWORKS_ANALYSES_DIR",
+    )
+
+    invocations = runner.build_invocations(preset, results_dir=Path("/analysis-logs"))
+    rscc = invocations[0]
+
+    assert rscc.job.name == "rscc"
+    assert rscc.env["CUDA_VISIBLE_DEVICES"] == "0"
+    assert rscc.argv[:6] == [
+        "pixi",
+        "run",
+        "-e",
+        "analysis",
+        "python",
+        str(repo_root / "scripts/eval/rscc_grid_search_script.py"),
+    ]
+    assert "--output-dir" not in rscc.argv
+    assert rscc.output_dir == Path("/analysis-logs/analysis/rscc")
+    assert rscc.argv[rscc.argv.index("--grid-search-results-path") + 1] == "/grid/results"
+    assert rscc.argv[rscc.argv.index("--grid-search-inputs-path") + 1] == "/grid/inputs"
+    occupancy_index = rscc.argv.index("--occupancies")
+    assert rscc.argv[occupancy_index + 1 : occupancy_index + 6] == [
+        "0.0",
+        "0.25",
+        "0.5",
+        "0.75",
+        "1.0",
+    ]
+
+
+def test_analysis_cli_lists_analysis_presets(capsys: pytest.CaptureFixture[str]) -> None:
+    """The analysis entrypoint lists analyses/*.toml instead of experiments/*.toml."""
+    assert analysis_cli.main(["--list"]) == 0
+    listed = set(capsys.readouterr().out.splitlines())
+    assert {
+        "all",
+        "altloc_classify",
+        "altloc_find",
+        "external_tools",
+        "grid_search",
+    }.issubset(listed)
+
+
+def test_gpu_validation_ignores_cpu_jobs_but_checks_gpu_duplicates(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A gpus='none' analysis job must not disable validation for real GPU jobs."""
+    monkeypatch.setattr(runner, "_detect_available_gpus", lambda: ["0", "1"])
+    custom = tmp_path / "custom.toml"
+    custom.write_text(
+        "[shared_args]\n"
+        '[[jobs]]\nname = "cpu"\nenv = "analysis"\ngpus = "none"\noutput_subdir = "cpu"\n'
+        'script = "scripts/eval/bond_geometry_eval.py"\noutput_arg = ""\n'
+        '[[jobs]]\nname = "a"\nenv = "analysis"\ngpus = "0"\noutput_subdir = "a"\n'
+        'script = "scripts/eval/rscc_grid_search_script.py"\noutput_arg = ""\n'
+        '[[jobs]]\nname = "b"\nenv = "analysis"\ngpus = "0"\noutput_subdir = "b"\n'
+        'script = "scripts/eval/lddt_evaluation_script.py"\noutput_arg = ""\n'
+    )
+    preset = loader.load_preset(str(custom))
+    invocations = runner.build_invocations(preset, results_dir=tmp_path / "logs")
+
+    with pytest.raises(RuntimeError, match="same GPU"):
+        runner._validate_gpu_assignments(invocations)
+
+
 def _argv_to_dict(tail: list[str]) -> dict[str, object]:
     """Turn ``[--a, 1, --b, --c, 2]`` into ``{'--a': '1', '--b': True, '--c': '2'}``."""
     out: dict[str, object] = {}

From 144c9786626e78b0fa663d54306260cb99ceee44 Mon Sep 17 00:00:00 2001
From: xraymemory <me.anzuoni@gmail.com>
Date: Thu, 28 May 2026 16:24:45 -0400
Subject: [PATCH 2/4] feat(runs): automate analysis CIF patching

---
 README.md                         |   8 ++-
 analyses/all.toml                 |  13 ++++
 analyses/external_tools.toml      |  13 ++++
 analyses/grid_search.toml         |  13 ++++
 scripts/eval/EVALUATION.md        |  19 ++++--
 scripts/patch_output_cif_files.py |  45 ++++++++++---
 src/sampleworks/runs/cli.py       |  46 ++++++++-----
 src/sampleworks/runs/loader.py    |  43 ++++++++----
 src/sampleworks/runs/runner.py    | 104 +++++++++++++++++++++++++++---
 src/sampleworks/runs/schema.py    |  18 ++++--
 tests/runs/test_runner.py         |  53 ++++++++++++++-
 11 files changed, 316 insertions(+), 59 deletions(-)

diff --git a/README.md b/README.md
index a069a7c0..dbb1d517 100644
--- a/README.md
+++ b/README.md
@@ -251,6 +251,9 @@ rebuilt `pixi-with-checkpoints:sampleworks` image instead.
 
 `run_analysis` uses the same TOML runner as `run_experiments`, but loads presets
 from `analyses/*.toml` and runs the scripts under `scripts/eval/`.
+The `grid_search`, `all`, and `external_tools` presets first run a sequential
+`patch_outputs` pre-job, which creates `refined-patched.cif` files from each
+`refined.cif` before the evaluation jobs start.
 
 ```bash
 export GRID_SEARCH_RESULTS_DIR=/mnt/diffuse-shared/results/sampleworks/<pod>/full_8gpu
@@ -266,8 +269,9 @@ run_analysis all  # includes tortoize and phenix.clashscore jobs
 ```
 
 Use `--set` for one-off changes, for example
-`run_analysis rscc --set shared_args.target-filename=refined.cif` or
-`run_analysis rscc --set jobs.rscc.gpus=0`.
+`run_analysis rscc --set jobs.rscc.gpus=0`. If your input layout differs from
+the default `processed/{pdb_id}/{pdb_id}_single_001_density_input.cif`, override
+the patch pre-job with `--set defaults.PATCH_INPUT_PDB_PATTERN='{pdb_id}/{pdb_id}_original.cif'`.
 
 
 ## Docker
diff --git a/analyses/all.toml b/analyses/all.toml
index 02294cfa..281b9008 100644
--- a/analyses/all.toml
+++ b/analyses/all.toml
@@ -6,6 +6,10 @@ GRID_SEARCH_INPUTS_DIR = "/data/inputs"
 PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
 TARGET_FILENAME = "refined-patched.cif"
 N_JOBS = "16"
+PATCH_CIF_PATTERN = "refined.cif"
+PATCH_DEPTH = "4"
+PATCH_INPUT_PDB_PATTERN = "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
+PATCH_RCSB_PATTERN = "${GRID_SEARCH_RESULTS_DIR}/([A-Za-z0-9]{4})"
 
 [shared_args]
 grid-search-results-path = "${GRID_SEARCH_RESULTS_DIR}"
@@ -15,6 +19,15 @@ target-filename = "${TARGET_FILENAME}"
 occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
 n-jobs = "${N_JOBS}"
 
+[[pre_jobs]]
+name = "patch_outputs"
+env = "analysis"
+gpus = "none"
+script = "scripts/patch_output_cif_files.py"
+output_arg = ""
+output_subdir = "analysis/patch_outputs"
+args = { input-dir = "${GRID_SEARCH_RESULTS_DIR}", cif-pattern = "${PATCH_CIF_PATTERN}", rcsb-pattern = "${PATCH_RCSB_PATTERN}", depth = "${PATCH_DEPTH}", grid-search-input-dir = "${GRID_SEARCH_INPUTS_DIR}", input-pdb-pattern = "${PATCH_INPUT_PDB_PATTERN}" }
+
 [[jobs]]
 name = "rscc"
 env = "analysis"
diff --git a/analyses/external_tools.toml b/analyses/external_tools.toml
index 2ffa8226..bd1ed13f 100644
--- a/analyses/external_tools.toml
+++ b/analyses/external_tools.toml
@@ -6,6 +6,10 @@ GRID_SEARCH_INPUTS_DIR = "/data/inputs"
 PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
 TARGET_FILENAME = "refined-patched.cif"
 N_JOBS = "16"
+PATCH_CIF_PATTERN = "refined.cif"
+PATCH_DEPTH = "4"
+PATCH_INPUT_PDB_PATTERN = "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
+PATCH_RCSB_PATTERN = "${GRID_SEARCH_RESULTS_DIR}/([A-Za-z0-9]{4})"
 
 [shared_args]
 grid-search-results-path = "${GRID_SEARCH_RESULTS_DIR}"
@@ -15,6 +19,15 @@ target-filename = "${TARGET_FILENAME}"
 occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
 n-jobs = "${N_JOBS}"
 
+[[pre_jobs]]
+name = "patch_outputs"
+env = "analysis"
+gpus = "none"
+script = "scripts/patch_output_cif_files.py"
+output_arg = ""
+output_subdir = "analysis/patch_outputs"
+args = { input-dir = "${GRID_SEARCH_RESULTS_DIR}", cif-pattern = "${PATCH_CIF_PATTERN}", rcsb-pattern = "${PATCH_RCSB_PATTERN}", depth = "${PATCH_DEPTH}", grid-search-input-dir = "${GRID_SEARCH_INPUTS_DIR}", input-pdb-pattern = "${PATCH_INPUT_PDB_PATTERN}" }
+
 [[jobs]]
 name = "tortoize"
 env = "analysis"
diff --git a/analyses/grid_search.toml b/analyses/grid_search.toml
index 5cf68419..a9ac09f9 100644
--- a/analyses/grid_search.toml
+++ b/analyses/grid_search.toml
@@ -6,6 +6,10 @@ GRID_SEARCH_INPUTS_DIR = "/data/inputs"
 PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
 TARGET_FILENAME = "refined-patched.cif"
 N_JOBS = "16"
+PATCH_CIF_PATTERN = "refined.cif"
+PATCH_DEPTH = "4"
+PATCH_INPUT_PDB_PATTERN = "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
+PATCH_RCSB_PATTERN = "${GRID_SEARCH_RESULTS_DIR}/([A-Za-z0-9]{4})"
 
 [shared_args]
 grid-search-results-path = "${GRID_SEARCH_RESULTS_DIR}"
@@ -15,6 +19,15 @@ target-filename = "${TARGET_FILENAME}"
 occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
 n-jobs = "${N_JOBS}"
 
+[[pre_jobs]]
+name = "patch_outputs"
+env = "analysis"
+gpus = "none"
+script = "scripts/patch_output_cif_files.py"
+output_arg = ""
+output_subdir = "analysis/patch_outputs"
+args = { input-dir = "${GRID_SEARCH_RESULTS_DIR}", cif-pattern = "${PATCH_CIF_PATTERN}", rcsb-pattern = "${PATCH_RCSB_PATTERN}", depth = "${PATCH_DEPTH}", grid-search-input-dir = "${GRID_SEARCH_INPUTS_DIR}", input-pdb-pattern = "${PATCH_INPUT_PDB_PATTERN}" }
+
 [[jobs]]
 name = "rscc"
 env = "analysis"
diff --git a/scripts/eval/EVALUATION.md b/scripts/eval/EVALUATION.md
index 6cbbd4b2..c64228e7 100644
--- a/scripts/eval/EVALUATION.md
+++ b/scripts/eval/EVALUATION.md
@@ -21,10 +21,15 @@ coordinates, and not the additional information that many programs, like `tortoi
 `phenix.clashscore`, require. Furthermore, many protein structure predictors effectively 
 renumber residues. Since our metrics are frequently calculated by comparing selections of atoms or 
 residues, we must align to the original _sequence_ of the protein as well. Future versions of 
-Sampleworks will handle these issues automatically. For now, you should run the script
-`scripts/patch_output_cif_files.py`. This will use the original PDB inputs to reconstruct proper 
-output CIF files that are numbered correctly and
-have all necessary metadata to reconstruct the protein structure correctly.
+Sampleworks will handle these issues automatically. For direct script invocation, you should run
+the script `scripts/patch_output_cif_files.py`. This will use the original PDB inputs to
+reconstruct proper output CIF files that are numbered correctly and have all necessary metadata to
+reconstruct the protein structure correctly.
+
+The `run_analysis` presets automate this step for the `grid_search`, `all`, and `external_tools`
+presets: a sequential `patch_outputs` pre-job runs before evaluation jobs and writes
+`refined-patched.cif` files. Override `PATCH_INPUT_PDB_PATTERN`, `PATCH_RCSB_PATTERN`,
+`PATCH_CIF_PATTERN`, or `PATCH_DEPTH` if your input or output layout differs.
 
 You can run the following command, which assumes:
 - your sampleworks output is stored in `/home/ubuntu/grid_search_results`, 
@@ -68,9 +73,13 @@ run_analysis --list
 run_analysis grid_search --jobs rscc,lddt,bond_geometry
 run_analysis altloc_find
 run_analysis altloc_classify
-run_analysis rscc --set shared_args.target-filename=refined.cif
+run_analysis rscc --set defaults.PATCH_INPUT_PDB_PATTERN='{pdb_id}/{pdb_id}_original.cif'
 ```
 
+The `grid_search`, `all`, and `external_tools` presets run the CIF patching pre-step before these
+evaluation scripts. If you run the scripts directly, run `scripts/patch_output_cif_files.py` first
+or point `--target-filename` at files that already contain the required metadata.
+
 For direct script invocation, the equivalent command shape is:
 
 ```shell
diff --git a/scripts/patch_output_cif_files.py b/scripts/patch_output_cif_files.py
index 78966e2a..273b8667 100644
--- a/scripts/patch_output_cif_files.py
+++ b/scripts/patch_output_cif_files.py
@@ -92,11 +92,36 @@ def main(
     rcsb_regex: str = r"grid_search_results/(.{4})",
     depth: int = 4,
     input_pdb_pattern: str = "{pdb_id}/{pdb_id}_single_001_density_input.cif",
-) -> None:
+) -> int:
+    """Patch Sampleworks output CIF files for downstream evaluation tools.
+
+    Parameters
+    ----------
+    input_dir : str or Path
+        Directory containing generated Sampleworks CIF files.
+    grid_search_input_dir : str or Path
+        Root directory containing original input CIF files.
+    target_pattern : str
+        Filename pattern for generated CIFs to patch.
+    rcsb_regex : str, optional
+        Regular expression with one capture group for the RCSB ID.
+    depth : int, optional
+        Directory recursion depth below ``input_dir``.
+    input_pdb_pattern : str, optional
+        Format string for locating original input CIFs from ``pdb_id``.
+
+    Returns
+    -------
+    int
+        ``0`` when all matched files patch successfully, otherwise ``1``.
+    """
     # make sure the cache exists
     SAMPLEWORKS_CACHE.mkdir(parents=True, exist_ok=True)
 
     cif_files_to_patch = crawl_dir_by_depth(input_dir, target_pattern, n_levels=depth)
+    if not cif_files_to_patch:
+        logger.error(f"No CIF files matching {target_pattern!r} found under {input_dir}")
+        return 1
     results = joblib.Parallel()(
         joblib.delayed(patch_individual_cif_file)(
             f, rcsb_regex, Path(grid_search_input_dir), input_pdb_pattern
@@ -108,6 +133,8 @@ def main(
         logger.error("The following errors occurred:")
         for r in results:
             print(r)
+        return 1
+    return 0
 
 
 def patch_individual_cif_file(
@@ -233,11 +260,13 @@ def patch_individual_cif_file(
 
 if __name__ == "__main__":
     args = parse_args()
-    main(
-        args.input_dir,
-        args.grid_search_input_dir,
-        args.cif_pattern,
-        args.rcsb_pattern,
-        args.depth,
-        args.input_pdb_pattern,
+    raise SystemExit(
+        main(
+            args.input_dir,
+            args.grid_search_input_dir,
+            args.cif_pattern,
+            args.rcsb_pattern,
+            args.depth,
+            args.input_pdb_pattern,
+        )
     )
diff --git a/src/sampleworks/runs/cli.py b/src/sampleworks/runs/cli.py
index 5d61b06d..1613f2e9 100644
--- a/src/sampleworks/runs/cli.py
+++ b/src/sampleworks/runs/cli.py
@@ -9,7 +9,7 @@
 from pathlib import Path
 
 from . import loader, runner
-from .schema import Preset
+from .schema import Job, Preset
 
 
 DEFAULT_PRESET = "full_8gpu"
@@ -293,6 +293,7 @@ def _filter_jobs(preset: Preset, jobs: str) -> Preset:
         description=description,
         defaults=preset.defaults,
         shared_args=preset.shared_args,
+        pre_jobs=preset.pre_jobs,
         jobs=keep,
     )
 
@@ -312,22 +313,37 @@ def _print_show(preset: Preset) -> None:
         print("defaults:")
         for k, v in preset.defaults.items():
             print(f"  {k} = {v}")
+    if preset.pre_jobs:
+        print("pre_jobs:")
+        for j in preset.pre_jobs:
+            _print_job(j)
     print("jobs:")
     for j in preset.jobs:
-        print(f"  - name: {j.name}")
-        print(f"    env: {j.env}")
-        if j.gpus:
-            print(f"    gpus: {j.gpus}")
-        else:
-            print(f"    gpu_count: {j.gpu_count}")
-        if j.script:
-            print(f"    script: {j.script}")
-        print(f"    output_subdir: {j.output_subdir}")
-        if j.output_arg != "output-dir":
-            print(f"    output_arg: {j.output_arg!r}")
-        print("    args:")
-        for k, v in j.args.items():
-            print(f"      {k} = {v!r}")
+        _print_job(j)
+
+
+def _print_job(j: Job) -> None:
+    """Print one resolved preset job for ``--show``.
+
+    Parameters
+    ----------
+    j : Job
+        Job to print.
+    """
+    print(f"  - name: {j.name}")
+    print(f"    env: {j.env}")
+    if j.gpus:
+        print(f"    gpus: {j.gpus}")
+    else:
+        print(f"    gpu_count: {j.gpu_count}")
+    if j.script:
+        print(f"    script: {j.script}")
+    print(f"    output_subdir: {j.output_subdir}")
+    if j.output_arg != "output-dir":
+        print(f"    output_arg: {j.output_arg!r}")
+    print("    args:")
+    for k, v in j.args.items():
+        print(f"      {k} = {v!r}")
 
 
 def _default_results_dir(preset: Preset, *, config: CliConfig = EXPERIMENT_CLI_CONFIG) -> str:
diff --git a/src/sampleworks/runs/loader.py b/src/sampleworks/runs/loader.py
index c9e1d287..b2d446ef 100644
--- a/src/sampleworks/runs/loader.py
+++ b/src/sampleworks/runs/loader.py
@@ -24,7 +24,7 @@
 _EXPERIMENTS_DIR_ENV_VAR = "SAMPLEWORKS_EXPERIMENTS_DIR"
 _MAX_EXPAND_ITERATIONS = 32
 _VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
-_TOP_LEVEL_KEYS = frozenset({"description", "defaults", "shared_args", "jobs"})
+_TOP_LEVEL_KEYS = frozenset({"description", "defaults", "shared_args", "pre_jobs", "jobs"})
 
 
 def list_presets(
@@ -342,9 +342,9 @@ def _set_dotted(obj: dict[str, Any], dotted: str, value: Any) -> None:
         leaf_parent[_find_in_list(leaf_parent, leaf_key, where=dotted)] = value
     else:
         leaf_parent[leaf_key] = value
-        if parts[0] == "jobs" and len(parts) == 3 and leaf_key == "gpus":
+        if parts[0] in {"pre_jobs", "jobs"} and len(parts) == 3 and leaf_key == "gpus":
             leaf_parent.pop("gpu_count", None)
-        elif parts[0] == "jobs" and len(parts) == 3 and leaf_key == "gpu_count":
+        elif parts[0] in {"pre_jobs", "jobs"} and len(parts) == 3 and leaf_key == "gpu_count":
             leaf_parent.pop("gpus", None)
 
 
@@ -566,10 +566,38 @@ def _build_preset(*, name: str, raw: dict[str, Any]) -> Preset:
         If ``raw['jobs']`` is not a list, or if any :class:`Job` /
         :class:`Preset` invariant fails (see their docstrings).
     """
+    raw_pre_jobs = raw.get("pre_jobs", [])
     raw_jobs = raw.get("jobs", [])
+    if not isinstance(raw_pre_jobs, list):
+        raise ValueError(f"Preset {name!r}: 'pre_jobs' must be a list")
     if not isinstance(raw_jobs, list):
         raise ValueError(f"Preset {name!r}: 'jobs' must be a list")
-    jobs = [
+    pre_jobs = _build_jobs(raw_pre_jobs)
+    jobs = _build_jobs(raw_jobs)
+    return Preset(
+        name=name,
+        description=str(raw.get("description", "")),
+        defaults=dict(raw.get("defaults", {})),
+        shared_args=dict(raw.get("shared_args", {})),
+        pre_jobs=pre_jobs,
+        jobs=jobs,
+    )
+
+
+def _build_jobs(raw_jobs: list[Any]) -> list[Job]:
+    """Build :class:`Job` objects from raw TOML job dictionaries.
+
+    Parameters
+    ----------
+    raw_jobs : list of Any
+        Parsed TOML job entries.
+
+    Returns
+    -------
+    list of Job
+        Validated jobs.
+    """
+    return [
         Job(
             name=str(j["name"]),
             env=str(j["env"]),
@@ -582,13 +610,6 @@ def _build_preset(*, name: str, raw: dict[str, Any]) -> Preset:
         )
         for j in raw_jobs
     ]
-    return Preset(
-        name=name,
-        description=str(raw.get("description", "")),
-        defaults=dict(raw.get("defaults", {})),
-        shared_args=dict(raw.get("shared_args", {})),
-        jobs=jobs,
-    )
 
 
 def _optional_int(value: Any) -> int | None:
diff --git a/src/sampleworks/runs/runner.py b/src/sampleworks/runs/runner.py
index 33dbee58..846e5332 100644
--- a/src/sampleworks/runs/runner.py
+++ b/src/sampleworks/runs/runner.py
@@ -73,10 +73,57 @@ def build_invocations(preset: Preset, *, results_dir: Path) -> list[JobInvocatio
     list of JobInvocation
         One :class:`JobInvocation` per job, in declaration order.
     """
-    gpu_assignments = _resolve_gpu_assignments(preset.jobs)
+    return _build_invocations_for_jobs(
+        preset.jobs, preset=preset, results_dir=results_dir, include_shared_args=True
+    )
+
+
+def build_pre_invocations(preset: Preset, *, results_dir: Path) -> list[JobInvocation]:
+    """Build subprocess invocations for sequential preset pre-jobs.
+
+    Parameters
+    ----------
+    preset : Preset
+        Resolved preset to launch.
+    results_dir : Path
+        Root directory for outputs and per-job log files.
+
+    Returns
+    -------
+    list of JobInvocation
+        One :class:`JobInvocation` per pre-job, in declaration order.
+    """
+    return _build_invocations_for_jobs(
+        preset.pre_jobs, preset=preset, results_dir=results_dir, include_shared_args=False
+    )
+
+
+def _build_invocations_for_jobs(
+    jobs: list[Job], *, preset: Preset, results_dir: Path, include_shared_args: bool
+) -> list[JobInvocation]:
+    """Build subprocess invocations for a specific preset job phase.
+
+    Parameters
+    ----------
+    jobs : list of Job
+        Jobs to resolve into command lines.
+    preset : Preset
+        Parent preset whose shared args apply to each job.
+    results_dir : Path
+        Root directory for outputs and per-job log files.
+    include_shared_args : bool
+        If True, merge ``preset.shared_args`` into each job. Pre-jobs use False
+        because preparation scripts usually have different CLIs from main jobs.
+
+    Returns
+    -------
+    list of JobInvocation
+        Resolved invocations for ``jobs``.
+    """
+    gpu_assignments = _resolve_gpu_assignments(jobs)
     invocations: list[JobInvocation] = []
-    for job in preset.jobs:
-        args = preset.effective_args(job)
+    for job in jobs:
+        args = preset.effective_args(job) if include_shared_args else dict(job.args)
         output_dir = results_dir / job.output_subdir
         if job.output_arg:
             args.setdefault(job.output_arg, str(output_dir))
@@ -593,20 +640,31 @@ def run(preset: Preset, *, results_dir: Path, dry_run: bool = False) -> int:
     """
     results_dir = results_dir.resolve()
     results_dir.mkdir(parents=True, exist_ok=True)
+    pre_invocations = build_pre_invocations(preset, results_dir=results_dir)
     invocations = build_invocations(preset, results_dir=results_dir)
+    _validate_gpu_assignments(pre_invocations)
     _validate_gpu_assignments(invocations)
 
     if dry_run:
+        for inv in pre_invocations:
+            _print_dry_run(inv, phase="pre-job")
         for inv in invocations:
-            _print_dry_run(inv)
+            _print_dry_run(inv, phase="job")
         return 0
 
-    pixi_envs = sorted({inv.job.env for inv in invocations})
+    pixi_envs = sorted({inv.job.env for inv in [*pre_invocations, *invocations]})
     for pixi_env in pixi_envs:
         _prepare_pixi_env(pixi_env)
+    pre_invocations = build_pre_invocations(preset, results_dir=results_dir)
     invocations = build_invocations(preset, results_dir=results_dir)
 
-    _print_launch_summary(preset, invocations)
+    if pre_invocations:
+        _print_launch_summary(preset, pre_invocations, phase="pre-jobs")
+        pre_exit = _run_sequential(pre_invocations)
+        if pre_exit != 0:
+            return pre_exit
+
+    _print_launch_summary(preset, invocations, phase="jobs")
     processes: list[_RunningJob] = []
     try:
         for inv in invocations:
@@ -687,21 +745,25 @@ def _prepare_pixi_env(pixi_env: str) -> None:
     subprocess.run(cmd, cwd=str(_pixi_project_dir()), env=env, check=True)
 
 
-def _print_dry_run(inv: JobInvocation) -> None:
+def _print_dry_run(inv: JobInvocation, *, phase: str = "job") -> None:
     """Print the exact command for one job without launching it.
 
     Parameters
     ----------
     inv : JobInvocation
         Invocation to print.
+    phase : str, optional
+        Human-readable phase label for the dry-run header.
     """
-    print(f"# job: {inv.job.name}  (env={inv.job.env}, gpus={inv.gpus})", file=sys.stderr)
+    print(f"# {phase}: {inv.job.name}  (env={inv.job.env}, gpus={inv.gpus})", file=sys.stderr)
     print(f"# log: {inv.log_path}", file=sys.stderr)
     print(f"CUDA_VISIBLE_DEVICES={inv.gpus} {_shell_join(inv.argv)}")
     print(file=sys.stderr)
 
 
-def _print_launch_summary(preset: Preset, invocations: list[JobInvocation]) -> None:
+def _print_launch_summary(
+    preset: Preset, invocations: list[JobInvocation], *, phase: str = "jobs"
+) -> None:
     """Print a banner describing what is about to be launched.
 
     Parameters
@@ -710,10 +772,12 @@ def _print_launch_summary(preset: Preset, invocations: list[JobInvocation]) -> N
         Preset being launched.
     invocations : list of JobInvocation
         Jobs about to be spawned.
+    phase : str, optional
+        Phase label to print in the banner.
     """
     bar = "=" * 60
     print(bar, file=sys.stderr)
-    print(f"preset: {preset.name}", file=sys.stderr)
+    print(f"preset: {preset.name} ({phase})", file=sys.stderr)
     if preset.description:
         print(f"  {preset.description}", file=sys.stderr)
     for inv in invocations:
@@ -724,6 +788,26 @@ def _print_launch_summary(preset: Preset, invocations: list[JobInvocation]) -> N
     print(bar, file=sys.stderr)
 
 
+def _run_sequential(invocations: list[JobInvocation]) -> int:
+    """Run invocations one at a time, stopping at the first failure.
+
+    Parameters
+    ----------
+    invocations : list of JobInvocation
+        Pre-job invocations to run in order.
+
+    Returns
+    -------
+    int
+        ``0`` if all jobs succeed, otherwise ``1``.
+    """
+    for inv in invocations:
+        exit_code = _wait_all([_spawn(inv)])
+        if exit_code != 0:
+            return exit_code
+    return 0
+
+
 @dataclass(frozen=True)
 class _RunningJob:
     """Internal handle: a spawned subprocess and its log-tee thread.
diff --git a/src/sampleworks/runs/schema.py b/src/sampleworks/runs/schema.py
index f9b84201..2e2c3c31 100644
--- a/src/sampleworks/runs/schema.py
+++ b/src/sampleworks/runs/schema.py
@@ -1,11 +1,11 @@
 """Dataclasses for the run preset schema.
 
-A preset describes one or more parallel script jobs. Experiment presets default
-to ``run_grid_search.py`` while analysis presets set ``script`` explicitly to
-one of the evaluation scripts. Each job runs in its configured pixi environment,
-either through ``pixi run`` or a baked environment Python, with
-``CUDA_VISIBLE_DEVICES`` set from an explicit GPU assignment or an automatically
-allocated ``gpu_count``.
+A preset describes optional sequential pre-jobs followed by one or more parallel
+script jobs. Experiment presets default to ``run_grid_search.py`` while analysis
+presets set ``script`` explicitly to one of the evaluation scripts. Each job runs
+in its configured pixi environment, either through ``pixi run`` or a baked
+environment Python, with ``CUDA_VISIBLE_DEVICES`` set from an explicit GPU
+assignment or an automatically allocated ``gpu_count``.
 """
 
 from __future__ import annotations
@@ -116,6 +116,9 @@ class Preset:
     shared_args : dict of str to Any, optional
         Args merged into every job's ``args`` before argv is built. Per-job
         ``args`` win on collision.
+    pre_jobs : list of Job
+        Jobs that run sequentially before any main jobs. They are useful for
+        required preparation steps such as CIF patching.
     jobs : list of Job
         Jobs to launch in parallel. Must be non-empty and have unique names.
 
@@ -129,6 +132,7 @@ class Preset:
     description: str
     defaults: dict[str, str] = field(default_factory=dict)
     shared_args: dict[str, Any] = field(default_factory=dict)
+    pre_jobs: list[Job] = field(default_factory=list)
     jobs: list[Job] = field(default_factory=list)
 
     def __post_init__(self) -> None:
@@ -136,7 +140,7 @@ def __post_init__(self) -> None:
         if not self.jobs:
             raise ValueError(f"Preset {self.name!r}: must declare at least one job")
         seen: set[str] = set()
-        for job in self.jobs:
+        for job in [*self.pre_jobs, *self.jobs]:
             if job.name in seen:
                 raise ValueError(f"Preset {self.name!r}: duplicate job name {job.name!r}")
             seen.add(job.name)
diff --git a/tests/runs/test_runner.py b/tests/runs/test_runner.py
index 02c5e294..63fa0e0c 100644
--- a/tests/runs/test_runner.py
+++ b/tests/runs/test_runner.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sys
 from pathlib import Path
 
 import pytest
@@ -268,7 +269,7 @@ def test_dry_run_does_not_create_directories(
 
 
 def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Analysis TOML presets run eval scripts without injecting --output-dir."""
+    """Analysis TOML presets patch CIFs before running eval scripts."""
     repo_root = Path(__file__).resolve().parents[2]
     monkeypatch.setenv("HOME", "/home/test")
     monkeypatch.setenv("SAMPLEWORKS_SOURCE_DIR", str(repo_root))
@@ -285,9 +286,32 @@ def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.Monk
         preset_dir_env_var="SAMPLEWORKS_ANALYSES_DIR",
     )
 
+    pre_invocations = runner.build_pre_invocations(preset, results_dir=Path("/analysis-logs"))
     invocations = runner.build_invocations(preset, results_dir=Path("/analysis-logs"))
+    patch = pre_invocations[0]
     rscc = invocations[0]
 
+    assert patch.job.name == "patch_outputs"
+    assert patch.env["CUDA_VISIBLE_DEVICES"] == "none"
+    assert patch.argv[:6] == [
+        "pixi",
+        "run",
+        "-e",
+        "analysis",
+        "python",
+        str(repo_root / "scripts/patch_output_cif_files.py"),
+    ]
+    patch_args = _argv_to_dict(patch.argv[6:])
+    assert patch_args["--input-dir"] == "/grid/results"
+    assert patch_args["--grid-search-input-dir"] == "/grid/inputs"
+    assert patch_args["--cif-pattern"] == "refined.cif"
+    assert patch_args["--rcsb-pattern"] == "/grid/results/([A-Za-z0-9]{4})"
+    assert patch_args["--input-pdb-pattern"] == (
+        "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
+    )
+    assert "--target-filename" not in patch_args
+    assert "--protein-configs-csv" not in patch_args
+
     assert rscc.job.name == "rscc"
     assert rscc.env["CUDA_VISIBLE_DEVICES"] == "0"
     assert rscc.argv[:6] == [
@@ -312,6 +336,33 @@ def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.Monk
     ]
 
 
+def test_pre_jobs_run_before_main_jobs(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Sequential pre-jobs complete before regular jobs are launched."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("SAMPLEWORKS_PIXI_PROJECT_DIR", str(tmp_path))
+    monkeypatch.setenv("SAMPLEWORKS_ANALYSIS_PYTHON", sys.executable)
+    pre_script = tmp_path / "pre.py"
+    main_script = tmp_path / "main.py"
+    pre_script.write_text("from pathlib import Path\nPath('marker').write_text('pre')\n")
+    main_script.write_text(
+        "from pathlib import Path\n"
+        "assert Path('marker').read_text() == 'pre'\n"
+        "Path('main').write_text('main')\n"
+    )
+    custom = tmp_path / "custom.toml"
+    custom.write_text(
+        'description = "custom"\n'
+        '[[pre_jobs]]\nname = "pre"\nenv = "analysis"\ngpus = "none"\n'
+        f'script = "{pre_script}"\noutput_subdir = "pre"\noutput_arg = ""\n'
+        '[[jobs]]\nname = "main"\nenv = "analysis"\ngpus = "none"\n'
+        f'script = "{main_script}"\noutput_subdir = "main"\noutput_arg = ""\n'
+    )
+    preset = loader.load_preset(str(custom))
+
+    assert runner.run(preset, results_dir=tmp_path / "results") == 0
+    assert (tmp_path / "main").read_text() == "main"
+
+
 def test_analysis_cli_lists_analysis_presets(capsys: pytest.CaptureFixture[str]) -> None:
     """The analysis entrypoint lists analyses/*.toml instead of experiments/*.toml."""
     assert analysis_cli.main(["--list"]) == 0

From c62684a6f0751b13049502dea408fa76ac446f8e Mon Sep 17 00:00:00 2001
From: xraymemory <me.anzuoni@gmail.com>
Date: Thu, 28 May 2026 16:30:53 -0400
Subject: [PATCH 3/4] docs(runs): clarify filtered pre-jobs

---
 src/sampleworks/runs/cli.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/sampleworks/runs/cli.py b/src/sampleworks/runs/cli.py
index 1613f2e9..c6858dbe 100644
--- a/src/sampleworks/runs/cli.py
+++ b/src/sampleworks/runs/cli.py
@@ -274,7 +274,7 @@ def _filter_jobs(preset: Preset, jobs: str) -> Preset:
     -------
     Preset
         New preset with the same ``description``, ``defaults``, and
-        ``shared_args`` and only the filtered jobs.
+        ``shared_args``, all pre-jobs, and only the filtered main jobs.
 
     Raises
     ------

From fc9e8224adfbbec9d773f48baa936d768c4a27ba Mon Sep 17 00:00:00 2001
From: xraymemory <me.anzuoni@gmail.com>
Date: Sun, 31 May 2026 22:44:49 -0400
Subject: [PATCH 4/4] fix(runs): address analysis harness review comments

---
 Dockerfile                                    |  3 +-
 README.md                                     | 18 +++++---
 analyses/all.toml                             |  4 +-
 analyses/altloc_classify.toml                 | 10 ++---
 analyses/altloc_find.toml                     |  8 ++--
 ...d_search.toml => analyze_grid_search.toml} |  6 ++-
 analyses/external_tools.toml                  |  4 +-
 run_analysis                                  |  6 ++-
 scripts/eval/EVALUATION.md                    | 14 +++---
 .../eval/grid_search_eval_utils.py            | 12 ++++-
 src/sampleworks/runs/analysis_cli.py          | 20 ++++-----
 src/sampleworks/runs/cli.py                   | 29 ++++++++----
 src/sampleworks/runs/runner.py                | 18 ++++++--
 src/sampleworks/runs/schema.py                |  2 +-
 tests/runs/test_cli.py                        | 36 +++++++++++++++
 tests/runs/test_runner.py                     | 45 ++++++++++++++++---
 16 files changed, 178 insertions(+), 57 deletions(-)
 rename analyses/{grid_search.toml => analyze_grid_search.toml} (89%)

diff --git a/Dockerfile b/Dockerfile
index ef0eba2e..cacbd13b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -112,7 +112,8 @@ RUN if [ ! -e /dev/nvidiactl ] && [ ! -e /proc/driver/nvidia/version ]; then \
     else \
         pixi run -e boltz python -c "\
 from sampleworks.core.forward_models.xray.real_space_density_deps.ops import dilate_atom_centric; \
-print('CUDA extensions compiled successfully')" || echo "CUDA extension pre-compilation skipped (no GPU during build)"
+print('CUDA extensions compiled successfully')"; \
+    fi
 
 # This image carries pixi environments and checkpoints. Runtime source should
 # come from ACTL's synced checkout at /home/dev/workspace, not from stale code
diff --git a/README.md b/README.md
index de13fa8b..0949a887 100644
--- a/README.md
+++ b/README.md
@@ -251,7 +251,7 @@ rebuilt `pixi-with-checkpoints:sampleworks` image instead.
 
 `run_analysis` uses the same TOML runner as `run_experiments`, but loads presets
 from `analyses/*.toml` and runs the scripts under `scripts/eval/`.
-The `grid_search`, `all`, and `external_tools` presets first run a sequential
+The `analyze_grid_search`, `all`, and `external_tools` presets first run a sequential
 `patch_outputs` pre-job, which creates `refined-patched.cif` files from each
 `refined.cif` before the evaluation jobs start.
 
@@ -261,17 +261,23 @@ export GRID_SEARCH_INPUTS_DIR=/mnt/diffuse-shared/raw/sampleworks/initial_datase
 export PROTEIN_CONFIGS_CSV="$GRID_SEARCH_INPUTS_DIR/protein_analysis_config.csv"
 
 run_analysis --list
-run_analysis --dry-run rscc
-run_analysis grid_search --jobs rscc,lddt
+run_analysis --dry-run analyze_grid_search --jobs rscc
+run_analysis analyze_grid_search --jobs rscc,lddt
 run_analysis altloc_find
 run_analysis altloc_classify
 run_analysis all  # includes tortoize and phenix.clashscore jobs
 ```
 
 Use `--set` for one-off changes, for example
-`run_analysis rscc --set jobs.rscc.gpus=0`. If your input layout differs from
-the default `processed/{pdb_id}/{pdb_id}_single_001_density_input.cif`, override
-the patch pre-job with `--set defaults.PATCH_INPUT_PDB_PATTERN='{pdb_id}/{pdb_id}_original.cif'`.
+`run_analysis analyze_grid_search --jobs rscc --set jobs.rscc.gpus=0`. If your
+input layout differs from the default
+`processed/{pdb_id}/{pdb_id}_single_001_density_input.cif`, override the patch
+pre-job with `--set defaults.PATCH_INPUT_PDB_PATTERN='{pdb_id}/{pdb_id}_original.cif'`.
+When patched CIFs already exist, add `--skip-pre-jobs` to rerun analyses without
+repeating the patching step.
+The `altloc_find` and `altloc_classify` presets are independent of grid-search
+outputs; override `ALTLOC_ANALYSIS_DIR` and `ALTLOC_INPUTS_DIR` when their input
+or output roots differ from the defaults.
 
 
 ## Docker
diff --git a/analyses/all.toml b/analyses/all.toml
index 281b9008..b286aaa2 100644
--- a/analyses/all.toml
+++ b/analyses/all.toml
@@ -7,7 +7,8 @@ PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
 TARGET_FILENAME = "refined-patched.cif"
 N_JOBS = "16"
 PATCH_CIF_PATTERN = "refined.cif"
-PATCH_DEPTH = "4"
+GRID_SEARCH_DEPTH = "4"
+PATCH_DEPTH = "${GRID_SEARCH_DEPTH}"
 PATCH_INPUT_PDB_PATTERN = "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
 PATCH_RCSB_PATTERN = "${GRID_SEARCH_RESULTS_DIR}/([A-Za-z0-9]{4})"
 
@@ -18,6 +19,7 @@ protein-configs-csv = "${PROTEIN_CONFIGS_CSV}"
 target-filename = "${TARGET_FILENAME}"
 occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
 n-jobs = "${N_JOBS}"
+depth = "${GRID_SEARCH_DEPTH}"
 
 [[pre_jobs]]
 name = "patch_outputs"
diff --git a/analyses/altloc_classify.toml b/analyses/altloc_classify.toml
index cd7cf730..152bd33c 100644
--- a/analyses/altloc_classify.toml
+++ b/analyses/altloc_classify.toml
@@ -1,11 +1,11 @@
 description = "Classify altloc selections into side-chain, loop, and domain-shift categories."
 
 [defaults]
-GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
-GRID_SEARCH_INPUTS_DIR = "/data/inputs"
-ALTLOC_SELECTIONS_CSV = "${GRID_SEARCH_RESULTS_DIR}/analysis/altloc_selections.csv"
-ALTLOC_CLASSIFICATIONS_CSV = "${GRID_SEARCH_RESULTS_DIR}/analysis/altloc_region_classifications.csv"
-CIF_ROOT = "${GRID_SEARCH_INPUTS_DIR}"
+ALTLOC_ANALYSIS_DIR = "/data/results/altloc_analysis"
+ALTLOC_INPUTS_DIR = "/data/inputs"
+ALTLOC_SELECTIONS_CSV = "${ALTLOC_ANALYSIS_DIR}/altloc_selections.csv"
+ALTLOC_CLASSIFICATIONS_CSV = "${ALTLOC_ANALYSIS_DIR}/altloc_region_classifications.csv"
+CIF_ROOT = "${ALTLOC_INPUTS_DIR}"
 DOMAIN_SHIFT_MIN_SPAN = "50"
 LOOP_LDDT_THRESHOLD = "0.75"
 
diff --git a/analyses/altloc_find.toml b/analyses/altloc_find.toml
index e6d2718b..898e5301 100644
--- a/analyses/altloc_find.toml
+++ b/analyses/altloc_find.toml
@@ -1,10 +1,10 @@
 description = "Build an analysis protein-config CSV by finding altloc selections in input CIFs."
 
 [defaults]
-GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
-GRID_SEARCH_INPUTS_DIR = "/data/inputs"
-PROTEINS_CSV = "${GRID_SEARCH_INPUTS_DIR}/proteins.csv"
-ALTLOC_SELECTIONS_CSV = "${GRID_SEARCH_RESULTS_DIR}/analysis/altloc_selections.csv"
+ALTLOC_ANALYSIS_DIR = "/data/results/altloc_analysis"
+ALTLOC_INPUTS_DIR = "/data/inputs"
+PROTEINS_CSV = "${ALTLOC_INPUTS_DIR}/proteins.csv"
+ALTLOC_SELECTIONS_CSV = "${ALTLOC_ANALYSIS_DIR}/altloc_selections.csv"
 ALTLOC_MIN_SPAN = "5"
 ALTLOC_LABEL = "label_alt_id"
 
diff --git a/analyses/grid_search.toml b/analyses/analyze_grid_search.toml
similarity index 89%
rename from analyses/grid_search.toml
rename to analyses/analyze_grid_search.toml
index a9ac09f9..334779ae 100644
--- a/analyses/grid_search.toml
+++ b/analyses/analyze_grid_search.toml
@@ -1,4 +1,4 @@
-description = "Core grid-search evaluations: RSCC, LDDT clustering, and bond geometry."
+description = "Analyze grid-search outputs with RSCC, LDDT clustering, and bond geometry."
 
 [defaults]
 GRID_SEARCH_RESULTS_DIR = "/data/results/grid_search_results"
@@ -7,7 +7,8 @@ PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
 TARGET_FILENAME = "refined-patched.cif"
 N_JOBS = "16"
 PATCH_CIF_PATTERN = "refined.cif"
-PATCH_DEPTH = "4"
+GRID_SEARCH_DEPTH = "4"
+PATCH_DEPTH = "${GRID_SEARCH_DEPTH}"
 PATCH_INPUT_PDB_PATTERN = "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
 PATCH_RCSB_PATTERN = "${GRID_SEARCH_RESULTS_DIR}/([A-Za-z0-9]{4})"
 
@@ -18,6 +19,7 @@ protein-configs-csv = "${PROTEIN_CONFIGS_CSV}"
 target-filename = "${TARGET_FILENAME}"
 occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
 n-jobs = "${N_JOBS}"
+depth = "${GRID_SEARCH_DEPTH}"
 
 [[pre_jobs]]
 name = "patch_outputs"
diff --git a/analyses/external_tools.toml b/analyses/external_tools.toml
index bd1ed13f..b6678c43 100644
--- a/analyses/external_tools.toml
+++ b/analyses/external_tools.toml
@@ -7,7 +7,8 @@ PROTEIN_CONFIGS_CSV = "${GRID_SEARCH_INPUTS_DIR}/protein_analysis_config.csv"
 TARGET_FILENAME = "refined-patched.cif"
 N_JOBS = "16"
 PATCH_CIF_PATTERN = "refined.cif"
-PATCH_DEPTH = "4"
+GRID_SEARCH_DEPTH = "4"
+PATCH_DEPTH = "${GRID_SEARCH_DEPTH}"
 PATCH_INPUT_PDB_PATTERN = "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
 PATCH_RCSB_PATTERN = "${GRID_SEARCH_RESULTS_DIR}/([A-Za-z0-9]{4})"
 
@@ -18,6 +19,7 @@ protein-configs-csv = "${PROTEIN_CONFIGS_CSV}"
 target-filename = "${TARGET_FILENAME}"
 occupancies = [0.0, 0.25, 0.5, 0.75, 1.0]
 n-jobs = "${N_JOBS}"
+depth = "${GRID_SEARCH_DEPTH}"
 
 [[pre_jobs]]
 name = "patch_outputs"
diff --git a/run_analysis b/run_analysis
index 54a55539..1e8b4c71 100755
--- a/run_analysis
+++ b/run_analysis
@@ -178,13 +178,13 @@ if [[
     -z "$explicit_jobs" &&
     -z "$env_preset"
 ]]; then
-    target="grid_search"
+    target="analyze_grid_search"
 fi
 
 label_source="$default_target"
 if [[ -n "$explicit_preset" ]]; then
     label_source="$explicit_preset"
-elif [[ -n "$explicit_jobs" && ( -z "$target" || "$target" == "all" || "$target" == "grid_search" ) ]]; then
+elif [[ -n "$explicit_jobs" && ( -z "$target" || "$target" == "all" || "$target" == "grid_search" || "$target" == "analyze_grid_search" ) ]]; then
     label_source="$explicit_jobs"
 elif [[ -n "$target" ]]; then
     label_source="$target"
@@ -209,6 +209,8 @@ else
 fi
 export RESULTS_DIR="${RESULTS_DIR:-$GRID_SEARCH_RESULTS_DIR}"
 export GRID_SEARCH_INPUTS_DIR="${GRID_SEARCH_INPUTS_DIR:-${DATA_DIR:-${SAMPLEWORKS_DATA_DIR:-$default_grid_inputs_dir}}}"
+export ALTLOC_ANALYSIS_DIR="${ALTLOC_ANALYSIS_DIR:-${SAMPLEWORKS_ALTLOC_ANALYSIS_DIR:-$default_grid_results_dir}}"
+export ALTLOC_INPUTS_DIR="${ALTLOC_INPUTS_DIR:-${SAMPLEWORKS_ALTLOC_INPUTS_DIR:-$GRID_SEARCH_INPUTS_DIR}}"
 export PROTEIN_CONFIGS_CSV="${PROTEIN_CONFIGS_CSV:-${SAMPLEWORKS_PROTEIN_CONFIGS_CSV:-$GRID_SEARCH_INPUTS_DIR/protein_analysis_config.csv}}"
 export TARGET_FILENAME="${TARGET_FILENAME:-${SAMPLEWORKS_TARGET_FILENAME:-refined-patched.cif}}"
 export N_JOBS="${N_JOBS:-${SAMPLEWORKS_ANALYSIS_N_JOBS:-16}}"
diff --git a/scripts/eval/EVALUATION.md b/scripts/eval/EVALUATION.md
index c64228e7..fc59a7c3 100644
--- a/scripts/eval/EVALUATION.md
+++ b/scripts/eval/EVALUATION.md
@@ -26,7 +26,7 @@ the script `scripts/patch_output_cif_files.py`. This will use the original PDB i
 reconstruct proper output CIF files that are numbered correctly and have all necessary metadata to
 reconstruct the protein structure correctly.
 
-The `run_analysis` presets automate this step for the `grid_search`, `all`, and `external_tools`
+The `run_analysis` presets automate this step for the `analyze_grid_search`, `all`, and `external_tools`
 presets: a sequential `patch_outputs` pre-job runs before evaluation jobs and writes
 `refined-patched.cif` files. Override `PATCH_INPUT_PDB_PATTERN`, `PATCH_RCSB_PATTERN`,
 `PATCH_CIF_PATTERN`, or `PATCH_DEPTH` if your input or output layout differs.
@@ -70,15 +70,16 @@ export GRID_SEARCH_INPUTS_DIR=/home/ubuntu/grid_search_inputs
 export PROTEIN_CONFIGS_CSV=/home/ubuntu/protein_analysis_config.csv
 
 run_analysis --list
-run_analysis grid_search --jobs rscc,lddt,bond_geometry
+run_analysis analyze_grid_search --jobs rscc,lddt,bond_geometry
 run_analysis altloc_find
 run_analysis altloc_classify
-run_analysis rscc --set defaults.PATCH_INPUT_PDB_PATTERN='{pdb_id}/{pdb_id}_original.cif'
+run_analysis analyze_grid_search --jobs rscc --set defaults.PATCH_INPUT_PDB_PATTERN='{pdb_id}/{pdb_id}_original.cif'
 ```
 
-The `grid_search`, `all`, and `external_tools` presets run the CIF patching pre-step before these
+The `analyze_grid_search`, `all`, and `external_tools` presets run the CIF patching pre-step before these
 evaluation scripts. If you run the scripts directly, run `scripts/patch_output_cif_files.py` first
-or point `--target-filename` at files that already contain the required metadata.
+or point `--target-filename` at files that already contain the required metadata. If patched CIFs
+already exist, add `--skip-pre-jobs` to rerun the analyses without repeating the patching step.
 
 For direct script invocation, the equivalent command shape is:
 
@@ -87,6 +88,7 @@ pixi run -e analysis python scripts/eval/<script> \
 --grid-search-results-path /home/ubuntu/grid_search_results \
 --grid-search-inputs-path /home/ubuntu/grid_search_inputs \
 --target-filename 'refined-patched.cif' \
+--depth 4 \
 --protein-configs-csv /home/ubuntu/protein_analysis_config.csv \
 --occupancies 0.0 0.25 0.5 0.75 1.0 \
 --n-jobs 16
@@ -97,6 +99,8 @@ what you used in the grid search.
 The `--n-jobs` argument is the number of parallel jobs to run; it is not used by all scripts yet but
 speeds some up considerably, especially for the tortoize and clashscore scripts.
 
+The `--depth` argument is the maximum directory depth to recurse into when looking for target CIF files.
+
 The `--protein-configs-csv` argument is a CSV file describes what parts of each protein to evaluate.
 Examples can be found in `sampleworks/data/`.
 The file has the following columns:
diff --git a/src/sampleworks/eval/grid_search_eval_utils.py b/src/sampleworks/eval/grid_search_eval_utils.py
index 1bd32fd8..9c917981 100644
--- a/src/sampleworks/eval/grid_search_eval_utils.py
+++ b/src/sampleworks/eval/grid_search_eval_utils.py
@@ -266,6 +266,12 @@ def parse_eval_args(description: str | None = None):
         default="refined.cif",
         help="Target filename for the CIF files to process, defaults to 'refined.cif'",
     )
+    parser.add_argument(
+        "--depth",
+        type=int,
+        default=4,
+        help="Maximum directory depth to recurse when scanning for target CIF files.",
+    )
     parser.add_argument(
         "--n-jobs",
         type=int,
@@ -288,7 +294,11 @@ def setup_evaluation_parameters(
     logger.info(f"Proteins configured: {list(protein_configs.keys())}")
 
     # Scan for experiments (look for refined.cif files)
-    all_trials = scan_grid_search_results(grid_search_dir, target_filename=args.target_filename)
+    all_trials = scan_grid_search_results(
+        grid_search_dir,
+        target_depth=args.depth,
+        target_filename=args.target_filename,
+    )
     logger.info(f"Found {len(all_trials)} experiments with refined.cif files")
 
     if all_trials:
diff --git a/src/sampleworks/runs/analysis_cli.py b/src/sampleworks/runs/analysis_cli.py
index 4a9f37af..9844d71a 100644
--- a/src/sampleworks/runs/analysis_cli.py
+++ b/src/sampleworks/runs/analysis_cli.py
@@ -4,28 +4,28 @@
 
 import sys
 
-from .cli import CliConfig, run_cli
+from sampleworks.runs.cli import CliConfig, run_cli
 
 
 ANALYSIS_CLI_CONFIG = CliConfig(
     prog="sampleworks-analysis",
     description=(
         "Run Sampleworks analysis/evaluation presets. With no target, runs the "
-        "grid_search preset. A target like 'all' runs that preset; comma-separated "
-        "targets like 'rscc,lddt' select jobs from grid_search."
+        "analyze_grid_search preset. A target like 'all' runs that preset; "
+        "comma-separated targets like 'rscc,lddt' select jobs from analyze_grid_search."
     ),
     target_help=(
-        "Preset name from analyses/ (grid_search, all, external_tools, etc.) or "
-        "comma-separated job shortcut from grid_search."
+        "Preset name from analyses/ (analyze_grid_search, all, external_tools, etc.) or "
+        "comma-separated job shortcut from analyze_grid_search."
     ),
-    preset_help="Preset name from analyses/ or path to a .toml file. Default: grid_search.",
+    preset_help="Preset name from analyses/ or path to a .toml file. Default: analyze_grid_search.",
     list_help="List analyses/*.toml presets and exit",
     preset_dir_name="analyses",
     preset_dir_env_var="SAMPLEWORKS_ANALYSES_DIR",
-    default_preset="grid_search",
-    default_aliases=frozenset({"grid_search"}),
-    results_default_keys=("GRID_SEARCH_RESULTS_DIR", "RESULTS_DIR"),
-    results_env_vars=("GRID_SEARCH_RESULTS_DIR", "RESULTS_DIR"),
+    default_preset="analyze_grid_search",
+    default_aliases=frozenset({"analyze_grid_search", "grid_search"}),
+    results_default_keys=("GRID_SEARCH_RESULTS_DIR", "ALTLOC_ANALYSIS_DIR", "RESULTS_DIR"),
+    results_env_vars=("GRID_SEARCH_RESULTS_DIR", "ALTLOC_ANALYSIS_DIR", "RESULTS_DIR"),
     results_fallback="./grid_search_results",
 )
 
diff --git a/src/sampleworks/runs/cli.py b/src/sampleworks/runs/cli.py
index c6858dbe..d9ee7cc7 100644
--- a/src/sampleworks/runs/cli.py
+++ b/src/sampleworks/runs/cli.py
@@ -8,8 +8,8 @@
 from dataclasses import dataclass
 from pathlib import Path
 
-from . import loader, runner
-from .schema import Job, Preset
+from sampleworks.runs import loader, runner
+from sampleworks.runs.schema import Job, Preset
 
 
 DEFAULT_PRESET = "full_8gpu"
@@ -152,7 +152,12 @@ def run_cli(argv: list[str] | None = None, *, config: CliConfig) -> int:
 
     results_dir = Path(args.results_dir or _default_results_dir(preset, config=config))
     try:
-        return runner.run(preset, results_dir=results_dir, dry_run=args.dry_run)
+        return runner.run(
+            preset,
+            results_dir=results_dir,
+            dry_run=args.dry_run,
+            skip_pre_jobs=args.skip_pre_jobs,
+        )
     except RuntimeError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
@@ -181,6 +186,11 @@ def _build_parser(config: CliConfig) -> argparse.ArgumentParser:
         action="store_true",
         help="Print the resolved job commands instead of executing them",
     )
+    parser.add_argument(
+        "--skip-pre-jobs",
+        action="store_true",
+        help="Skip sequential pre-jobs when their outputs already exist.",
+    )
     parser.add_argument(
         "--jobs",
         default="",
@@ -245,17 +255,18 @@ def _resolve_target(
     if target is None or target in config.default_aliases:
         return config.default_preset, jobs
 
-    if jobs:
-        parser.error("pass jobs either as the positional target or with --jobs, not both")
-
     if target.endswith(".toml") or "/" in target:
         parser.error("pass custom preset paths with --preset path/to/preset.toml")
 
-    if "," not in target and target in loader.list_presets(
+    preset_names = loader.list_presets(
         preset_dir_name=config.preset_dir_name,
         preset_dir_env_var=config.preset_dir_env_var,
-    ):
-        return target, ""
+    )
+    if "," not in target and target in preset_names:
+        return target, jobs
+
+    if jobs:
+        parser.error("pass jobs either as the positional target or with --jobs, not both")
 
     return config.default_preset, target
 
diff --git a/src/sampleworks/runs/runner.py b/src/sampleworks/runs/runner.py
index 846e5332..7829bc4f 100644
--- a/src/sampleworks/runs/runner.py
+++ b/src/sampleworks/runs/runner.py
@@ -598,8 +598,7 @@ def _source_root_candidates() -> list[Path]:
     """
     candidates: list[Path] = []
     for env_var in ("SAMPLEWORKS_SOURCE_DIR", "SAMPLEWORKS_SCRIPT_ROOT"):
-        override = os.environ.get(env_var)
-        if override:
+        if override := os.environ.get(env_var):
             candidates.append(Path(override))
 
     candidates.append(Path("/home/dev/workspace"))
@@ -617,7 +616,13 @@ def _source_root_candidates() -> list[Path]:
     return unique
 
 
-def run(preset: Preset, *, results_dir: Path, dry_run: bool = False) -> int:
+def run(
+    preset: Preset,
+    *,
+    results_dir: Path,
+    dry_run: bool = False,
+    skip_pre_jobs: bool = False,
+) -> int:
     """Launch every job in parallel and wait for completion.
 
     Stdout+stderr from each job is teed to a per-job log file under
@@ -632,6 +637,9 @@ def run(preset: Preset, *, results_dir: Path, dry_run: bool = False) -> int:
         Root directory for outputs and logs. Created if missing.
     dry_run : bool, optional
         If True, print the resolved commands instead of launching anything.
+    skip_pre_jobs : bool, optional
+        If True, omit sequential pre-jobs. Use this when preparation outputs,
+        such as patched CIFs, have already been generated.
 
     Returns
     -------
@@ -640,7 +648,9 @@ def run(preset: Preset, *, results_dir: Path, dry_run: bool = False) -> int:
     """
     results_dir = results_dir.resolve()
     results_dir.mkdir(parents=True, exist_ok=True)
-    pre_invocations = build_pre_invocations(preset, results_dir=results_dir)
+    pre_invocations = (
+        [] if skip_pre_jobs else build_pre_invocations(preset, results_dir=results_dir)
+    )
     invocations = build_invocations(preset, results_dir=results_dir)
     _validate_gpu_assignments(pre_invocations)
     _validate_gpu_assignments(invocations)
diff --git a/src/sampleworks/runs/schema.py b/src/sampleworks/runs/schema.py
index 2e2c3c31..771c7780 100644
--- a/src/sampleworks/runs/schema.py
+++ b/src/sampleworks/runs/schema.py
@@ -93,7 +93,7 @@ def __post_init__(self) -> None:
             raise ValueError(f"Job {self.name!r}: gpu_count must be positive")
         if not self.output_subdir:
             raise ValueError(f"Job {self.name!r}: output_subdir must be non-empty")
-        if self.output_arg.startswith("--"):
+        if self.output_arg.startswith("-"):
             raise ValueError(
                 f"Job {self.name!r}: output_arg must omit leading dashes, got {self.output_arg!r}"
             )
diff --git a/tests/runs/test_cli.py b/tests/runs/test_cli.py
index 7af38081..a20f141c 100644
--- a/tests/runs/test_cli.py
+++ b/tests/runs/test_cli.py
@@ -115,6 +115,42 @@ def test_jobs_filters_explicit_preset(
     assert "protenix" not in out
 
 
+def test_jobs_filters_positional_preset(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """``--jobs`` filters a preset selected by positional target.
+
+    Returns
+    -------
+    None
+    """
+    monkeypatch.setenv("HOME", "/home/test")
+    exit_code = cli.main(["boltz", "--jobs", "boltz2_xrd", "--show"])
+    assert exit_code == 0
+    out = capsys.readouterr().out
+    assert "name: boltz:boltz2_xrd" in out
+    assert "name: boltz2_xrd" in out
+    assert "name: boltz2_md" not in out
+
+
+def test_skip_pre_jobs_flag_is_passed_to_runner(monkeypatch: pytest.MonkeyPatch) -> None:
+    """``--skip-pre-jobs`` reaches the runner.
+
+    Returns
+    -------
+    None
+    """
+    seen: dict[str, bool] = {}
+
+    def fake_run(*args: object, **kwargs: object) -> int:
+        seen["skip_pre_jobs"] = bool(kwargs["skip_pre_jobs"])
+        return 0
+
+    monkeypatch.setattr(runner, "run", fake_run)
+    assert cli.main(["--preset", "full_8gpu", "--skip-pre-jobs"]) == 0
+    assert seen == {"skip_pre_jobs": True}
+
+
 def test_job_shortcut_with_unknown_job_errors(monkeypatch: pytest.MonkeyPatch) -> None:
     """Unknown positional job shortcuts fail with a clear selector error."""
     monkeypatch.setenv("HOME", "/home/test")
diff --git a/tests/runs/test_runner.py b/tests/runs/test_runner.py
index 63fa0e0c..bec96b9d 100644
--- a/tests/runs/test_runner.py
+++ b/tests/runs/test_runner.py
@@ -7,6 +7,7 @@
 
 import pytest
 from sampleworks.runs import analysis_cli, loader, runner
+from sampleworks.runs.schema import Job
 
 
 def test_argv_for_rf3_partial_matches_bash(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -269,13 +270,18 @@ def test_dry_run_does_not_create_directories(
 
 
 def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Analysis TOML presets patch CIFs before running eval scripts."""
+    """Build analysis eval and preparation commands.
+
+    Returns
+    -------
+    None
+    """
     repo_root = Path(__file__).resolve().parents[2]
     monkeypatch.setenv("HOME", "/home/test")
     monkeypatch.setenv("SAMPLEWORKS_SOURCE_DIR", str(repo_root))
     monkeypatch.setattr(runner, "_detect_available_gpus", lambda: ["0"])
     preset = loader.load_preset(
-        "grid_search",
+        "analyze_grid_search",
         overrides=[
             "defaults.GRID_SEARCH_RESULTS_DIR=/grid/results",
             "defaults.GRID_SEARCH_INPUTS_DIR=/grid/inputs",
@@ -309,6 +315,7 @@ def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.Monk
     assert patch_args["--input-pdb-pattern"] == (
         "processed/{pdb_id}/{pdb_id}_single_001_density_input.cif"
     )
+    assert patch_args["--depth"] == "4"
     assert "--target-filename" not in patch_args
     assert "--protein-configs-csv" not in patch_args
 
@@ -326,6 +333,7 @@ def test_analysis_preset_builds_eval_script_invocations(monkeypatch: pytest.Monk
     assert rscc.output_dir == Path("/analysis-logs/analysis/rscc")
     assert rscc.argv[rscc.argv.index("--grid-search-results-path") + 1] == "/grid/results"
     assert rscc.argv[rscc.argv.index("--grid-search-inputs-path") + 1] == "/grid/inputs"
+    assert rscc.argv[rscc.argv.index("--depth") + 1] == "4"
     occupancy_index = rscc.argv.index("--occupancies")
     assert rscc.argv[occupancy_index + 1 : occupancy_index + 6] == [
         "0.0",
@@ -364,22 +372,32 @@ def test_pre_jobs_run_before_main_jobs(tmp_path: Path, monkeypatch: pytest.Monke
 
 
 def test_analysis_cli_lists_analysis_presets(capsys: pytest.CaptureFixture[str]) -> None:
-    """The analysis entrypoint lists analyses/*.toml instead of experiments/*.toml."""
+    """List bundled analysis presets.
+
+    Returns
+    -------
+    None
+    """
     assert analysis_cli.main(["--list"]) == 0
     listed = set(capsys.readouterr().out.splitlines())
     assert {
         "all",
+        "analyze_grid_search",
         "altloc_classify",
         "altloc_find",
         "external_tools",
-        "grid_search",
     }.issubset(listed)
 
 
 def test_gpu_validation_ignores_cpu_jobs_but_checks_gpu_duplicates(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    """A gpus='none' analysis job must not disable validation for real GPU jobs."""
+    """Validate CPU-only jobs without masking GPU conflicts.
+
+    Returns
+    -------
+    None
+    """
     monkeypatch.setattr(runner, "_detect_available_gpus", lambda: ["0", "1"])
     custom = tmp_path / "custom.toml"
     custom.write_text(
@@ -398,6 +416,23 @@ def test_gpu_validation_ignores_cpu_jobs_but_checks_gpu_duplicates(
         runner._validate_gpu_assignments(invocations)
 
 
+def test_output_arg_rejects_any_leading_dash() -> None:
+    """Reject output_arg values that already look like CLI flags.
+
+    Returns
+    -------
+    None
+    """
+    with pytest.raises(ValueError, match="output_arg must omit leading dashes"):
+        Job(
+            name="bad",
+            env="analysis",
+            gpus="none",
+            output_subdir="bad",
+            output_arg="-output-dir",
+        )
+
+
 def _argv_to_dict(tail: list[str]) -> dict[str, object]:
     """Turn ``[--a, 1, --b, --c, 2]`` into ``{'--a': '1', '--b': True, '--c': '2'}``."""
     out: dict[str, object] = {}