apptainer/README.md

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:

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:

./run_cryozeta.sh --gpu ID <input_json> <output_dir> <assets_dir>

Example:

./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:

./run_cryozeta_large.sh --sif /path/to/CryoZeta.sif --gpu ID \
  <input_json> <output_dir> <assets_dir>

Example:

./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.