1 configs

configs

Lazy stable imports for ARIA-NBV configuration factories.

Loading PathConfig must not import optional Optuna, W&B, TorchMetrics, or Lightning runtime stacks. The public names remain available through module attribute lookup and are imported only when requested.

1.1 Package guide

aria_nbv.configs exposes trusted configuration families and a safe authoring transaction around their existing BaseConfig validation. It does not import runtime targets merely to inspect a file, and it never discovers model classes from strings stored in TOML.

Code

sequenceDiagram
  participant U as User
  participant A as Streamlit config workspace
  participant D as ConfigDocument
  participant P as Pydantic model
  participant F as TOML file

  U->>A: Select trusted config
  A->>D: Open path and root model
  D->>P: Validate parsed values
  P-->>A: Values, schema, docs, policies
  U->>A: Edit draft and submit form
  A->>D: Validate patch
  D->>P: Validate complete config tree
  P-->>A: Valid config or located errors
  U->>A: Save copy
  A->>D: Save with expected SHA-256
  D->>F: Atomic comment-preserving write
  F-->>A: Write receipt and new digest

sequenceDiagram
  participant U as User
  participant A as Streamlit config workspace
  participant D as ConfigDocument
  participant P as Pydantic model
  participant F as TOML file

  U->>A: Select trusted config
  A->>D: Open path and root model
  D->>P: Validate parsed values
  P-->>A: Values, schema, docs, policies
  U->>A: Edit draft and submit form
  A->>D: Validate patch
  D->>P: Validate complete config tree
  P-->>A: Valid config or located errors
  U->>A: Save copy
  A->>D: Save with expected SHA-256
  D->>F: Atomic comment-preserving write
  F-->>A: Write receipt and new digest

1.2 Workflow

Open a trusted path together with its root model, inspect field descriptors, validate a partial patch, review the semantic diff, and save a copy with the digest observed at open time:

from aria_nbv.configs import ConfigDocument, WandbConfig

document = ConfigDocument.open(path, WandbConfig)
updated = document.validate_patch({"project": "aria-nbv-reporting"})
print(document.diff(updated))
receipt = document.save_copy(copy_path, expected_sha256=document.source_sha256)

Save-as-copy is the UI default. An in-place save uses the same optimistic concurrency check and therefore refuses to overwrite an externally changed file. Inline Python field docstrings own field meaning; Pydantic owns types and constraints; json_schema_extra["aria"] carries only structured edit, sensitivity, and theory-link policy.

The generated configuration API reference contains exact field and error contracts. Streamlit behavior belongs to aria_nbv.app; scientific report recipes belong to aria_nbv.reporting.

1.3 Responsibility boundaries

base.py owns validated configuration construction, TOML round-trips, target setup and singleton lifecycle. resolution.py delegates CLI/cache path policy to PathConfig; optimizable.py owns declarative search-space markers. authoring.py composes those contracts into the complete read, validate, diff and atomic-write transaction described above. These owners hide validation and serialization ordering from scientific modules; they do not own model equations or training lifecycle hooks.

from aria_nbv.configs.base import TargetConfig
from aria_nbv.configs.optimizable import optimizable_field
from aria_nbv.configs.resolution import resolve_config_toml_path

The existing aria_nbv.utils configuration imports remain typed compatibility entrypoints. They load their canonical owner lazily, preventing the config foundation’s console dependency from importing a partially initialized config class. New code imports the leaves above; the configs package root remains its existing lazy factory/authoring interface. Former utils.base_config, utils.config_paths and utils.optuna_optimizable leaves are retired after repository consumer migration.

Run tests/test_base_config_toml.py, tests/configs/test_config_authoring.py, tests/utils/test_optuna_optimizable.py and the public mypy contract from the package root. The import-order regression verifies canonical/root class identity and excludes training-stack imports; TOML and authoring tests preserve device serialization, setup behavior and optimistic write checks.

1.4 Attributes

Name	Description
ConfigValue	JSON/TOML-compatible value used by config descriptors and patches.

1.5 Classes

Name	Description
ConfigAuthoringError	Base error for parse, validation, policy, and write failures.
ConfigConflictError	Raised when a source file changed after it was inspected.
ConfigDiff	Canonical semantic changes for one authoring transaction.
ConfigDiffEntry	One semantic value change between the opened and validated draft.
ConfigDocument	Inspect, patch, diff, and atomically save one trusted TOML config.
ConfigFieldDescriptor	Schema and source documentation for one editable field.
ConfigWriteReceipt	Identity of one atomically promoted configuration file.
OptunaConfig	Configure an Optuna study used by `aria_nbv.lightning.AriaNBVExperimentConfig`.
PathConfig	Centralize filesystem ownership for package, data, and run artifacts.
WandbConfig	Wrapper around Lightning’s `WandbLogger`.

1.5.1 ConfigAuthoringError

configs.ConfigAuthoringError()

Base error for parse, validation, policy, and write failures.

1.5.2 ConfigConflictError

configs.ConfigConflictError()

Raised when a source file changed after it was inspected.

1.5.3 ConfigDiff

configs.ConfigDiff(entries)

Canonical semantic changes for one authoring transaction.

1.5.3.1 Attributes

Name	Description
entries	Changes sorted by dotted field path.
is_empty	Return whether the validated draft is semantically unchanged.

1.5.4 ConfigDiffEntry

configs.ConfigDiffEntry(path, before, after)

One semantic value change between the opened and validated draft.

1.5.4.1 Attributes

Name	Description
path	Dotted field path.
before	Original JSON-compatible value.
after	Validated draft value.

1.5.5 ConfigDocument

configs.ConfigDocument(path, model, source_text, document, config)

Inspect, patch, diff, and atomically save one trusted TOML config.

open and describe are metadata-only: they validate values and read Python source/schema metadata but never call setup_target. A patch is applied to a tomlkit tree so unrelated comments, ordering, and whitespace survive. save_copy uses the digest observed at open as a compare- and-swap token and writes through a same-directory temporary file.

1.5.5.1 Methods

Name	Description
open	Open and validate a TOML file without constructing its runtime target.
describe	Return schema-derived field descriptors without evaluating runtime targets.
validate_patch	Apply a partial mapping to the TOML tree and validate the complete config.
diff	Return semantic changes against the originally opened config.
save_copy	Atomically promote the validated draft after source-digest verification.

1.5.5.1.1 open

configs.ConfigDocument.open(path, model)

Open and validate a TOML file without constructing its runtime target.

1.5.5.1.2 describe

configs.ConfigDocument.describe()

Return schema-derived field descriptors without evaluating runtime targets.

1.5.5.1.3 validate_patch

configs.ConfigDocument.validate_patch(patch)

Apply a partial mapping to the TOML tree and validate the complete config.

The validated draft becomes the value subsequently reported by :meth:diff and written by :meth:save_copy. Locked fields reject changes before validation; sensitive fields may still be changed by trusted callers but presentation surfaces must conceal them.

1.5.5.1.4 diff

configs.ConfigDocument.diff(updated=None)

Return semantic changes against the originally opened config.

1.5.5.1.5 save_copy

configs.ConfigDocument.save_copy(destination, *, expected_sha256)

Atomically promote the validated draft after source-digest verification.

1.5.5.1.5.1 Parameters

Name	Type	Description	Default
destination	Path	New file or explicitly selected overwrite target.	required
expected_sha256	str	Digest returned when this document was opened.	required

1.5.5.1.5.2 Raises

Name	Type	Description
	ConfigConflictError	If the opened source changed or the supplied digest is not the one observed by this document.

1.5.6 ConfigFieldDescriptor

configs.ConfigFieldDescriptor(
    path,
    title,
    annotation,
    documentation,
    required,
    default,
    choices,
    allows_none,
    minimum,
    maximum,
    editable,
    sensitive,
    theory_ids,
)

Schema and source documentation for one editable field.

1.5.6.1 Attributes

Name	Type	Description
path	str	Dotted path within the validated configuration tree.
title	str	Human-readable schema title.
annotation	str	Stable textual form of the Python annotation.
documentation	str \| None	Inline field docstring from the nearest source owner.
required	bool	Whether the validated model requires the field.
default	ConfigValue	JSON-compatible default, or `None` when absent.
choices	tuple[ConfigValue, …]	Closed enum or `Literal` choices, if any.
allows_none	bool	Whether omission represents an explicit optional value.
minimum	float \| int \| None	Inclusive or exclusive lower numeric bound when declared.
maximum	float \| int \| None	Inclusive or exclusive upper numeric bound when declared.
editable	bool	Whether trusted authoring surfaces may change this field.
sensitive	bool	Whether presentation surfaces must conceal the value.
theory_ids	tuple[str, …]	Canonical Typst-derived theory identifiers relevant to the field.

1.5.7 ConfigWriteReceipt

configs.ConfigWriteReceipt(path, sha256, previous_sha256, changed)

Identity of one atomically promoted configuration file.

1.5.7.1 Attributes

Name	Description
path	Absolute destination path.
sha256	SHA-256 digest of the exact written TOML bytes.
previous_sha256	Digest of a replaced destination, when one existed.
changed	Whether destination bytes differed from the promoted bytes.

1.5.8 OptunaConfig

configs.OptunaConfig()

Configure an Optuna study used by aria_nbv.lightning.AriaNBVExperimentConfig.

1.5.8.1 Attributes

Name	Description
study_name	Study name (used for Optuna storage and W&B grouping).
direction	Optuna optimization direction.
n_trials	Number of Optuna trials to run.
monitor	Metric key to optimize (must be present in the Lightning trainer metrics).
load_if_exists	Re-use an existing study with the same name when True.
sampler	Optuna sampler choice.
pruner	Optuna pruner choice.
suggested_params	Latest trial suggestions applied to the config tree (W&B friendly).

1.5.8.2 Methods

Name	Description
setup_target	Create or resume the configured study in the project SQLite store.
setup_optimizables	Apply Optimizable hints embedded in the config tree.
log_to_wandb	Send the most recent suggestions to W&B.
get_pruning_callback	Return a PyTorch Lightning pruning callback for the configured monitor.

1.5.8.2.1 setup_target

configs.OptunaConfig.setup_target()

Create or resume the configured study in the project SQLite store.

1.5.8.2.2 setup_optimizables

configs.OptunaConfig.setup_optimizables(
    experiment_config,
    trial,
    *,
    console=None,
)

Apply Optimizable hints embedded in the config tree.

1.5.8.2.3 log_to_wandb

configs.OptunaConfig.log_to_wandb()

Send the most recent suggestions to W&B.

1.5.8.2.4 get_pruning_callback

configs.OptunaConfig.get_pruning_callback(trial)

Return a PyTorch Lightning pruning callback for the configured monitor.

1.5.9 PathConfig

configs.PathConfig(**kwargs)

Centralize filesystem ownership for package, data, and run artifacts.

Reinitializing the singleton with a different root rebases fields that still equal their old root-derived defaults while preserving explicit overrides. Paths exposed by this config are absolute after validation.

1.5.9.1 Attributes

Name	Description
root	Absolute repository root used to resolve relative configuration paths.
data_root	Root directory for all data (downloaded datasets, meshes, etc.).
data_root_massive	Optional root directory for storing further large datasets, caches or artifacts.
checkpoints	Directory used by Lightning checkpoints.
external_checkpoints	Optional directory containing checkpoints produced outside this project.
wandb	Directory used by Weights & Biases for local run artifacts.
optuna	Directory used by Optuna for local study storage (SQLite).
configs_dir	Directory containing exported experiment/configuration files (TOML, etc.).
url_dir	Directory containing ASE download URL JSON files.
metadata_cache	Path to cached ASE metadata JSON.
offline_cache_dir	VIN offline-store directory, resolved below `data_root_massive` when set.
ase_meshes	Directory for downloaded ASE ground truth meshes.
processed_meshes	Directory for cropped/simplified meshes persisted for reuse.
external_dir	Directory containing pinned external source checkouts such as EFM3D.

1.5.9.2 Methods

Name	Description
resolve_checkpoint_path	Resolve a checkpoint path relative to the checkpoints directory.
resolve_external_checkpoint_path	Resolve and validate a checkpoint under `external_checkpoints`.
resolve_mesh_path	Resolve path to GT mesh for a scene.
resolve_processed_mesh_path	Resolve path for a processed (cropped/simplified) mesh artifact.
resolve_atek_data_dir	Resolve path to ATEK data directory for a config.
get_atek_source_path	Get path to vendored ATEK source.
get_atek_url_json_path	Get path to ATEK download URLs JSON.
resolve_under_root	Resolve a user-provided path relative to the project root.
resolve_cache_artifact_dir	Resolve a cache or store directory against the configured data roots.
resolve_run_dir	Resolve a run output directory and ensure it exists.
resolve_artifact_path	Resolve an artifact file path under the project root.
resolve_config_toml_path	Resolve a TOML experiment config path.
resolve_optuna_study_uri	Resolve a SQLite Optuna storage URI for a given study name.

1.5.9.2.1 resolve_checkpoint_path

configs.PathConfig.resolve_checkpoint_path(path)

Resolve a checkpoint path relative to the checkpoints directory.

1.5.9.2.1.1 Parameters

Name	Type	Description	Default
path	str \| Path \| None	Checkpoint path (absolute, relative, or None).	required

1.5.9.2.1.2 Returns

Name	Type	Description
	Path \| None	Resolved absolute path, or None if input is None/empty.

1.5.9.2.1.3 Raises

Name	Type	Description
	FileNotFoundError	If the resolved path does not exist.

1.5.9.2.2 resolve_external_checkpoint_path

configs.PathConfig.resolve_external_checkpoint_path(path)

Resolve and validate a checkpoint under external_checkpoints.

Absolute paths are accepted unchanged. Relative paths are interpreted below the configured external-checkpoint root and must already exist.

1.5.9.2.3 resolve_mesh_path

configs.PathConfig.resolve_mesh_path(scene_id)

Resolve path to GT mesh for a scene.

1.5.9.2.3.1 Parameters

Name	Type	Description	Default
scene_id	str	Scene identifier (e.g., “82832”)	required

1.5.9.2.3.2 Returns

Name	Type	Description
	Path	Path to mesh file (may not exist yet)

1.5.9.2.4 resolve_processed_mesh_path

configs.PathConfig.resolve_processed_mesh_path(
    scene_id,
    simplification_ratio,
    is_crop,
    spec_hash,
)

Resolve path for a processed (cropped/simplified) mesh artifact.

1.5.9.2.4.1 Parameters

Name	Type	Description	Default
scene_id	str	ASE scene identifier.	required
simplification_ratio	float	Mesh simplification ratio encoded in the filename.	required
is_crop	bool	Whether the processed mesh is a cropped artifact.	required
spec_hash	str	Short hash of the processing specification.	required

1.5.9.2.4.2 Returns

Name	Type	Description
	Path	Destination path where the processed mesh should be stored.

1.5.9.2.5 resolve_atek_data_dir

configs.PathConfig.resolve_atek_data_dir(config_name='efm')

Resolve path to ATEK data directory for a config.

1.5.9.2.5.1 Parameters

Name	Type	Description	Default
config_name	str	ATEK config name (e.g., “efm”, “efm_eval”)	`'efm'`

1.5.9.2.5.2 Returns

Name	Type	Description
	Path	Path to ATEK data directory

1.5.9.2.6 get_atek_source_path

configs.PathConfig.get_atek_source_path()

Get path to vendored ATEK source.

1.5.9.2.6.1 Returns

Name	Type	Description
	Path	Path to external/ATEK directory

1.5.9.2.6.2 Raises

Name	Type	Description
	FileNotFoundError	If ATEK is not found

1.5.9.2.7 get_atek_url_json_path

configs.PathConfig.get_atek_url_json_path(
    json_filename='AriaSyntheticEnvironment_ATEK_download_urls.json',
)

Get path to ATEK download URLs JSON.

1.5.9.2.7.1 Parameters

Name	Type	Description	Default
json_filename	str	Name of the ATEK URL JSON file.	`'AriaSyntheticEnvironment_ATEK_download_urls.json'`

1.5.9.2.7.2 Returns

Name	Type	Description
	Path	Path to the ATEK URL JSON file.

1.5.9.2.8 resolve_under_root

configs.PathConfig.resolve_under_root(path, *, base_dir=None)

Resolve a user-provided path relative to the project root.

1.5.9.2.8.1 Parameters

Name	Type	Description	Default
path	str \| Path	Path to resolve (absolute or relative).	required
base_dir	Path \| None	Optional base directory to resolve relative paths against. Defaults to `root`.	`None`

1.5.9.2.8.2 Returns

Name	Type	Description
	Path	Absolute, expanded, resolved path.

1.5.9.2.9 resolve_cache_artifact_dir

configs.PathConfig.resolve_cache_artifact_dir(path)

Resolve a cache or store directory against the configured data roots.

Relative paths default to offline_cache_dir when available and otherwise fall back to data_root. Paths that already start with the data-root or offline-cache root name are instead interpreted relative to root so callers can still pass repo-root-relative paths such as offline_cache/foo.

1.5.9.2.10 resolve_run_dir

configs.PathConfig.resolve_run_dir(out_dir)

Resolve a run output directory and ensure it exists.

1.5.9.2.11 resolve_artifact_path

configs.PathConfig.resolve_artifact_path(
    path,
    *,
    expected_suffix=None,
    create_parent=True,
)

Resolve an artifact file path under the project root.

1.5.9.2.11.1 Parameters

Name	Type	Description	Default
path	str \| Path	Path to resolve (absolute or relative).	required
expected_suffix	str \| None	Optional required suffix (e.g. “.json”, “.pt”, “.toml”).	`None`
create_parent	bool	Create the parent directory when True.	`True`

1.5.9.2.11.2 Returns

Name	Type	Description
	Path	Absolute, expanded, resolved path.

1.5.9.2.12 resolve_config_toml_path

configs.PathConfig.resolve_config_toml_path(path, *, must_exist=True)

Resolve a TOML experiment config path.

Relative paths are resolved as: - bare filenames (no parent) are interpreted as under configs_dir - other relative paths are interpreted as under root

1.5.9.2.13 resolve_optuna_study_uri

configs.PathConfig.resolve_optuna_study_uri(study_name)

Resolve a SQLite Optuna storage URI for a given study name.

1.5.10 WandbConfig

configs.WandbConfig()

Wrapper around Lightning’s WandbLogger.

1.5.10.1 References

https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html

1.5.10.2 Attributes

Name	Description
target_type	Return Lightning’s W&B logger class for config-factory inspection.
name	Optional display name for the run.
project	Destination W&B project name.
entity	Optional W&B user or team entity.
run_id	Stable run id used for creation or resumption.
resume	Policy for an already existing `run_id`.
anonymous	Optional W&B anonymous-mode override.
offline	Write events locally without contacting the W&B service.
log_model	Lightning checkpoint-to-W&B artifact logging policy.
checkpoint_name	Optional name for uploaded checkpoint artifacts.
tags	Optional run tags used for filtering and comparison.
group	Optional group shared by related runs or trials.
job_type	Optional role label such as training, evaluation, or sweep.
prefix	Optional namespace prepended to logged metric keys.

1.5.10.3 Methods

Name	Description
init_kwargs	Return the shared W&B run-identity arguments for non-Lightning reporters.
setup_target	Instantiate a logger rooted in `PathConfig`’s W&B directory.

1.5.10.3.1 init_kwargs

configs.WandbConfig.init_kwargs()

Return the shared W&B run-identity arguments for non-Lightning reporters.

Lightning-only checkpoint and metric-prefix options deliberately remain exclusive to :meth:setup_target. This keeps small reporting tools on the same project, identity, grouping, and offline-mode contract without pretending that they are Lightning loggers.

1.5.10.3.2 setup_target

configs.WandbConfig.setup_target(**kwargs)

Instantiate a logger rooted in PathConfig’s W&B directory.

1.6 Functions

Name	Description
describe_config_model	Return schema/documentation descriptors for an in-memory config model.

1.6.1 describe_config_model

configs.describe_config_model(model)

Return schema/documentation descriptors for an in-memory config model.

# configs { #aria_nbv.configs } `configs` Lazy stable imports for ARIA-NBV configuration factories. Loading :class:`PathConfig` must not import optional Optuna, W&B, TorchMetrics, or Lightning runtime stacks. The public names remain available through module attribute lookup and are imported only when requested.  ## Package guide `aria_nbv.configs` exposes trusted configuration families and a safe authoring transaction around their existing `BaseConfig` validation. It does not import runtime targets merely to inspect a file, and it never discovers model classes from strings stored in TOML. ```{mermaid} sequenceDiagram participant U as User participant A as Streamlit config workspace participant D as ConfigDocument participant P as Pydantic model participant F as TOML file U->>A: Select trusted config A->>D: Open path and root model D->>P: Validate parsed values P-->>A: Values, schema, docs, policies U->>A: Edit draft and submit form A->>D: Validate patch D->>P: Validate complete config tree P-->>A: Valid config or located errors U->>A: Save copy A->>D: Save with expected SHA-256 D->>F: Atomic comment-preserving write F-->>A: Write receipt and new digest ``` ## Workflow Open a trusted path together with its root model, inspect field descriptors, validate a partial patch, review the semantic diff, and save a copy with the digest observed at open time: ```python from aria_nbv.configs import ConfigDocument, WandbConfig document = ConfigDocument.open(path, WandbConfig) updated = document.validate_patch({"project": "aria-nbv-reporting"}) print(document.diff(updated)) receipt = document.save_copy(copy_path, expected_sha256=document.source_sha256) ``` Save-as-copy is the UI default. An in-place save uses the same optimistic concurrency check and therefore refuses to overwrite an externally changed file. Inline Python field docstrings own field meaning; Pydantic owns types and constraints; `json_schema_extra["aria"]` carries only structured edit, sensitivity, and theory-link policy. The generated [configuration API reference](configs.qmd) contains exact field and error contracts. Streamlit behavior belongs to `aria_nbv.app`; scientific report recipes belong to `aria_nbv.reporting`. ## Responsibility boundaries `base.py` owns validated configuration construction, TOML round-trips, target setup and singleton lifecycle. `resolution.py` delegates CLI/cache path policy to `PathConfig`; `optimizable.py` owns declarative search-space markers. `authoring.py` composes those contracts into the complete read, validate, diff and atomic-write transaction described above. These owners hide validation and serialization ordering from scientific modules; they do not own model equations or training lifecycle hooks. ```python from aria_nbv.configs.base import TargetConfig from aria_nbv.configs.optimizable import optimizable_field from aria_nbv.configs.resolution import resolve_config_toml_path ``` The existing `aria_nbv.utils` configuration imports remain typed compatibility entrypoints. They load their canonical owner lazily, preventing the config foundation's console dependency from importing a partially initialized config class. New code imports the leaves above; the configs package root remains its existing lazy factory/authoring interface. Former `utils.base_config`, `utils.config_paths` and `utils.optuna_optimizable` leaves are retired after repository consumer migration. Run `tests/test_base_config_toml.py`, `tests/configs/test_config_authoring.py`, `tests/utils/test_optuna_optimizable.py` and the public mypy contract from the package root. The import-order regression verifies canonical/root class identity and excludes training-stack imports; TOML and authoring tests preserve device serialization, setup behavior and optimistic write checks.  ## Attributes | Name | Description | | --- | --- | | [ConfigValue](#aria_nbv.configs.ConfigValue) | JSON/TOML-compatible value used by config descriptors and patches. | ## Classes | Name | Description | | --- | --- | | [ConfigAuthoringError](#aria_nbv.configs.ConfigAuthoringError) | Base error for parse, validation, policy, and write failures. | | [ConfigConflictError](#aria_nbv.configs.ConfigConflictError) | Raised when a source file changed after it was inspected. | | [ConfigDiff](#aria_nbv.configs.ConfigDiff) | Canonical semantic changes for one authoring transaction. | | [ConfigDiffEntry](#aria_nbv.configs.ConfigDiffEntry) | One semantic value change between the opened and validated draft. | | [ConfigDocument](#aria_nbv.configs.ConfigDocument) | Inspect, patch, diff, and atomically save one trusted TOML config. | | [ConfigFieldDescriptor](#aria_nbv.configs.ConfigFieldDescriptor) | Schema and source documentation for one editable field. | | [ConfigWriteReceipt](#aria_nbv.configs.ConfigWriteReceipt) | Identity of one atomically promoted configuration file. | | [OptunaConfig](#aria_nbv.configs.OptunaConfig) | Configure an Optuna study used by :class:`aria_nbv.lightning.AriaNBVExperimentConfig`. | | [PathConfig](#aria_nbv.configs.PathConfig) | Centralize filesystem ownership for package, data, and run artifacts. | | [WandbConfig](#aria_nbv.configs.WandbConfig) | Wrapper around Lightning's `WandbLogger`. | ### ConfigAuthoringError { #aria_nbv.configs.ConfigAuthoringError } ```python configs.ConfigAuthoringError() ``` Base error for parse, validation, policy, and write failures. ### ConfigConflictError { #aria_nbv.configs.ConfigConflictError } ```python configs.ConfigConflictError() ``` Raised when a source file changed after it was inspected. ### ConfigDiff { #aria_nbv.configs.ConfigDiff } ```python configs.ConfigDiff(entries) ``` Canonical semantic changes for one authoring transaction. #### Attributes | Name | Description | | --- | --- | | [entries](#aria_nbv.configs.ConfigDiff.entries) | Changes sorted by dotted field path. | | [is_empty](#aria_nbv.configs.ConfigDiff.is_empty) | Return whether the validated draft is semantically unchanged. | ### ConfigDiffEntry { #aria_nbv.configs.ConfigDiffEntry } ```python configs.ConfigDiffEntry(path, before, after) ``` One semantic value change between the opened and validated draft. #### Attributes | Name | Description | | --- | --- | | [path](#aria_nbv.configs.ConfigDiffEntry.path) | Dotted field path. | | [before](#aria_nbv.configs.ConfigDiffEntry.before) | Original JSON-compatible value. | | [after](#aria_nbv.configs.ConfigDiffEntry.after) | Validated draft value. | ### ConfigDocument { #aria_nbv.configs.ConfigDocument } ```python configs.ConfigDocument(path, model, source_text, document, config) ``` Inspect, patch, diff, and atomically save one trusted TOML config. ``open`` and ``describe`` are metadata-only: they validate values and read Python source/schema metadata but never call ``setup_target``. A patch is applied to a tomlkit tree so unrelated comments, ordering, and whitespace survive. ``save_copy`` uses the digest observed at ``open`` as a compare- and-swap token and writes through a same-directory temporary file. #### Methods | Name | Description | | --- | --- | | [open](#aria_nbv.configs.ConfigDocument.open) | Open and validate a TOML file without constructing its runtime target. | | [describe](#aria_nbv.configs.ConfigDocument.describe) | Return schema-derived field descriptors without evaluating runtime targets. | | [validate_patch](#aria_nbv.configs.ConfigDocument.validate_patch) | Apply a partial mapping to the TOML tree and validate the complete config. | | [diff](#aria_nbv.configs.ConfigDocument.diff) | Return semantic changes against the originally opened config. | | [save_copy](#aria_nbv.configs.ConfigDocument.save_copy) | Atomically promote the validated draft after source-digest verification. | ##### open { #aria_nbv.configs.ConfigDocument.open } ```python configs.ConfigDocument.open(path, model) ``` Open and validate a TOML file without constructing its runtime target. ##### describe { #aria_nbv.configs.ConfigDocument.describe } ```python configs.ConfigDocument.describe() ``` Return schema-derived field descriptors without evaluating runtime targets. ##### validate_patch { #aria_nbv.configs.ConfigDocument.validate_patch } ```python configs.ConfigDocument.validate_patch(patch) ``` Apply a partial mapping to the TOML tree and validate the complete config. The validated draft becomes the value subsequently reported by :meth:`diff` and written by :meth:`save_copy`. Locked fields reject changes before validation; sensitive fields may still be changed by trusted callers but presentation surfaces must conceal them. ##### diff { #aria_nbv.configs.ConfigDocument.diff } ```python configs.ConfigDocument.diff(updated=None) ``` Return semantic changes against the originally opened config. ##### save_copy { #aria_nbv.configs.ConfigDocument.save_copy } ```python configs.ConfigDocument.save_copy(destination, *, expected_sha256) ``` Atomically promote the validated draft after source-digest verification. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |-----------------|------------------------|---------------------------------------------------|------------| | destination | [Path](`pathlib.Path`) | New file or explicitly selected overwrite target. | _required_ | | expected_sha256 | [str](`str`) | Digest returned when this document was opened. | _required_ | ###### Raises {.doc-section .doc-section-raises} | Name | Type | Description | |--------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | | [ConfigConflictError](`aria_nbv.configs.authoring.ConfigConflictError`) | If the opened source changed or the supplied digest is not the one observed by this document. | ### ConfigFieldDescriptor { #aria_nbv.configs.ConfigFieldDescriptor } ```python configs.ConfigFieldDescriptor( path, title, annotation, documentation, required, default, choices, allows_none, minimum, maximum, editable, sensitive, theory_ids, ) ``` Schema and source documentation for one editable field. #### Attributes {.doc-section .doc-section-attributes} | Name | Type | Description | |---------------|----------------------------------------------------------------------------------|-------------------------------------------------------------------| | path | [str](`str`) | Dotted path within the validated configuration tree. | | title | [str](`str`) | Human-readable schema title. | | annotation | [str](`str`) | Stable textual form of the Python annotation. | | documentation | [str](`str`) \| None | Inline field docstring from the nearest source owner. | | required | [bool](`bool`) | Whether the validated model requires the field. | | default | [ConfigValue](`aria_nbv.configs.authoring.ConfigValue`) | JSON-compatible default, or ``None`` when absent. | | choices | [tuple](`tuple`)\[[ConfigValue](`aria_nbv.configs.authoring.ConfigValue`), ...\] | Closed enum or ``Literal`` choices, if any. | | allows_none | [bool](`bool`) | Whether omission represents an explicit optional value. | | minimum | [float](`float`) \| [int](`int`) \| None | Inclusive or exclusive lower numeric bound when declared. | | maximum | [float](`float`) \| [int](`int`) \| None | Inclusive or exclusive upper numeric bound when declared. | | editable | [bool](`bool`) | Whether trusted authoring surfaces may change this field. | | sensitive | [bool](`bool`) | Whether presentation surfaces must conceal the value. | | theory_ids | [tuple](`tuple`)\[[str](`str`), ...\] | Canonical Typst-derived theory identifiers relevant to the field. | ### ConfigWriteReceipt { #aria_nbv.configs.ConfigWriteReceipt } ```python configs.ConfigWriteReceipt(path, sha256, previous_sha256, changed) ``` Identity of one atomically promoted configuration file. #### Attributes | Name | Description | | --- | --- | | [path](#aria_nbv.configs.ConfigWriteReceipt.path) | Absolute destination path. | | [sha256](#aria_nbv.configs.ConfigWriteReceipt.sha256) | SHA-256 digest of the exact written TOML bytes. | | [previous_sha256](#aria_nbv.configs.ConfigWriteReceipt.previous_sha256) | Digest of a replaced destination, when one existed. | | [changed](#aria_nbv.configs.ConfigWriteReceipt.changed) | Whether destination bytes differed from the promoted bytes. | ### OptunaConfig { #aria_nbv.configs.OptunaConfig } ```python configs.OptunaConfig() ``` Configure an Optuna study used by :class:`aria_nbv.lightning.AriaNBVExperimentConfig`. #### Attributes | Name | Description | | --- | --- | | [study_name](#aria_nbv.configs.OptunaConfig.study_name) | Study name (used for Optuna storage and W&B grouping). | | [direction](#aria_nbv.configs.OptunaConfig.direction) | Optuna optimization direction. | | [n_trials](#aria_nbv.configs.OptunaConfig.n_trials) | Number of Optuna trials to run. | | [monitor](#aria_nbv.configs.OptunaConfig.monitor) | Metric key to optimize (must be present in the Lightning trainer metrics). | | [load_if_exists](#aria_nbv.configs.OptunaConfig.load_if_exists) | Re-use an existing study with the same name when True. | | [sampler](#aria_nbv.configs.OptunaConfig.sampler) | Optuna sampler choice. | | [pruner](#aria_nbv.configs.OptunaConfig.pruner) | Optuna pruner choice. | | [suggested_params](#aria_nbv.configs.OptunaConfig.suggested_params) | Latest trial suggestions applied to the config tree (W&B friendly). | #### Methods | Name | Description | | --- | --- | | [setup_target](#aria_nbv.configs.OptunaConfig.setup_target) | Create or resume the configured study in the project SQLite store. | | [setup_optimizables](#aria_nbv.configs.OptunaConfig.setup_optimizables) | Apply Optimizable hints embedded in the config tree. | | [log_to_wandb](#aria_nbv.configs.OptunaConfig.log_to_wandb) | Send the most recent suggestions to W&B. | | [get_pruning_callback](#aria_nbv.configs.OptunaConfig.get_pruning_callback) | Return a PyTorch Lightning pruning callback for the configured monitor. | ##### setup_target { #aria_nbv.configs.OptunaConfig.setup_target } ```python configs.OptunaConfig.setup_target() ``` Create or resume the configured study in the project SQLite store. ##### setup_optimizables { #aria_nbv.configs.OptunaConfig.setup_optimizables } ```python configs.OptunaConfig.setup_optimizables( experiment_config, trial, *, console=None, ) ``` Apply Optimizable hints embedded in the config tree. ##### log_to_wandb { #aria_nbv.configs.OptunaConfig.log_to_wandb } ```python configs.OptunaConfig.log_to_wandb() ``` Send the most recent suggestions to W&B. ##### get_pruning_callback { #aria_nbv.configs.OptunaConfig.get_pruning_callback } ```python configs.OptunaConfig.get_pruning_callback(trial) ``` Return a PyTorch Lightning pruning callback for the configured monitor. ### PathConfig { #aria_nbv.configs.PathConfig } ```python configs.PathConfig(**kwargs) ``` Centralize filesystem ownership for package, data, and run artifacts. Reinitializing the singleton with a different `root` rebases fields that still equal their old root-derived defaults while preserving explicit overrides. Paths exposed by this config are absolute after validation. #### Attributes | Name | Description | | --- | --- | | [root](#aria_nbv.configs.PathConfig.root) | Absolute repository root used to resolve relative configuration paths. | | [data_root](#aria_nbv.configs.PathConfig.data_root) | Root directory for all data (downloaded datasets, meshes, etc.). | | [data_root_massive](#aria_nbv.configs.PathConfig.data_root_massive) | Optional root directory for storing further large datasets, caches or artifacts. | | [checkpoints](#aria_nbv.configs.PathConfig.checkpoints) | Directory used by Lightning checkpoints. | | [external_checkpoints](#aria_nbv.configs.PathConfig.external_checkpoints) | Optional directory containing checkpoints produced outside this project. | | [wandb](#aria_nbv.configs.PathConfig.wandb) | Directory used by Weights & Biases for local run artifacts. | | [optuna](#aria_nbv.configs.PathConfig.optuna) | Directory used by Optuna for local study storage (SQLite). | | [configs_dir](#aria_nbv.configs.PathConfig.configs_dir) | Directory containing exported experiment/configuration files (TOML, etc.). | | [url_dir](#aria_nbv.configs.PathConfig.url_dir) | Directory containing ASE download URL JSON files. | | [metadata_cache](#aria_nbv.configs.PathConfig.metadata_cache) | Path to cached ASE metadata JSON. | | [offline_cache_dir](#aria_nbv.configs.PathConfig.offline_cache_dir) | VIN offline-store directory, resolved below `data_root_massive` when set. | | [ase_meshes](#aria_nbv.configs.PathConfig.ase_meshes) | Directory for downloaded ASE ground truth meshes. | | [processed_meshes](#aria_nbv.configs.PathConfig.processed_meshes) | Directory for cropped/simplified meshes persisted for reuse. | | [external_dir](#aria_nbv.configs.PathConfig.external_dir) | Directory containing pinned external source checkouts such as EFM3D. | #### Methods | Name | Description | | --- | --- | | [resolve_checkpoint_path](#aria_nbv.configs.PathConfig.resolve_checkpoint_path) | Resolve a checkpoint path relative to the checkpoints directory. | | [resolve_external_checkpoint_path](#aria_nbv.configs.PathConfig.resolve_external_checkpoint_path) | Resolve and validate a checkpoint under `external_checkpoints`. | | [resolve_mesh_path](#aria_nbv.configs.PathConfig.resolve_mesh_path) | Resolve path to GT mesh for a scene. | | [resolve_processed_mesh_path](#aria_nbv.configs.PathConfig.resolve_processed_mesh_path) | Resolve path for a processed (cropped/simplified) mesh artifact. | | [resolve_atek_data_dir](#aria_nbv.configs.PathConfig.resolve_atek_data_dir) | Resolve path to ATEK data directory for a config. | | [get_atek_source_path](#aria_nbv.configs.PathConfig.get_atek_source_path) | Get path to vendored ATEK source. | | [get_atek_url_json_path](#aria_nbv.configs.PathConfig.get_atek_url_json_path) | Get path to ATEK download URLs JSON. | | [resolve_under_root](#aria_nbv.configs.PathConfig.resolve_under_root) | Resolve a user-provided path relative to the project root. | | [resolve_cache_artifact_dir](#aria_nbv.configs.PathConfig.resolve_cache_artifact_dir) | Resolve a cache or store directory against the configured data roots. | | [resolve_run_dir](#aria_nbv.configs.PathConfig.resolve_run_dir) | Resolve a run output directory and ensure it exists. | | [resolve_artifact_path](#aria_nbv.configs.PathConfig.resolve_artifact_path) | Resolve an artifact file path under the project root. | | [resolve_config_toml_path](#aria_nbv.configs.PathConfig.resolve_config_toml_path) | Resolve a TOML experiment config path. | | [resolve_optuna_study_uri](#aria_nbv.configs.PathConfig.resolve_optuna_study_uri) | Resolve a SQLite Optuna storage URI for a given study name. | ##### resolve_checkpoint_path { #aria_nbv.configs.PathConfig.resolve_checkpoint_path } ```python configs.PathConfig.resolve_checkpoint_path(path) ``` Resolve a checkpoint path relative to the checkpoints directory. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |--------|------------------------------------------------|------------------------------------------------|------------| | path | [str](`str`) \| [Path](`pathlib.Path`) \| None | Checkpoint path (absolute, relative, or None). | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------------------------|---------------------------------------------------------| | | [Path](`pathlib.Path`) \| None | Resolved absolute path, or None if input is None/empty. | ###### Raises {.doc-section .doc-section-raises} | Name | Type | Description | |--------|------------------------------------------|--------------------------------------| | | [FileNotFoundError](`FileNotFoundError`) | If the resolved path does not exist. | ##### resolve_external_checkpoint_path { #aria_nbv.configs.PathConfig.resolve_external_checkpoint_path } ```python configs.PathConfig.resolve_external_checkpoint_path(path) ``` Resolve and validate a checkpoint under `external_checkpoints`. Absolute paths are accepted unchanged. Relative paths are interpreted below the configured external-checkpoint root and must already exist. ##### resolve_mesh_path { #aria_nbv.configs.PathConfig.resolve_mesh_path } ```python configs.PathConfig.resolve_mesh_path(scene_id) ``` Resolve path to GT mesh for a scene. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |----------|--------------|----------------------------------|------------| | scene_id | [str](`str`) | Scene identifier (e.g., "82832") | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|---------------------------------------| | | [Path](`pathlib.Path`) | Path to mesh file (may not exist yet) | ##### resolve_processed_mesh_path { #aria_nbv.configs.PathConfig.resolve_processed_mesh_path } ```python configs.PathConfig.resolve_processed_mesh_path( scene_id, simplification_ratio, is_crop, spec_hash, ) ``` Resolve path for a processed (cropped/simplified) mesh artifact. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |----------------------|------------------|----------------------------------------------------|------------| | scene_id | [str](`str`) | ASE scene identifier. | _required_ | | simplification_ratio | [float](`float`) | Mesh simplification ratio encoded in the filename. | _required_ | | is_crop | [bool](`bool`) | Whether the processed mesh is a cropped artifact. | _required_ | | spec_hash | [str](`str`) | Short hash of the processing specification. | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|-------------------------------------------------------------| | | [Path](`pathlib.Path`) | Destination path where the processed mesh should be stored. | ##### resolve_atek_data_dir { #aria_nbv.configs.PathConfig.resolve_atek_data_dir } ```python configs.PathConfig.resolve_atek_data_dir(config_name='efm') ``` Resolve path to ATEK data directory for a config. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |-------------|--------------|--------------------------------------------|-----------| | config_name | [str](`str`) | ATEK config name (e.g., "efm", "efm_eval") | `'efm'` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|-----------------------------| | | [Path](`pathlib.Path`) | Path to ATEK data directory | ##### get_atek_source_path { #aria_nbv.configs.PathConfig.get_atek_source_path } ```python configs.PathConfig.get_atek_source_path() ``` Get path to vendored ATEK source. ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|---------------------------------| | | [Path](`pathlib.Path`) | Path to external/ATEK directory | ###### Raises {.doc-section .doc-section-raises} | Name | Type | Description | |--------|------------------------------------------|----------------------| | | [FileNotFoundError](`FileNotFoundError`) | If ATEK is not found | ##### get_atek_url_json_path { #aria_nbv.configs.PathConfig.get_atek_url_json_path } ```python configs.PathConfig.get_atek_url_json_path( json_filename='AriaSyntheticEnvironment_ATEK_download_urls.json', ) ``` Get path to ATEK download URLs JSON. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |---------------|--------------|---------------------------------|------------------------------------------------------| | json_filename | [str](`str`) | Name of the ATEK URL JSON file. | `'AriaSyntheticEnvironment_ATEK_download_urls.json'` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|---------------------------------| | | [Path](`pathlib.Path`) | Path to the ATEK URL JSON file. | ##### resolve_under_root { #aria_nbv.configs.PathConfig.resolve_under_root } ```python configs.PathConfig.resolve_under_root(path, *, base_dir=None) ``` Resolve a user-provided path relative to the project root. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |----------|----------------------------------------|--------------------------------------------------------------------------------|------------| | path | [str](`str`) \| [Path](`pathlib.Path`) | Path to resolve (absolute or relative). | _required_ | | base_dir | [Path](`pathlib.Path`) \| None | Optional base directory to resolve relative paths against. Defaults to `root`. | `None` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|------------------------------------| | | [Path](`pathlib.Path`) | Absolute, expanded, resolved path. | ##### resolve_cache_artifact_dir { #aria_nbv.configs.PathConfig.resolve_cache_artifact_dir } ```python configs.PathConfig.resolve_cache_artifact_dir(path) ``` Resolve a cache or store directory against the configured data roots. Relative paths default to `offline_cache_dir` when available and otherwise fall back to `data_root`. Paths that already start with the data-root or offline-cache root name are instead interpreted relative to `root` so callers can still pass repo-root-relative paths such as ``offline_cache/foo``. ##### resolve_run_dir { #aria_nbv.configs.PathConfig.resolve_run_dir } ```python configs.PathConfig.resolve_run_dir(out_dir) ``` Resolve a run output directory and ensure it exists. ##### resolve_artifact_path { #aria_nbv.configs.PathConfig.resolve_artifact_path } ```python configs.PathConfig.resolve_artifact_path( path, *, expected_suffix=None, create_parent=True, ) ``` Resolve an artifact file path under the project root. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |-----------------|----------------------------------------|----------------------------------------------------------|------------| | path | [str](`str`) \| [Path](`pathlib.Path`) | Path to resolve (absolute or relative). | _required_ | | expected_suffix | [str](`str`) \| None | Optional required suffix (e.g. ".json", ".pt", ".toml"). | `None` | | create_parent | [bool](`bool`) | Create the parent directory when True. | `True` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------|------------------------------------| | | [Path](`pathlib.Path`) | Absolute, expanded, resolved path. | ##### resolve_config_toml_path { #aria_nbv.configs.PathConfig.resolve_config_toml_path } ```python configs.PathConfig.resolve_config_toml_path(path, *, must_exist=True) ``` Resolve a TOML experiment config path. Relative paths are resolved as: - bare filenames (no parent) are interpreted as under `configs_dir` - other relative paths are interpreted as under `root` ##### resolve_optuna_study_uri { #aria_nbv.configs.PathConfig.resolve_optuna_study_uri } ```python configs.PathConfig.resolve_optuna_study_uri(study_name) ``` Resolve a SQLite Optuna storage URI for a given study name. ### WandbConfig { #aria_nbv.configs.WandbConfig } ```python configs.WandbConfig() ``` Wrapper around Lightning's `WandbLogger`. #### References {.doc-section .doc-section-references} https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html #### Attributes | Name | Description | | --- | --- | | [target_type](#aria_nbv.configs.WandbConfig.target_type) | Return Lightning's W&B logger class for config-factory inspection. | | [name](#aria_nbv.configs.WandbConfig.name) | Optional display name for the run. | | [project](#aria_nbv.configs.WandbConfig.project) | Destination W&B project name. | | [entity](#aria_nbv.configs.WandbConfig.entity) | Optional W&B user or team entity. | | [run_id](#aria_nbv.configs.WandbConfig.run_id) | Stable run id used for creation or resumption. | | [resume](#aria_nbv.configs.WandbConfig.resume) | Policy for an already existing `run_id`. | | [anonymous](#aria_nbv.configs.WandbConfig.anonymous) | Optional W&B anonymous-mode override. | | [offline](#aria_nbv.configs.WandbConfig.offline) | Write events locally without contacting the W&B service. | | [log_model](#aria_nbv.configs.WandbConfig.log_model) | Lightning checkpoint-to-W&B artifact logging policy. | | [checkpoint_name](#aria_nbv.configs.WandbConfig.checkpoint_name) | Optional name for uploaded checkpoint artifacts. | | [tags](#aria_nbv.configs.WandbConfig.tags) | Optional run tags used for filtering and comparison. | | [group](#aria_nbv.configs.WandbConfig.group) | Optional group shared by related runs or trials. | | [job_type](#aria_nbv.configs.WandbConfig.job_type) | Optional role label such as training, evaluation, or sweep. | | [prefix](#aria_nbv.configs.WandbConfig.prefix) | Optional namespace prepended to logged metric keys. | #### Methods | Name | Description | | --- | --- | | [init_kwargs](#aria_nbv.configs.WandbConfig.init_kwargs) | Return the shared W&B run-identity arguments for non-Lightning reporters. | | [setup_target](#aria_nbv.configs.WandbConfig.setup_target) | Instantiate a logger rooted in :class:`PathConfig`'s W&B directory. | ##### init_kwargs { #aria_nbv.configs.WandbConfig.init_kwargs } ```python configs.WandbConfig.init_kwargs() ``` Return the shared W&B run-identity arguments for non-Lightning reporters. Lightning-only checkpoint and metric-prefix options deliberately remain exclusive to :meth:`setup_target`. This keeps small reporting tools on the same project, identity, grouping, and offline-mode contract without pretending that they are Lightning loggers. ##### setup_target { #aria_nbv.configs.WandbConfig.setup_target } ```python configs.WandbConfig.setup_target(**kwargs) ``` Instantiate a logger rooted in :class:`PathConfig`'s W&B directory. ## Functions | Name | Description | | --- | --- | | [describe_config_model](#aria_nbv.configs.describe_config_model) | Return schema/documentation descriptors for an in-memory config model. | ### describe_config_model { #aria_nbv.configs.describe_config_model } ```python configs.describe_config_model(model) ``` Return schema/documentation descriptors for an in-memory config model.