Commands & Options

Synopsis#

zsasa calc <input> [output] [OPTIONS]
zsasa calc --workflow <workflow.toml>
zsasa batch <input_dir> [output_dir] [OPTIONS]
zsasa batch --workflow <workflow.toml>
zsasa traj <trajectory> <topology> [OPTIONS]
zsasa compile-dict <input.cif[.gz|.zst]> -o <output.zsdc>

Workflow Files#

zsasa calc --workflow <workflow.toml>
zsasa batch --workflow <workflow.toml>

Workflow files are TOML files that keep input, output, calculation, classifier, and batch job settings together. In batch mode, --manifest remains a compatibility alias for --workflow; it also accepts the older flat-root manifest layout.

A workflow file is written for one command. A key that the command does not read is never ignored silently: it is an error when it would change the results (for example [[jobs]] or [input] dir under calc --workflow, or [calculation] rsa = true under batch --workflow) and a warning, printed also with --quiet, when it only affects reporting or the output location (for example [output] dir under calc --workflow, or timing = true in a batch workflow with [[jobs]]). See Keys a Command Does Not Read.

See Workflow Files for full examples, the key reference, precedence rules, custom classifier config, and residue-map usage.

Subcommands#

calc - Single File SASA Calculation#

Calculate SASA for a single structure file.

zsasa calc structure.cif output.json
zsasa calc --workflow sasa.toml

batch - Directory Batch Processing#

Process all structure files in a directory.

zsasa batch structures/ results/
zsasa batch --workflow bsa.toml

Positional paths are required for ordinary batch mode, but can be supplied by the workflow file when using --workflow.

Batch mode uses file-level parallelism: multiple files are processed simultaneously, one thread per file. Use --threads to control the number of concurrent files.

For task-oriented examples, see Batch Processing and Workflow Files.

traj - Trajectory Analysis#

Calculate SASA for each frame in a trajectory file (XTC, TRR, DCD, or AMBER NetCDF).

zsasa traj trajectory.xtc topology.pdb --output=sasa.csv

See Trajectory Options for traj-specific options and details.

compile-dict - Compile CCD Dictionary#

Convert a CCD dictionary from CIF text to compact binary ZSDC format for faster loading.

zsasa compile-dict components.cif.gz -o components.zsdc

The compiled ZSDC file can then be used with --ccd=components.zsdc for faster dictionary loading compared to parsing CIF text at runtime.

compile-dict stops with a non-zero exit status, and writes no output file (an existing file at the output path is left untouched), when:

• the input contains no components (no _chem_comp_atom loop with rows);
• a component has more than 65,535 atoms or more than 65,535 bonds, the most the ZSDC format can store;
• a component ID is longer than 255 bytes.

--ccd= rejects a ZSDC file whose lengths, counts or bond orders are invalid, that is shorter than its counts say, that lists a component twice, or that has bytes after its last component. The error names the problem (for example InvalidAtomLength or UnexpectedEof). Files written by earlier versions of compile-dict load unchanged.

Basic Usage#

# Basic SASA calculation
./zig-out/bin/zsasa calc structure.cif output.json

# With algorithm selection
./zig-out/bin/zsasa calc --algorithm=lr structure.cif output.json

# Multi-threaded
./zig-out/bin/zsasa calc --threads=4 structure.cif output.json

# With analysis features
./zig-out/bin/zsasa calc --rsa --polar structure.cif output.json

# With workflow file
./zig-out/bin/zsasa calc --workflow sasa.toml

Calc-only Options#

Custom classifier config#

--config=FILE is a calc-only option for advanced custom classifiers. Files must use TOML format and the .toml extension. If both --classifier and --config are specified for calc, --config takes precedence and a warning is printed.

zsasa calc --config=my_classifier.toml structure.cif output.json

For batch custom classifier configs, use a workflow [classifier] section. See Workflow Files.

Options#

The three commands share most of their options but not all of them. The Commands column of every table below lists the commands that accept the option; a command rejects any other option with Error: Unknown option: <option>. calc, batch and traj all accept -h, --help.

Algorithm Options#

Classifier Options#

When --classifier is used, atom radii are assigned based on residue and atom names. For PDB/mmCIF/BinaryCIF/SDF/MOL input, ccd is used by default. HETATM records are excluded unless --include-hetatm is given, whichever classifier is used.

--ccd and --sdf only matter for the ccd classifier; with another classifier they are ignored.

See Classifiers for detailed classifier documentation.

Structure Filtering#

traj always reads every ATOM and HETATM record of the first model of its topology; see Trajectory Options.

Analysis Options#

See Output & Analysis for detailed output descriptions.

Workflow Options#

Batch Input Options#

Output Options#

batch --format=jsonl without an output path writes the rows to standard output.

Prefer json or jsonl for machine-readable pipelines. The freesasa and rsa formats are legacy compatibility text formats; rsa warns if values do not fit legacy NACCESS fixed-width columns.

Information Options#

Help and version are written to standard output, so they can be piped and captured (zsasa --version prints zsasa <version>). Progress, summaries, warnings and error messages are written to standard error, as is the usage text that follows an error such as an unknown command.

Trajectory Options#

The traj subcommand has additional options specific to trajectory processing.

Arguments#

Options#

Every option marked traj in the algorithm, classifier, structure filtering and output tables applies, plus the trajectory-specific options below. For trajectory calculations, --classifier defaults to naccess (not ccd); traj has no custom config CLI option, so use a built-in classifier. The structure filters --chain, --model, --auth-chain and --include-hetatm, the analysis options, --format, --timing and --validate are not available (Error: Unknown option): traj writes the total SASA of all topology atoms per frame, and the output file is always given with -o/--output (there is no positional output argument).

Notes#

• Supported trajectory formats: XTC and TRR (GROMACS), DCD (NAMD/CHARMM), and AMBER NetCDF (.nc, .ncdf), auto-detected from extension
• Coordinates are normalized to Å internally by the ztraj readers before SASA calculation.
• Hydrogen atoms are included by default in trajectory mode; use --no-hydrogens to exclude them. The option removes hydrogens from the topology and from every frame, so the trajectory itself must still contain them
• Topology file provides atom names for radius classification. Every ATOM and HETATM record of its first model is read, in file order; later models of an NMR ensemble are ignored. Solvent, ions and ligands in the topology are therefore part of the calculation
• The number of atoms in the trajectory must match the topology (before hydrogens are removed)
• Default precision is f32 (faster for trajectory processing). --algorithm and --precision are independent: all four combinations are available
• Options are validated before the output file is created, so a rejected command leaves an existing output file untouched
• If reading or calculating a frame fails, the command exits with an error after writing the frames completed before it

Examples#

Basic Calculations#

# mmCIF input
./zig-out/bin/zsasa calc structure.cif output.json

# PDB input
./zig-out/bin/zsasa calc structure.pdb output.json

# JSON input
./zig-out/bin/zsasa calc atoms.json output.json

Algorithm Selection#

# Lee-Richards with 50 slices
./zig-out/bin/zsasa calc --algorithm=lr --n-slices=50 structure.cif output.json

# Lee-Richards with the approximate arc angles of zsasa 0.9.1 and earlier
./zig-out/bin/zsasa calc --algorithm=lr --lr-trig=fast structure.cif output.json

# Shrake-Rupley with 200 test points
./zig-out/bin/zsasa calc --algorithm=sr --n-points=200 structure.cif output.json

Performance Tuning#

# Fast mode: f32 precision
./zig-out/bin/zsasa calc --precision=f32 structure.cif output.json

# Multi-threaded
./zig-out/bin/zsasa calc --threads=4 structure.cif output.json

# Show timing breakdown
./zig-out/bin/zsasa calc --timing structure.cif output.json

Classifier Usage#

# NACCESS classifier
./zig-out/bin/zsasa calc --classifier=naccess structure.cif output.json

# Custom config
./zig-out/bin/zsasa calc --config=custom.toml structure.cif output.json

Small Molecules#

# Second molecule of a multi-molecule SDF file
./zig-out/bin/zsasa calc --mol=2 molecules.sdf output.json

Chain/Model Filtering#

# Single chain
./zig-out/bin/zsasa calc --chain=A structure.cif output.json

# Multiple chains
./zig-out/bin/zsasa calc --chain=A,B,C structure.cif output.json

# Specific model (NMR)
./zig-out/bin/zsasa calc --model=1 nmr_structure.cif output.json

# Use auth chain IDs
./zig-out/bin/zsasa calc --auth-chain --chain=A structure.cif output.json

Atom Filtering#

By default, hydrogen atoms and HETATM records (ligands, ions, waters) are excluded, whichever classifier is used.

# Include hydrogen atoms
./zig-out/bin/zsasa calc --include-hydrogens structure.pdb output.json

# Include HETATM records (water, ligands, etc.)
./zig-out/bin/zsasa calc --include-hetatm structure.pdb output.json

# Include both
./zig-out/bin/zsasa calc --include-hydrogens --include-hetatm structure.pdb output.json

Batch Processing#

# Basic batch processing
./zig-out/bin/zsasa batch input_dir/ output_dir/

# Multi-threaded (file-level parallelism)
./zig-out/bin/zsasa batch --threads=8 input_dir/ output_dir/

# One JSONL file for all structures (without -o the rows go to standard output)
./zig-out/bin/zsasa batch --format=jsonl -o results.jsonl input_dir/

# With workflow file
./zig-out/bin/zsasa batch --workflow bsa.toml

BSA workflow interface maps may contain multiple stable-ID rows for one input filename. The command writes one JSONL success or error row per requested interface; residue components and opt-in atom detail are configured in the workflow. See Workflow Files.

Ordinary SASA workflow chain_map files may also contain multiple stable-ID rows per filename. zsasa parses and classifies each source once, reuses identical chain-set calculations, and emits primitive SASA JSONL rows for downstream analysis. See Per-file Chain Maps.

Trajectory Analysis#

# Basic trajectory analysis
zsasa traj trajectory.xtc topology.pdb

# With NACCESS classifier
zsasa traj trajectory.xtc topology.pdb --classifier=naccess

# Every 10th frame
zsasa traj trajectory.xtc topology.pdb --stride=10

# Frames 100-200 only
zsasa traj trajectory.xtc topology.pdb --start=100 --end=200

# Write the CSV to a chosen file
zsasa traj trajectory.xtc topology.pdb -o sasa.csv

# Lee-Richards algorithm with f64 precision
zsasa traj trajectory.xtc topology.pdb --algorithm=lr --precision=f64

Validation Only#

# Validate without calculation
./zig-out/bin/zsasa calc --validate structure.cif

Error Messages#

Errors are written to standard error and the command exits with status 1. <...> marks a value taken from the command line or the input.

Command line#

Input files#

Exit Codes#