Validate Command¶

For --assess_bias, prepare and select source bundles as described in Providing bias training data, including the whole policy, shared query cache, and prepared custom-complex supplements.

The validate command performs co-folding of a single protein-ligand system.

Evidence regimes¶

Regime	Inputs	Applicable diagnostics
Reference complex	`--reference_path` with a PDB/mmCIF/CIF complex	Protein/ligand RMSD, SuCOS, pose overlap, reference pocket coverage, reference-derived IFP analysis
Pocket only	`--pocket_coverage_reference` without a structure reference	Custom pocket coverage, distance IFPs, exposure, confidence, robustness, and optional bias context
Reference free	Neither reference input	Confidence, binding/affinity when runner-supported, SASA, interactions, repeat consistency, and optional bias context

Unavailable evidence is represented explicitly; it does not turn an unrelated diagnostic into a failure. No regime or metric provides a universal correctness threshold.

Basic Usage¶

cofolder validate -s system.yaml -o options.yaml

Arguments¶

Required Arguments¶

-s, --system_path: Path to system YAML file
-o, --options_path: Path to runner options YAML file

Optional Arguments¶

-w, --wrk_dir: Working directory (default: current directory)
--conformers {2D,3D,sdf}: Generate or load conformers for SMILES input
--sdf_file: SDF path (required with --conformers sdf)
--assess_bias: Add shared bias diagnostics under results/bias_train/
-d, --debug: Enable debug logging

Examples¶

Basic Validation¶

cofolder validate \
  -s examples/system.yaml \
  -o examples/options.yaml \
  -w ./output

With 3D Conformer Generation¶

cofolder validate \
  -s system.yaml \
  -o options.yaml \
  --conformers 3D

With Debug Logging¶

cofolder validate \
  -s system.yaml \
  -o options.yaml \
  -d

When --debug is enabled, COFOLDER emits benchmark-friendly timing lines in the log:

TIMER | <label> | <seconds>s during the run
TIMER SUMMARY | <label> | <seconds>s at the end

This is intended for component benchmarking. For reproducible benchmark numbers, use warmed Boltz cache/model files and fresh prediction outputs so one-time downloads or cache-hit skips do not distort timings.

With Shared Bias Diagnostics¶

cofolder validate \
  -s system.yaml \
  -o options.yaml \
  --assess_bias \
  --protein_training_data_path protein_training_data.csv \
  --ligand_training_data_path ligand_training_data.csv

This uses the same bias-reporting seam as the standalone bias workflow and writes those diagnostics to <wrk_dir>/results/bias_train/ alongside the runner-backed prediction outputs.

System File Format¶

version: 1
sequences:
  - protein:
      id: "protein_1"
      fasta: "MKTAYIAKQRQISFV..."
  - ligand:
      id: B
      smiles: "CC(C)Cc1ccc(cc1)C(C)C(=O)O"

Each ligand defines exactly one of smiles, ccd, or ccd_codes. Use CCD instead of SMILES when stable atom names or a preprocessed multi-component ligand is needed.

Output¶

The command creates:

raw/ - runner-owned raw execution artifacts
results/records.jsonl - authoritative success, metric, and failure records
results/successes.csv, results/metrics.csv, and results/failures.csv - tabular views
results/manifest.json - schema, invocation, evidence, and artifact metadata
results/structures/ - gathered output structures
results/bias_train/ - optional shared bias diagnostics when --assess_bias is enabled
log files in the working directory

Bias outputs remain distinct from validation metrics, model-confidence outputs, and any affinity predictions. They are reference-overlap diagnostics, not a proxy for binding affinity or expected cofolding success.

Tips¶

Use absolute paths in YAML files for reproducibility
Validate SMILES strings before prediction
Check GPU memory availability for large systems
Use debug mode to troubleshoot issues