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:

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