Artifacts

substrax.artifacts decides where a run writes its figures, tables and other outputs, and never defaults into the working tree.

import argparse
from pathlib import Path

from substrax.artifacts import resolve_output_dir


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--output-dir", type=Path, default=None)
    args = parser.parse_args()

    location = resolve_output_dir("fno_darcy", explicit=args.output_dir)
    figure_path = location.path / "prediction.png"

resolve_output_dir takes the first of these that applies and creates the directory:

Order	Directory	source
1	explicit, resolved against the working directory when it is relative	"argument"
2	$AVITAI_OUTPUT_DIR/<name>; the variable must hold an absolute path	"environment"
3	<name> inside a directory created once per process under the system temporary directory	"run_default"

Writing figures into the documentation is an explicit choice: python examples/neural-operators/fno_darcy.py --output-dir docs/assets/examples/fno_darcy. A test run or a CI job sets AVITAI_OUTPUT_DIR instead, so running an example never rewrites tracked files.

The per-run directory is created with tempfile.mkdtemp, so its name cannot be claimed by another user of a shared temporary directory and only its owner can read it. Every default output in one process shares it. name must be a relative path that stays inside the output directory. Importing the package creates nothing.

substrax.artifacts

Output directories that never default into the working tree.

resolve_output_dir picks the directory a run writes to: an explicit argument, then AVITAI_OUTPUT_DIR, then a directory created once per process under the system temporary directory. Importing this package creates nothing.

OutputLocation(*, path, source) dataclass

A resolved output directory and where the choice came from.

Attributes:

Name	Type	Description
path	Path	The absolute directory, which exists.
source	Literal['argument', 'environment', 'run_default']	"argument" for a directory the caller passed, "environment" for one under AVITAI_OUTPUT_DIR, "run_default" for one under the per-run directory.

resolve_output_dir(name, *, explicit=None, env=None)

Return the directory a run writes the output called name to, creating it.

The directory is explicit when given, with a relative path resolved against the working directory. Otherwise it is $AVITAI_OUTPUT_DIR/<name>, and otherwise <name> inside a directory created once per process under the system temporary directory. It never defaults into the working tree, so running an example or a test cannot overwrite tracked files, and writing into docs/assets is always an explicit choice.

Parameters:

Name	Type	Description	Default
name	str	The output's relative path, such as "fno_darcy".	required
explicit	Path | None	A directory chosen by the caller, typically from an --output-dir option.	None
env	Mapping[str, str] | None	The environment AVITAI_OUTPUT_DIR is read from; os.environ when None.	None

Returns:

Type	Description
OutputLocation	The created directory and the source it was chosen from.

Raises:

Type	Description
ValueError	If name is empty, absolute or leaves the output directory, or AVITAI_OUTPUT_DIR holds a relative path.