Fallback behavior

turbo-picard targets full Picard 3.4.0 command compatibility. Commands without a native fast path, plus unsupported options on accelerated commands, are delegated to upstream Picard.

Auto-discovery

When TURBO_PICARD_FALLBACK_COMMAND is unset, turbo-picard tries to find upstream Picard automatically:

  • PICARD_JAR if set;

  • $CONDA_PREFIX/share/picard-*/picard.jar;

  • an executable picard on PATH that is not the turbo-picard shim.

Disable auto-discovery with:

export TURBO_PICARD_DISABLE_AUTO_FALLBACK=1

Explicit override

For reproducible environments, set an absolute upstream command prefix:

export TURBO_PICARD_FALLBACK_COMMAND='java -jar /opt/picard/picard.jar'

or:

export TURBO_PICARD_FALLBACK_COMMAND='mamba run -p /opt/conda/envs/picard picard'

What delegates

turbo-picard delegates:

  • every Picard 3.4.0 command without a native fast path;

  • explicitly unsupported native options or formats that the native implementation recognizes as outside its current scope;

  • JVM-style leading options when upstream Picard is available.

Delegation keeps command compatibility. It does not replace the output parity evidence in What Parity Means for accelerated commands you plan to switch. Treat fallback as a compatibility bridge, not proof that every accelerated surface is interchangeable with Picard. Unsupported surfaces remain visible so operators can tell when a workflow is using upstream Picard instead of a native turbo-picard fast path.

What does not delegate

Native I/O failures and malformed inputs are reported by the native command. They are not sent to fallback, because doing so could hide real data or environment problems.

Avoid fallback loops

Prefer an absolute upstream Picard path or JAR path. A fallback value such as picard can resolve back to the turbo-picard shim if the shim shadows upstream Picard on PATH.