protcross 0.2.2__tar.gz → 0.2.4__tar.gz

{protcross-0.2.2 → protcross-0.2.4}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: protcross
-Version: 0.2.2
+Version: 0.2.4
 Summary: Domain-adaptive protein point-cloud binding-site prediction.
 Author: Shuyu Zhong, Yuying Jiang
 License-Expression: MIT
 Project-URL: Publication, https://doi.org/10.1021/acs.jcim.5c03224
-Project-URL: Documentation, https://github.com/GeraltZeroZhong/ProtCross/blob/v0.2.2/README.md
+Project-URL: Documentation, https://github.com/GeraltZeroZhong/ProtCross/blob/v0.2.4/README.md
 Project-URL: Repository, https://github.com/GeraltZeroZhong/ProtCross
 Project-URL: Issues, https://github.com/GeraltZeroZhong/ProtCross/issues
 Classifier: Development Status :: 3 - Alpha
@@ -52,7 +52,7 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/protcross?label=PyPI&color=0f766e)](https://pypi.org/project/protcross/)
 [![Windows Desktop](https://img.shields.io/badge/Windows-10%2F11%20x64-0078d4?logo=windows11&logoColor=white)](https://github.com/GeraltZeroZhong/ProtCross/releases)
 [![macOS Desktop](https://img.shields.io/badge/macOS-12%2B%20Apple%20Silicon-111827?logo=apple&logoColor=white)](https://github.com/GeraltZeroZhong/ProtCross/releases)
-[![Version](https://img.shields.io/badge/version-0.2.2-2563eb)](#version-history)
+[![Version](https://img.shields.io/badge/version-0.2.4-2563eb)](#version-history)
 [![Python](https://img.shields.io/badge/python-3.10-3776ab)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
 [![Paper](https://img.shields.io/badge/DOI-10.1021%2Facs.jcim.5c03224-ca8a04)](https://doi.org/10.1021/acs.jcim.5c03224)
@@ -82,11 +82,17 @@ poses and virtual-screening enrichment
 
 ## Quick start
 
-ProtCross 0.2.2 uses Python 3.10:
+Choose the interface that matches your task:
 
-Review the [ESM-C model terms](https://www.evolutionaryscale.ai/policies/cambrian-non-commercial-license-agreement)
-before asset setup. A fresh setup downloads approximately 2.14 GiB of model
-weights; subsequent predictions reuse the local asset cache.
+| Goal | Start here |
+| --- | --- |
+| Run a local prediction from a terminal | Install the CLI below |
+| Call ProtCross from a Python workflow | Install the CLI, then open [Python API](#python-api) |
+| Use a guided interface and 3D viewer | Download [ProtCross Desktop](#desktop-application) |
+
+ProtCross 0.2.4 requires Python 3.10. This first run installs the prediction
+dependencies, prepares the managed model assets, checks a structure, and writes
+one result package:
 
 ```bash
 python3.10 -m venv .venv
@@ -94,11 +100,15 @@ source .venv/bin/activate
 python -m pip install --upgrade pip
 python -m pip install "protcross[predict]"
 
-protcross setup-assets --accept-esm-license
+protcross setup-assets
 protcross inspect input.pdb
 protcross predict input.pdb --out-dir protcross-results
 ```
 
+ESM-C weights use the [MIT license](https://huggingface.co/biohub/esmc-600m-2024-12).
+Initial asset setup downloads approximately
+2.14 GiB; later predictions reuse the verified local cache.
+
 The prediction command creates:
 
 ```text
@@ -109,10 +119,10 @@ protcross-results/
 └── input.protcross.summary.json
 ```
 
-Windows x64 and macOS Apple Silicon Desktop builds are available through
-[GitHub Releases](https://github.com/GeraltZeroZhong/ProtCross/releases). The
-Desktop workflow installs its local runtime, manages assets, inspects inputs,
-runs single or batch predictions, and displays results with Mol*.
+For a graphical workflow, install the Windows x64 or macOS Apple Silicon build
+from [GitHub Releases](https://github.com/GeraltZeroZhong/ProtCross/releases),
+then follow the two readiness steps in **Setup**. Desktop manages its own
+runtime and assets and opens completed predictions in Mol*.
 
 ## Contents
 
@@ -121,11 +131,11 @@ runs single or batch predictions, and displays results with Mol*.
 - [Installation](#installation)
 - [Run predictions](#run-predictions)
 - [Output package](#output-package)
-- [Model and inference pipeline](#model-and-inference-pipeline)
 - [Batch inference](#batch-inference)
 - [Python API](#python-api)
 - [Assets](#assets)
 - [Desktop application](#desktop-application)
+- [Model and inference pipeline](#model-and-inference-pipeline)
 - [Training and development](#training-and-development)
 - [Troubleshooting](#troubleshooting)
 - [Version history](#version-history)
@@ -134,14 +144,13 @@ runs single or batch predictions, and displays results with Mol*.
 
 ## Highlights
 
-- PDB, mmCIF, and AlphaFold coordinate input
-- Per-chain ESM-C 600M embeddings with paired 128-dimensional PCA features
-- PointNet++ residue segmentation over centered Cα point clouds
-- PDB/mmCIF annotation, extended TSV, cluster JSON, and provenance JSON
-- CPU, CUDA, and Apple MPS device selection
-- Bounded ESM-C and PointNet++ microbatching for high-throughput inference
-- Deterministic pure-PyTorch FPS, radius, and KNN geometry operators
-- Local Desktop, unified CLI, and reusable Python API
+- Inspect PDB, mmCIF, and AlphaFold coordinate files before model loading
+- Score residues and rank spatial binding-site clusters with centroids
+- Export annotated coordinates, a full residue table, cluster JSON, and run provenance
+- Run on CPU, CUDA, or Apple MPS through the CLI, Python API, or local Desktop
+- Reuse verified assets and reduced ESM/PCA features across repeated work
+- Process structure collections with bounded ESM-C and PointNet++ microbatches
+- Review persistent Desktop batches and regroup completed results interactively
 
 ## Installation
 
@@ -155,8 +164,8 @@ runs single or batch predictions, and displays results with Mol*.
 | Desktop development | Node.js 20, Rust 1.88, Tauri 2 system packages |
 
 ProtCross declares `python >=3.10,<3.11`. Create a dedicated Python 3.10
-environment for installation. The platform commands below install the PyPI
-distribution.
+environment, choose the platform command below, and confirm the installed
+version before preparing assets.
 
 ### Linux CPU
 
@@ -216,13 +225,9 @@ py -3.10 -m venv .venv
 Activate the environment to use the shorter commands shown throughout this
 README.
 
-### Development environment
-
-```bash
-conda env create -f environment.yml
-conda activate protcross
-python -m pip install -e ".[dev,esm]"
-```
+After installation, run `protcross setup-assets` once, or
+open [Assets](#assets) to select another cache location or an existing ESM-C
+file.
 
 ## Run predictions
 
@@ -230,7 +235,7 @@ python -m pip install -e ".[dev,esm]"
 
 `protcross inspect` parses coordinate metadata without loading model assets.
 The repository includes [`examples/6fhu.pdb`](examples/6fhu.pdb) for a first
-run.
+check, so input preparation can be tested before the 2.14 GiB ESM-C download.
 
 ```bash
 protcross inspect input.cif
@@ -238,9 +243,10 @@ protcross inspect input.cif --chain A
 protcross inspect input.cif --json
 ```
 
-The report includes coordinate models, chains, scorable residues, missing Cα
-atoms, modified residues, alternate conformers, coordinate breaks, numbering
-gaps, and ESM-C context length.
+Use the report to choose a chain, identify missing Cα atoms or modified
+residues, and check whether a chain exceeds the 1,022-residue ESM-C context.
+`--json` sends successful and failed inspections to stdout as machine-readable
+JSON and uses the process exit code to signal success or failure.
 
 ```text
 Input: examples/6fhu.pdb
@@ -255,11 +261,14 @@ Ready for prediction.
 ### Predict one structure
 
 ```bash
-protcross predict input.pdb \
-  --out-dir results \
-  --device cpu \
-  --threshold 0.5 \
-  --pocket-cluster-cutoff 8.0
+protcross predict input.pdb --out-dir results
+```
+
+Select one chain or an available accelerator when the task requires it:
+
+```bash
+protcross predict input.cif --chain A --out-dir results
+protcross predict input.pdb --device auto --out-dir results
 ```
 
 Common options:
@@ -268,15 +277,19 @@ Common options:
 | --- | ---: | --- |
 | `--chain ID` | all chains | Select one author chain ID |
 | `--device` | `cpu` | Select `cpu`, `cuda`, `cuda:N`, `mps`, or `auto` |
-| `--threshold` | `0.5` | Set the strict residue selection threshold |
+| `--threshold` | `0.5` | Select residues with `score > threshold` |
 | `--pocket-cluster-cutoff` | `8.0` | Set the Cα graph cutoff in Å |
 | `--max-len` | `1022` | Set the per-chain ESM-C residue limit |
-| `--allow-truncation` | disabled | Keep the leading `max_len` residues of each long chain |
+| `--allow-truncation` | disabled | Score the leading `max_len` residues of each long chain |
 | `--embedding-cache-dir` | unset | Cache reduced ESM/PCA residue features |
 | `--overwrite` | disabled | Replace an existing result package |
 | `--offline` | disabled | Restrict asset resolution to local files |
 
-Use explicit paths when integrating ProtCross into a workflow:
+The CLI writes four result files unless `--summary-only` is selected. Progress
+messages go to stderr; the terminal summary goes to stdout. Use `--quiet` when
+another process only needs the files and exit code.
+
+Set explicit output paths when a workflow owns the file layout:
 
 ```bash
 protcross predict input.cif \
@@ -328,12 +341,12 @@ protcross COMMAND --help
 
 ### Files
 
-| File | Contents |
-| --- | --- |
-| `input.protcross.pdb` or `.cif` | Input structure with residue scores in B-factor fields |
-| `input.protcross.scores.tsv` | Residue identifiers, scores, calls, coordinates, cluster IDs, and ranks |
-| `input.protcross.pockets.json` | Thresholded residue clusters and spatial statistics |
-| `input.protcross.summary.json` | Parameters, assets, runtime, hashes, warnings, and top-ranked results |
+| Task | File to use | Contents |
+| --- | --- | --- |
+| Color or share the scored structure | `input.protcross.pdb` or `.cif` | Input coordinates with residue scores in B-factor fields |
+| Rank and filter every scored residue | `input.protcross.scores.tsv` | Identifiers, scores, calls, coordinates, cluster IDs, and ranks |
+| Use predicted sites in a script | `input.protcross.pockets.json` | Thresholded residue clusters, members, centroids, and spatial statistics |
+| Audit or reproduce a run | `input.protcross.summary.json` | Parameters, asset and input hashes, runtime, warnings, and top results |
 
 PDB annotation preserves record order and updates B-factor columns on
 `ATOM`/`HETATM` records. mmCIF annotation retains coordinate categories and
@@ -354,13 +367,15 @@ coordinate models retain their original values.
 | Cluster order | Descending count/mean/maximum, then ascending canonical index |
 | Cluster center | Score-weighted Cα centroid |
 
-`model_score` is the canonical TSV field. `probability` remains available as a
-schema compatibility alias. Higher values indicate stronger support from the
-model's binding-site class; residue ranks preserve the continuous ordering.
-The threshold creates binary calls and cluster membership. Empty selections
-produce zero clusters and null aggregate/top-cluster entries.
-Selected chains share one geometry graph, so connected components can span a
-chain interface.
+Start analysis with `model_score` and `rank` in the TSV. Higher scores indicate
+stronger model support for the binding-site class. Scores are continuous model
+outputs and are not independently calibrated probabilities. `probability` is a
+schema compatibility alias for `model_score`.
+
+The threshold controls binary calls and cluster membership; it does not change
+the underlying scores. Empty selections produce zero clusters and null
+aggregate/top-cluster entries. Selected chains share one geometry graph, so a
+cluster can span a chain interface.
 
 ### Schemas
 
@@ -372,89 +387,49 @@ The JSON package records the application version, scoring procedure, selected
 asset bundle, asset hashes, input SHA256, threshold, clustering parameters,
 device, precision, and effective microbatch size.
 
-## Model and inference pipeline
-
-```mermaid
-flowchart LR
-    accTitle: ProtCross inference pipeline
-    accDescr: Coordinate files are parsed into per-chain sequences and a shared C-alpha graph, embedded with ESM-C and PCA, scored by PointNet++, and serialized as annotated coordinates, scores TSV, pockets JSON, and summary JSON.
-
-    coordinates["PDB or mmCIF"] --> parser["Structure parser"]
-    parser --> sequence["Per-chain sequence"]
-    parser --> geometry["Centered Cα graph"]
-    sequence --> esmc["ESM-C 600M"]
-    esmc --> pca["PCA 128"]
-    pca --> pointnet["PointNet++"]
-    geometry --> pointnet
-    pointnet --> scores["Residue scores"]
-    scores --> clusters["Threshold and cluster"]
-    clusters --> outputs["Four-file result package"]
-```
-
-### Components
-
-| Component | Configuration |
-| --- | --- |
-| ESM-C | 600M, hidden size 1,152, 36 layers, 18 attention heads |
-| PCA | Paired reducer, 128 output dimensions |
-| Set abstraction 1 | Sampling ratio `0.5`, radius `10 Å`, 64 neighbors |
-| Set abstraction 2 | Sampling ratio `0.25`, radius `20 Å`, 64 neighbors |
-| Set abstraction 3 | Sampling ratio `0.1`, radius `40 Å`, 64 neighbors |
-| Feature propagation | Three `k=3` interpolation stages |
-| Segmentation head | `128 -> 64 -> 32 -> 2`, dropout `0.5` |
-
-The inference parser creates centered Cα geometry and per-chain sequence
-chunks. ESM-C embeddings are reduced with the PCA asset paired to the selected
-checkpoint. PointNet++ processes every input structure as an independent graph
-and returns one two-class logit vector per residue.
-
-The geometry backend uses pure-PyTorch farthest-point sampling, radius search,
-and stable KNN interpolation. Radius neighborhoods retain the first 64 source
-neighbors in canonical input order. Inference runs in FP32 and records the
-execution mode in `summary.json`. Canonical ordering and neighbor selection are
-deterministic; floating-point reductions remain device- and kernel-dependent.
-
-### Training architecture
-
-ProtCross uses a source-domain residue segmentation objective and adversarial
-domain adaptation between PDB and matched AF2 structures. The target-domain
-adversarial term supports pLDDT weighting. The maintained model configuration
-uses `feature_dim=128`, `use_esm=true`, `use_da=true`, and `da_weight=0.2`.
-
-Training labels are generated from standard-residue Cα atoms within `6 Å` of
-eligible hetero-residue atoms. The parser applies a versioned residue-name
-filter for waters, common crystallization additives, salts, ions, and terminal
-caps.
-
 ## Batch inference
 
-ProtCross 0.2.2 batches ESM-C feature extraction and PointNet++ graph inference
-and preserves input order and per-structure outputs.
+Use one `ProtCrossPredictor` to process a directory of structures. ProtCross
+0.2.4 preserves input order, keeps each structure in its own result directory,
+and bounds ESM-C and PointNet++ microbatches by count and residue cost.
 
 ```python
 from pathlib import Path
 
 from protcross.inference import ProtCrossPredictor
 
-inputs = sorted(Path("structures").glob("*.pdb"))
-output_dir = Path("batch-results")
-output_dir.mkdir(parents=True, exist_ok=True)
+structure_dir = Path("structures")
+inputs = sorted(
+    path
+    for path in structure_dir.iterdir()
+    if path.is_file() and path.suffix.lower() in {".pdb", ".cif", ".mmcif"}
+)
+if not inputs:
+    raise FileNotFoundError(f"No PDB/mmCIF structures found in {structure_dir}")
+
+from datetime import datetime
+
+output_dir = Path("batch-results") / datetime.now().strftime("run-%Y%m%d-%H%M%S-%f")
+output_dir.mkdir(parents=True, exist_ok=False)
 
 predictor = ProtCrossPredictor.from_default_assets(
-    device="cuda",
+    device="auto",
     embedding_cache_dir=".protcross-feature-cache",
-    accept_esm_license=True,
 )
 
-output_paths = [
-    {
-        "output_pdb": output_dir / f"{path.stem}.protcross{path.suffix}",
-        "scores_tsv": output_dir / f"{path.stem}.protcross.scores.tsv",
-        "pocket_json": output_dir / f"{path.stem}.protcross.pockets.json",
-        "summary_json": output_dir / f"{path.stem}.protcross.summary.json",
-    }
-    for path in inputs
-]
+output_paths = []
+for index, path in enumerate(inputs, start=1):
+    result_dir = output_dir / f"{index:04d}-{path.stem}"
+    result_dir.mkdir(parents=True, exist_ok=True)
+    structure_suffix = ".cif" if path.suffix.lower() in {".cif", ".mmcif"} else ".pdb"
+    output_paths.append(
+        {
+            "output_pdb": result_dir / f"{path.stem}.protcross{structure_suffix}",
+            "scores_tsv": result_dir / f"{path.stem}.protcross.scores.tsv",
+            "pocket_json": result_dir / f"{path.stem}.protcross.pockets.json",
+            "summary_json": result_dir / f"{path.stem}.protcross.summary.json",
+        }
+    )
 
 results = predictor.predict_many(
     inputs,
@@ -462,9 +437,22 @@ results = predictor.predict_many(
     batch_size=4,
     max_batch_residues=4096,
     max_batch_quadratic_cost=4 * 1022**2,
+    return_exceptions=True,
 )
+
+for path, result in zip(inputs, results):
+    if isinstance(result, Exception):
+        print(f"FAILED {path}: {result}")
+    else:
+        print(f"DONE   {path}: {result.output_files['summary_json']}")
 ```
 
+The per-input result directories keep files distinct when structures share a
+stem or use different coordinate formats. `return_exceptions=True` lets the
+remaining inputs finish and keeps each exception in its original list position.
+Pass `chain_ids=[None, "A", ...]` to choose a chain independently for each
+input; `None` selects all scorable chains. The list must follow `inputs` order.
+
 ### Scheduler controls
 
 | Parameter | Default | Budget |
@@ -476,71 +464,65 @@ results = predictor.predict_many(
 | `max_feature_padded_tokens` | `2048` | Maximum padded ESM-C token matrix |
 | `return_exceptions` | `False` | Per-item exception collection |
 
-The scheduler keeps each structure in one PointNet++ graph and each chain in one
-ESM-C context. Identical chain sequences share one feature extraction
-within a microbatch. The feature cache validates tensor shape, PCA dimension,
-finite values, cache schema, and ESM/PCA asset identity.
-
-The residue and quadratic-cost limits are hard bounds for both a microbatch and
-each individual structure. An input graph that exceeds either limit fails before
-feature extraction; select a chain or raise the corresponding explicit limit.
-
-Accelerator memory errors trigger recursive microbatch splitting. With
-`return_exceptions=True`, failed items occupy their original list positions as
-exception objects. Completed items retain `PredictionResult` values.
-Desktop batch jobs use the same predictor API with a microbatch size of four.
-When a single-structure microbatch exhausts device memory, the item returns or
-raises that exception according to `return_exceptions`; chain selection and a
-smaller structure scope reduce its graph size.
-
-Cache keys include the chain sequence, cache schema, PCA dimension, maximum
-context, asset version, and ESM/PCA asset identity. Cache writes use atomic
-temporary-file replacement. Remove the cache directory to reclaim space or
-force feature regeneration. Predictors constructed with an injected ESM
-extractor or PCA reducer require a non-empty `feature_pipeline_fingerprint`
-before persistent feature caching can be enabled.
-
-The batch return type is `list[PredictionResult]` with the default exception
-mode and `list[PredictionResult | Exception]` with `return_exceptions=True`.
-Each `output_paths` mapping accepts `output_pdb`, `scores_tsv`, `pocket_json`,
-and `summary_json`; the result-schema aliases `structure` and `pockets_json`
-are accepted as well.
+Each structure remains one PointNet++ graph and each chain remains one ESM-C
+context. Identical chain sequences share feature extraction within a
+microbatch. Persistent cache entries include the sequence, PCA dimension,
+context limit, cache schema, and ESM/PCA asset identity.
+
+The residue and quadratic-cost settings bound both a microbatch and each
+individual structure. Select one chain or raise an explicit limit when a graph
+exceeds that budget. Accelerator memory errors trigger recursive microbatch
+splitting; a single item that still exhausts memory is reported through the
+selected exception mode. Desktop batch jobs use this API with groups of four.
+
+With the default exception mode, the return type is
+`list[PredictionResult]`. With `return_exceptions=True`, it is
+`list[PredictionResult | Exception]`. Each `output_paths` entry accepts the four
+writer names shown in the example.
 
 ## Python API
 
 ### Single-structure helper
 
+Use `predict_pdb` for a script that scores one structure and writes a complete
+result package:
+
 ```python
 from pathlib import Path
 
 from protcross.inference import predict_pdb
 
-output_dir = Path("results")
-output_dir.mkdir(parents=True, exist_ok=True)
+from datetime import datetime
+
+output_dir = Path("results") / datetime.now().strftime("run-%Y%m%d-%H%M%S-%f")
+output_dir.mkdir(parents=True, exist_ok=False)
 
 result = predict_pdb(
     "examples/6fhu.pdb",
     device="cpu",
-    accept_esm_license=True,
-    output_pdb="results/6fhu.protcross.pdb",
-    scores_tsv="results/6fhu.protcross.scores.tsv",
-    pocket_json="results/6fhu.protcross.pockets.json",
-    summary_json="results/6fhu.protcross.summary.json",
+    output_pdb=output_dir / "6fhu.protcross.pdb",
+    scores_tsv=output_dir / "6fhu.protcross.scores.tsv",
+    pocket_json=output_dir / "6fhu.protcross.pockets.json",
+    summary_json=output_dir / "6fhu.protcross.summary.json",
 )
 
 print(result.format_summary())
 ```
 
+`predict_pdb` resolves and downloads missing managed assets by default. Set
+`offline=True` for a local-cache-only run. Python writers replace existing files
+at explicitly supplied output paths. The examples use a new run directory each
+time to preserve earlier results; the CLI instead requires `--overwrite`.
+
 ### Reusable predictor
 
-Load `ProtCrossPredictor` once for repeated calls:
+Load `ProtCrossPredictor` once when a process will score several structures:
 
 ```python
 from protcross.inference import ProtCrossPredictor
 
 predictor = ProtCrossPredictor.from_default_assets(
     device="cpu",
-    accept_esm_license=True,
 )
 
 result = predictor.predict("examples/6fhu.pdb", threshold=0.5)
@@ -550,9 +532,9 @@ summary = result.to_summary_dict()
 ```
 
 Use one predictor per device worker and serialize calls that share an instance.
-Independent processes load independent model instances. CLI output protection
-uses `--overwrite`; Python writers publish each file through atomic replacement
-and require the annotated structure extension to match the input format.
+Independent processes load independent model instances. Python writers publish
+each output file through atomic replacement and keep the annotated structure in
+the input coordinate format.
 
 Structure inspection is also available from Python:
 
@@ -581,14 +563,14 @@ inspection = inspect_structure("examples/6fhu.pdb")
 
 ### Managed assets
 
-Prediction requires a checkpoint, its paired PCA reducer, and ESM-C 600M
-weights. Install the default bundle with:
+Prediction uses three matched assets: a ProtCross checkpoint, its PCA reducer,
+and ESM-C 600M weights. For most users, install the managed bundle once:
 
 ```bash
-protcross setup-assets --accept-esm-license
+protcross setup-assets
 ```
 
-The command installs these files under
+The command verifies and installs these files under
 `~/.cache/protcross/assets/v0.1.2`:
 
 ```text
@@ -598,9 +580,10 @@ esmc_600m_2024_12_v0.pth
 protcross-assets.json
 ```
 
-The ESM-C download is approximately 2.14 GiB. Asset setup supports partial
-download resumption, file locking, SHA256 verification, and atomic publication.
-Review the ESM-C model terms before recording acceptance.[^1]
+The ESM-C download is approximately 2.14 GiB. Interrupted transfers resume from
+retained partial data. Setup verifies SHA256 hashes and publishes completed
+files atomically. Later predictions reuse the manifest verification while file
+size and modification time remain unchanged.
 
 | Bundle | Checkpoint and PCA |
 | --- | --- |
@@ -611,37 +594,36 @@ Release compatibility:
 
 | Interface | Version |
 | --- | --- |
-| Application and Desktop | `0.2.2` |
+| Application and Desktop | `0.2.4` |
 | Default checkpoint/PCA bundle | `0.1.2` |
 | Paper reproduction bundle | `0.1.1-paper` |
 | Pocket and summary schemas | `protcross-pocket-v2`, `protcross-summary-v2` |
 
 `default` and `latest` resolve to the bundle pinned by the installed package.
-The checkpoint and PCA reducer come from the same bundle.
+Keep the checkpoint and PCA reducer from the same bundle.
 
 Configure another managed directory with either interface:
 
 ```bash
 PROTCROSS_ASSETS_DIR=/data/protcross-assets \
-  protcross setup-assets --accept-esm-license
+  protcross setup-assets
 
 protcross setup-assets \
-  --output-dir /data/protcross-assets \
-  --accept-esm-license
+  --output-dir /data/protcross-assets
+protcross predict input.pdb --assets-dir /data/protcross-assets
 ```
 
-Use `--refresh-assets` to rebuild and verify the managed cache. Use `--offline`
-or `--no-auto-assets` for local-only asset resolution.
+Use `--refresh-assets` for a fresh download and verification. Use `--offline`
+or `--no-auto-assets` to limit prediction to local files.
 
 ### Existing or custom assets
 
 Reuse an existing ESM-C file with an absolute path:
 
 ```bash
-protcross setup-assets --skip-esm --accept-esm-license
+protcross setup-assets --skip-esm
 protcross predict input.pdb \
   --esm-weights /absolute/path/to/esmc_600m_2024_12_v0.pth \
-  --accept-esm-license \
   --out-dir protcross-results
 ```
 
@@ -654,12 +636,11 @@ protcross predict input.pdb \
   --checkpoint /trusted/custom/model.ckpt \
   --esm-weights /trusted/custom/esmc.pth \
   --pca /trusted/custom/reducer.pkl \
-  --trust-unverified-assets \
-  --accept-esm-license
+  --trust-unverified-assets
 ```
 
 Checkpoint, PCA, and PyTorch weight files can contain executable serialized
-objects. Use assets from controlled storage. ESM-C weights are distributed
+objects. Load them from controlled storage. ESM-C weights are distributed
 through the EvolutionaryScale model repository.[^2]
 
 CLI and Desktop assets use separate storage roots. Desktop records its selected
@@ -674,15 +655,18 @@ uses a per-session token for local API requests.
 ### Install
 
 Download the matching release artifact and `SHA256SUMS.txt` from
-[the v0.2.2 release](https://github.com/GeraltZeroZhong/ProtCross/releases/tag/v0.2.2):
+[the v0.2.4 release](https://github.com/GeraltZeroZhong/ProtCross/releases/tag/v0.2.4):
 
 ```text
-ProtCross_Desktop_0.2.2_x64-setup.exe
-ProtCross_Desktop_0.2.2_macos-aarch64.dmg
+ProtCross_Desktop_0.2.4_x64-setup.exe
+ProtCross_Desktop_0.2.4_macos-aarch64.dmg
 ```
 
-The guided first-launch workflow installs a CPU runtime, records ESM-C term
-acceptance, downloads or imports model assets, and validates readiness. Advanced
+The guided first-launch workflow installs a CPU runtime, downloads or imports
+model assets, and validates readiness. Installation shows its current stage;
+**Open runtime logs** works even when the backend cannot start. Reinstalling the
+recommended runtime also recovers from an unusable previously selected environment.
+Advanced
 runtime options provide NVIDIA CUDA on Windows, Apple MPS on macOS, custom Conda
 environments, and proxy configuration. Reserve approximately 5 GiB for the
 runtime and ESM-C asset.
@@ -690,11 +674,17 @@ runtime and ESM-C asset.
 Run a first Desktop prediction in five steps:
 
 1. Open **Setup**, install a backend, and validate it.
-2. Review the ESM-C terms, then download or import the ESM-C weights.
+2. Download or import the ESM-C weights.
 3. Open **Predict**, select a local PDB/mmCIF file, and inspect it.
 4. Select the chain scope and output directory; expand prediction settings when needed.
 5. Open **Results** to inspect the 0–1 score color scale, residue clusters, and output package.
 
+Single predictions show the active stage and elapsed time. **Cancel prediction**
+restarts the runtime after confirmation; completed result files are kept. Finish
+an active batch or pause its asset download before starting a single prediction.
+Stopped batches offer **Continue remaining**, retaining their original settings
+and skipping completed structures. Quitting during active work asks for confirmation.
+
 The interface follows the system appearance by default and also provides light
 and dark modes. Keyboard focus indicators, reduced-motion handling, high-contrast
 support, resizable layouts, semantic status messages, and compact-window reflow
@@ -710,27 +700,88 @@ Tauri 2 shell
   -> ProtCross predictor and batch scheduler
 ```
 
-Desktop batch jobs reuse one predictor, reuse input inspection reports, expose
-per-item status, and support cancellation between microbatches.
-
-For a batch run, open **Batch**, add and review the deduplicated structure list,
-select one output root, and start the queue. The staging list supports repeated
-file selection, per-file removal, and clearing. Runtime progress, completed,
-failed, and remaining counts stay visible while the queue runs. Each input
-receives a unique subdirectory containing the four-file output package. Select a
-completed row to open it in **Results**; completed items remain available when
-the queue is cancelled.
+Desktop batch jobs reuse one predictor and the input inspection reports. Each
+staged file has its own chain selector, including all scorable chains and blank
+chain IDs. The monitor exposes per-item status and full errors, supports
+cancellation between microbatches, and can start a new queue containing only
+failed or interrupted items.
+
+For a batch run, open **Batch**, add the structures, review the deduplicated
+list, choose one output root, and start the queue. Progress and per-item status
+remain visible while the queue runs. Each input receives a unique subdirectory
+with the four-file result package. Select any completed row to inspect it in
+**Results**. Recent batch history is stored in the Desktop application-data
+directory and restored on the next launch. Work that was active during a
+restart appears as interrupted and can be retried; completed items and their
+files remain available.
 
 When the output field is empty, Desktop writes single predictions under its
 application-data `outputs/<structure>/` directory and batch predictions under
 `outputs/batch/<job-id>/`. The active platform path is displayed below the
 output field.
 
-The Results workspace maps annotated B-factor values to a continuous ProtCross
-model-score color theme and overlays the selected cluster in ball-and-stick
-representation. A previous result can be reopened by selecting its
-`*.protcross.summary.json` file. Diagnostics presents backend and asset health
-before the expandable technical report.
+The **Results** workspace colors scored residues by model score and gives
+unscored residues a neutral gray color, including residues outside a selected
+chain or a truncated sequence context. Adjust the displayed score cutoff and
+Cα clustering distance to regroup the complete residue table immediately;
+this updates the viewer and cluster inspector without running the model or
+changing output files. Reopen a previous package by selecting its
+`*.protcross.summary.json` file. Use **Diagnostics** to test the runtime, review
+asset health, and export a sanitized support ZIP with bounded log excerpts.
+
+## Model and inference pipeline
+
+```mermaid
+flowchart LR
+    accTitle: ProtCross inference pipeline
+    accDescr: Coordinate files are parsed into per-chain sequences and a shared C-alpha graph, embedded with ESM-C and PCA, scored by PointNet++, and serialized as annotated coordinates, scores TSV, pockets JSON, and summary JSON.
+
+    coordinates["PDB or mmCIF"] --> parser["Structure parser"]
+    parser --> sequence["Per-chain sequence"]
+    parser --> geometry["Centered Cα graph"]
+    sequence --> esmc["ESM-C 600M"]
+    esmc --> pca["PCA 128"]
+    pca --> pointnet["PointNet++"]
+    geometry --> pointnet
+    pointnet --> scores["Residue scores"]
+    scores --> clusters["Threshold and cluster"]
+    clusters --> outputs["Four-file result package"]
+```
+
+### Components
+
+| Component | Configuration |
+| --- | --- |
+| ESM-C | 600M, hidden size 1,152, 36 layers, 18 attention heads |
+| PCA | Paired reducer, 128 output dimensions |
+| Set abstraction 1 | Sampling ratio `0.5`, radius `10 Å`, 64 neighbors |
+| Set abstraction 2 | Sampling ratio `0.25`, radius `20 Å`, 64 neighbors |
+| Set abstraction 3 | Sampling ratio `0.1`, radius `40 Å`, 64 neighbors |
+| Feature propagation | Three `k=3` interpolation stages |
+| Segmentation head | `128 -> 64 -> 32 -> 2`, dropout `0.5` |
+
+The inference parser creates centered Cα geometry and per-chain sequence
+chunks. ESM-C embeddings are reduced with the PCA asset paired to the selected
+checkpoint. PointNet++ processes every input structure as an independent graph
+and returns one two-class logit vector per residue.
+
+The geometry backend uses pure-PyTorch farthest-point sampling, radius search,
+and stable KNN interpolation. Radius neighborhoods retain the first 64 source
+neighbors in canonical input order. Inference runs in FP32 and records the
+execution mode in `summary.json`. Canonical ordering and neighbor selection are
+deterministic; floating-point reductions remain device- and kernel-dependent.
+
+### Training architecture
+
+ProtCross uses a source-domain residue segmentation objective and adversarial
+domain adaptation between PDB and matched AF2 structures. The target-domain
+adversarial term supports pLDDT weighting. The maintained model configuration
+uses `feature_dim=128`, `use_esm=true`, `use_da=true`, and `da_weight=0.2`.
+
+Training labels are generated from standard-residue Cα atoms within `6 Å` of
+eligible hetero-residue atoms. The parser applies a versioned residue-name
+filter for waters, common crystallization additives, salts, ions, and terminal
+caps.
 
 ## Training and development
 
@@ -752,6 +803,14 @@ reproduction/        archived paper-era workflows
 examples/            example coordinate files
 ```
 
+### Development environment
+
+```bash
+conda env create -f environment.yml
+conda activate protcross
+python -m pip install -e ".[dev,esm]"
+```
+
 ### Maintained training workflow
 
 Place source coordinate files in `data/raw_pdb`. `protcross download-af2`
@@ -770,16 +829,14 @@ protcross preprocess \
   --fit-pca \
   --esm-weights ~/.cache/protcross/assets/v0.1.2/esmc_600m_2024_12_v0.pth \
   --pca artifacts/protcross-pca-128.pkl \
-  --pca-dim 128 \
-  --accept-esm-license
+  --pca-dim 128
 
 protcross preprocess \
   --data-dir data/raw_af2 \
   --output-dir data/processed_af2 \
   --esm-weights ~/.cache/protcross/assets/v0.1.2/esmc_600m_2024_12_v0.pth \
   --pca artifacts/protcross-pca-128.pkl \
-  --is-af2 \
-  --accept-esm-license
+  --is-af2
 
 protcross map-labels \
   --processed-pdb-dir data/processed_pdb \
@@ -794,7 +851,9 @@ protcross train
 Preprocessing writes one `.pt` tensor package per structure and an atomic
 `protcross-preprocess-manifest.json`. The manifest records completion state,
 input hashes, generated outputs, failures, and skipped files. PCA fitting uses
-the configured preprocessing seed.
+the configured preprocessing seed. Training cache freshness uses `.pt` file
+names, sizes, and modification times, so dataset startup does not reread every
+tensor package solely to hash it.
 
 Hydra configuration entry points:
 
@@ -819,13 +878,11 @@ protcross train \
 
 ```bash
 protcross setup-assets \
-  --asset-version 0.1.1-paper \
-  --accept-esm-license
+  --asset-version 0.1.1-paper
 
 python reproduction/legacy/run_Predict_ProtCross.py \
   --pdb_file examples/6fhu.pdb \
-  --asset-version 0.1.1-paper \
-  --accept-esm-license
+  --asset-version 0.1.1-paper
 ```
 
 The [`reproduction/legacy/`](reproduction/legacy/) directory contains the archived PDBbind v2020
@@ -864,7 +921,6 @@ npm run tauri:dev
 | Symptom | Resolution |
 | --- | --- |
 | Unsupported Python version | Create a Python 3.10 environment and reinstall |
-| ESM-C acceptance prompt | Run `protcross setup-assets --accept-esm-license` |
 | Interrupted asset transfer | Repeat setup; the downloader resumes retained `.part` data |
 | Asset verification failure | Run setup with `--refresh-assets` |
 | Existing output path | Select another `--out-dir` or pass `--overwrite` |
@@ -883,6 +939,27 @@ diagnostics.
 
 ## Version history
 
+### 0.2.4
+
+- Removed ESM-C license acceptance under the upstream MIT license, retained
+  legacy arguments, and simplified Desktop setup to two steps.
+- Improved Desktop runtime recovery, same-file checks, filtered centroids,
+  offline logs, task progress and cancellation, batch continuation, and exit prompts.
+- Added early dependency checks, custom asset-directory instructions, quiet
+  asset logging, clearer download errors, and Python examples that preserve earlier runs.
+
+### 0.2.3
+
+- Reused verified asset manifests and metadata-based dataset signatures to cut
+  repeated hashing and startup work; accelerated AF2 indexing, preprocessing,
+  strategy search, and long-log assembly.
+- Removed redundant prediction, CLI, data-loading, and output-rollback layers;
+  retained bounded scheduling, input contracts, and atomic per-file outputs.
+- Improved machine-readable inspection errors, chain guidance, Desktop error
+  display and diagnostic exports, per-file batch chain selection, failed-item
+  retry, restart-safe batch history, interactive result regrouping, and neutral
+  rendering for unscored residues.
+
 ### 0.2.2
 
 - Added bounded ESM-C and PointNet++ microbatching with graph, residue,
@@ -892,7 +969,7 @@ diagnostics.
 - Accelerated deterministic geometry and inference parsing; corrected small-set
   split leakage, label-alignment statistics, AF2 mapping, and mmCIF residue
   identity; added finite-value gates, isolated feature-cache namespaces, and
-  transactional dataset and result publication.
+  transactional dataset publication and atomic per-file result writes.
 - Rebuilt ProtCross Desktop around responsive task workspaces, semantic OKLCH
   themes, accessible interaction states, score-aware Mol* rendering, structured
   diagnostics, persistent batch feedback, and result-package reopening.
@@ -944,10 +1021,10 @@ If ProtCross contributes to a publication, cite:
 ## License
 
 ProtCross source code is distributed under the [MIT License](LICENSE).
-ESM-C weights use EvolutionaryScale's model terms.[^1] ProtCross checkpoint and
+ESM-C weights are distributed under the MIT license.[^1] ProtCross checkpoint and
 PCA bundles are distributed separately from ESM-C weights.
 
-[^1]: EvolutionaryScale. [Cambrian Non-Commercial License Agreement](https://www.evolutionaryscale.ai/policies/cambrian-non-commercial-license-agreement).
+[^1]: Biohub. [ESM-C model license](https://huggingface.co/biohub/esmc-600m-2024-12).
 
 [^2]: EvolutionaryScale. [ESM-C 600M 2024-12 model repository](https://huggingface.co/EvolutionaryScale/esmc-600m-2024-12).