Update apptainer/README.md

apptainer/README.md

@@ -0,0 +1,109 @@
+# CryoZeta Run Scripts
+
+This repository includes local wrapper scripts for running CryoZeta through
+Apptainer with externally downloaded model weights.
+
+Use:
+
+- `run_cryozeta.sh` for standard CryoZeta inference
+- `run_cryozeta_large.sh` for large-complex cycle inference
+
+
+## 1. Download weights once
+
+Download the Hugging Face model files into a local assets directory:
+
+```bash
+huggingface-cli download KiharaLab/CryoZeta --repo-type model \
+    --local-dir /path/to/assets
+```
+
+That directory should contain the model files used by the wrappers, including:
+
+- `cryozeta-detection-v0.0.1.safetensors`
+- `cryozeta-v0.0.1.safetensors`
+- `cryozeta-interpolate-v0.0.1.safetensors`
+
+
+## 2. Normal inference
+
+Use `run_cryozeta.sh` for the standard pipeline:
+
+- Stage 1: atom detection
+- Stage 2: structure prediction
+- Stage 3: result combination
+
+Basic usage:
+
+```bash
+./run_cryozeta.sh --gpu ID <input_json> <output_dir> <assets_dir>
+```
+
+Example:
+
+```bash
+./run_cryozeta.sh \
+  --gpu 0 \
+  server/3a7c2af60301441c607c5dfc565add50/input.json \
+  server/tmp \
+  /path/to/assets
+```
+
+Notes:
+
+- Edit the `SIF` path near the top of `run_cryozeta.sh` if needed, or pass
+  `--sif PATH`.
+- Pass the downloaded assets directory as the third positional argument.
+- Run the script from the repo root so bind mounts and relative paths resolve
+  cleanly.
+
+
+## 3. Large-complex inference
+
+Use `run_cryozeta_large.sh` for large-complex cycle prediction:
+
+- detection
+- cycle prediction
+- combine stages
+
+Basic usage:
+
+```bash
+./run_cryozeta_large.sh --sif /path/to/CryoZeta.sif --gpu ID \
+  <input_json> <output_dir> <assets_dir>
+```
+
+Example:
+
+```bash
+./run_cryozeta_large.sh \
+  --sif /path/to/CryoZeta.sif \
+  --gpu 0 \
+  server/8zui/input.json \
+  server/tmp \
+  /path/to/assets
+```
+
+Optional flags:
+
+- `--example SEL` select one entry by index or name from a JSON list
+- `--registration auto|teaser|svd|vesper`
+- `--threshold X`
+- `--n-sample N`
+- `--n-step N`
+- `--n-cycle N`
+- `--skip-detection`
+- `--skip-combine`
+
+Path handling:
+
+- `run_cryozeta_large.sh` supports both JSON-local relative paths such as
+  `60484.map` and repo-root-relative paths such as `server/8zui/60484.map`.
+
+
+## 4. Recommended workflow
+
+1. Download weights once with `huggingface-cli`.
+2. Use `run_cryozeta.sh` for normal inference jobs.
+3. Use `run_cryozeta_large.sh` for large-complex jobs.
+