# Configuration Reference (config_v2)

This page is a field-oriented reference for the current strict schema.

Validation entrypoints:

- `spider validate-config <config.json> --mode sample`
- `spider.core.config_v2.validate.parse_canonical_config()`

The root object only allows:

- `io`
- `model`
- `inference`
- `observability`

Unknown keys at any strict block level raise a validation error.

## `io` block

Required keys:

- `dtime_file` (string)
- `station_file` (string)
- `catalog_infile` (string)
- `catalog_outfile` (string)
- `samples_outfile` (string)
- `checkpoint_dir` (string)
- `checkpoint_interval` (int, `>= 1`)
- `save_every_n` (int, `>= 1`)
- `write_samples` (bool)

Optional keys:

- `sample_write_interval` (int or null, `>= 0` when set)

## `model` block

Allowed keys:

- `model_file`
- `domain`
- `priors`
- `likelihoods`
- `filters`
- `eikonet`

### `model.domain`

Required:

- `lon_min` (number)
- `lat_min` (number)
- `z_min` (number)
- `z_max` (number, must satisfy `z_max > z_min`)
- `scale` (number, `> 0`)

### `model.priors`

Schema is pass-through at this layer (validated/materialized downstream). Typical blocks:

- `event`
- `centroid`

### `model.filters`

Expected sub-blocks in runtime bridge:

- `dtimes`
- `events`
- `residual`

Common keys:

- `dtimes`: `remove_duplicates`, `max_abs_input_dt`, `dtime_thin_frac`, `flip_dt_sign`, `cc_min`
- `events`: `min_dtimes`, `min_unique_phase_per_event`, `min_dtimes_per_pair`, `min_event_degree`, `min_events_per_cluster`, `max_pair_station_ratio`, `ratio_filter_phase`, `linearization_error`
- `residual`: `enabled`, `method`, `mad_sigma`, `abs_max`

### `model.likelihoods`

Expected sub-blocks:

- `locate_map`
- `sample`

Current sampling mode expects:

- `model.likelihoods.sample.type = "correlated_gaussian"`

## `model.likelihoods.sample.shared_event_re`

Allowed top-level keys:

- `enabled`
- `model`
- `limits`
- `fallback`
- `numerics`
- `station_phase_term`
- `solver`
- `edge_weights`
- `autotune`
- `logging`

Legacy flat keys are rejected (for example `grouping`, `max_nodes_per_group`, `jitter0`, `bucket_nodes`).

### `shared_event_re.model`

- `group_by` (current supported runtime value: `station_phase`)
- `tau_s` (`[P, S]`)
- `cluster.mode`, `cluster.k`

### `shared_event_re.limits`

- `max_nodes`
- `max_rows`

### `shared_event_re.fallback`

- `to_diag`
- `abort_on_pcg_fallback`

### `shared_event_re.numerics`

- `jitter0`
- `jitter_max`

### `shared_event_re.solver`

Canonical keys:

- `kind` (`pcg`)
- `max_iters`
- `min_iters`
- `tol`
- `batched`
- `node_bin_edges`
- `warm_start`
- `cache_max_entries`
- `prefetch_grouping`
- `profile_micro_steps`
- `merge_sparse_node_bins`
- `min_groups_per_node_bin`
- `max_node_bins_per_node`
- `precompute.enabled`
- `precompute.device`

### `shared_event_re.edge_weights`

- `mode`
- `ell_km`
- `eps_km`
- `power`
- `scale_km`
- `global_scale`
- `normalize`

### `shared_event_re.autotune`

- `enabled`
- `observe_epochs`
- `latest_epoch`
- `min_groups`
- `max_node_bins`
- `min_groups_per_node_bin`
- `min_node_bin`
- `min_gain`
- `raise_nodes_cap`
- `nodes_cap_max`

### `shared_event_re.logging`

- `quiet`
- `stats_log_every_epochs`

## `inference` block

Allowed keys:

- `sampler`
- `batching`
- `runtime`
- `safety`
- `compute`

### `inference.sampler`

Required/validated:

- `backend` (`psgld` or `sghmc`)
- `epochs_per_phase` (list of 4 ints, each `>= 0`)
- `lr` (list of 4 positive numbers)
- `temperature` (`>= 0`)
- `beta` (`0 <= beta < 1`)
- `eps` (`> 0`)
- `freeze_preconditioner_sampling` (bool)
- `sghmc_alpha` (required key; number for SGHMC, number/null otherwise)

Optional:

- `noise_scale_mult` (`> 0` when set)
- `dt_lr_mult` (`> 0` when set)
- `grad_clip_norm` (`>= 0` when set)
- `overrides` (dict)

`preconditioning` sub-block:

- `enabled` (bool)
- `type` (`rmsprop` or `lrd` when enabled)
- `include_gamma` (bool)
- `lrd` (dict when present)

### `inference.batching`

- `standard` (dict)
- `event_batches` (dict)

Runtime-bridged keys in common use:

- `standard`: `warmup`, `sgld`, `shuffle`
- `event_batches`: `enabled`, `events_per_batch`, `max_edges_per_batch`, `bucket_reorder_all`, `bucket_reuse_epochs`

### `inference.runtime`

Allowed:

- `cuda_empty_cache_every`
- `reset_batch_numbers`
- `clear_samples_on_reset`
- `min_samples_to_save`
- `verbose`
- `cluster_events`
- `seed`
- `gauge_projection`
- `torch`

### `inference.safety`

- `max_abs_dX` is `null` or list of 4 numbers.

### `inference.compute`

- `devices` is optional list of device specifiers (int or non-empty string).

## `observability` block

Allowed keys:

- `wandb`
- `diagnostics`

### `observability.wandb`

Required keys:

- `enabled` (bool)
- `project_name` (non-empty string or null)
- `run_name` (non-empty string or null)

### `observability.diagnostics`

Accepted as a dict and materialized downstream. Common keys:

- `pair_count_stats_enable`
- `sgld_log_gnoise`
- `sgld_log_temperature`
- `display_precond_every`
- `profile_shared_event_re`
- `wandb` (including `groups`)
- `ess_online`

See {doc}`diagnostics-catalog` for behavior and interpretation.