Workflow Files
Workflow files keep input paths, output paths, calculation settings, and classifier settings in a reproducible TOML file.
Use workflows when command lines become long, when you need named batch jobs, or when you want settings committed alongside an analysis.
Commands
zsasa calc --workflow sasa.toml
zsasa batch --workflow bsa.toml
For batch mode, --manifest is still accepted as a compatibility alias for --workflow:
zsasa batch --manifest bsa.toml
Prefer --workflow in new scripts and docs.
Calc Workflow Example
version = 1
kind = "workflow"
[input]
path = "structure.cif"
[output]
path = "sasa.json"
format = "json"
[calculation]
algorithm = "sr"
rsa = true
n_points = 100
probe_radius = 1.4
threads = 0
[classifier]
type = "ccd"
ccd = "components.zsdc"
Run it with:
zsasa calc --workflow sasa.toml
Batch Workflow Example
Batch workflows contain one or more named [[jobs]] entries:
version = 1
kind = "workflow"
[input]
dir = "structures"
[output]
dir = "results"
format = "jsonl"
[calculation]
algorithm = "sr"
residue_map = true
n_points = 100
threads = 8
[classifier]
type = "custom"
config = "my_classifier.toml"
[[jobs]]
name = "chain_a"
chains = ["A"]
[[jobs]]
name = "chain_b"
chains = ["B"]
[[jobs]]
name = "complex_ab"
chains = ["A", "B"]
Run it with:
zsasa batch --workflow bsa.toml
For ordinary PDB, JSON, and unfiltered mmCIF/BinaryCIF workflow batch runs with compatible chain-ID settings, zsasa reuses each parsed input structure across jobs internally. For named chain analyses such as chain A, chain B, and complex AB, list only the jobs you want; eligible runs parse each input structure once and then compute each requested chain selection independently. Some inputs or settings, such as SDF files, per-job auth_chain changes, or mmCIF/BinaryCIF workflows with chain filters, use the compatibility job-first path instead so full chain-ID selection matches parser behavior.
Override Precedence
When the same setting appears in multiple places, zsasa applies this order:
built-in defaults < workflow settings < job settings < explicit CLI options
For example, this command uses the workflow but overrides the thread count:
zsasa batch structures/ results/ --workflow bsa.toml --threads=16
Workflow Jobs vs CLI Chain Filters
Use CLI flags for a single ad hoc chain-filtered batch run:
zsasa batch structures/ results/ --chain=A
Use workflow jobs for named, repeatable multi-chain analyses:
[[jobs]]
name = "chain_a"
chains = ["A"]
[[jobs]]
name = "complex_ab"
chains = ["A", "B"]
Custom Classifier Configs
Custom classifier configs are TOML-only. In batch workflows, set them in the workflow classifier section:
[classifier]
type = "custom"
config = "my_classifier.toml"
For single calc commands, you can also use the CLI option:
zsasa calc --config=my_classifier.toml structure.cif output.json
Residue Maps
Set residue_map = true under [calculation] to add compact residue arrays to JSONL rows:
[output]
format = "jsonl"
[calculation]
residue_map = true
This is equivalent to passing --residue-map with --format=jsonl in non-workflow batch mode.