Skip to content

Configuration

Falcon uses YAML configuration files powered by OmegaConf. This page documents all available options.

Configuration Sections

logging

Configure experiment tracking:

logging:
  wandb:
    enabled: true
    project: "my-project"
    entity: "my-team"
  local:
    enabled: true
Key Type Default Description
wandb.enabled bool false Enable WandB logging
wandb.project str "falcon" WandB project name
wandb.entity str null WandB team/entity
local.enabled bool true Enable local file logging

paths

Configure file paths:

paths:
  import: "."
  graph: ${run_dir}/graph
  samples: ${run_dir}/samples
Key Type Default Description
import str "." Path to import custom modules
graph str ${run_dir}/graph Trained models directory
samples str ${run_dir}/samples Output samples directory

buffer

Configure the rolling sample buffer that feeds training. Falcon continuously simulates new samples in the background while training runs concurrently.

buffer:
  min_samples: 4096
  max_samples: 32768
  validation_samples: 256
  simulate_count: 64
  simulate_interval: 1
  simulate_when_full: true
  snapshot_fraction: 0.0
Key Type Default Description
min_samples int — Minimum training samples required before training starts
max_samples int — Maximum training samples retained; older samples are disfavoured once this is exceeded
validation_samples int — Number of samples held out for validation (used for early stopping)
simulate_count int 64 Number of new samples generated per simulation round. For simulators taking >1s per sample, keep this small (4–16) to avoid long delays between buffer updates; for fast simulators, increase to reduce Ray overhead.
simulate_interval float 1 Seconds between simulation rounds
simulate_when_full bool true If true, simulation continues after max_samples is reached and old samples are replaced; if false, simulation stops once the buffer is full
snapshot_fraction float 0.0 Fraction of simulated samples written to buffer/snapshots/ for inspection (0 = none, 1 = all)

graph

Define the computational graph. Each key is a node name:

graph:
  node_name:
    parents: [parent1, parent2]    # Forward model dependencies
    evidence: [evidence1]          # Inference dependencies
    scaffolds: [scaffold1]         # Additional conditioning
    observed: "./path/to/data.npz" # Observation file
    resample: false                # Enable adaptive resampling

    simulator:                     # Forward model
      _target_: module.ClassName
      param1: value1

    estimator:                     # Posterior learner (optional)
      _target_: falcon.estimators.Flow
      loop:
        max_epochs: 300
      network:
        net_type: nsf
      embedding:
        _target_: model.MyEmbedding
        _input_: [x]
      optimizer:
        lr: 0.01
      inference:
        gamma: 0.5

    ray:                          # Ray actor configuration
      num_gpus: 0
      num_cpus: 1

Node Configuration

simulator

The forward model that generates samples:

simulator:
  _target_: falcon.priors.Hypercube
  priors:
    - ['uniform', -10.0, 10.0]
    - ['normal', 0.0, 1.0]

estimator

The posterior learner. Falcon provides two estimators:

estimator:
  _target_: falcon.estimators.Flow

  loop:
    max_epochs: 300
    batch_size: 128
    early_stop_patience: 50
    cache_sync_every: 0
    max_cache_samples: 0
    cache_on_device: false

  network:
    net_type: nsf          # nsf, maf, zuko_nice, etc.
    theta_norm: true

  embedding:
    _target_: model.Embedding
    _input_: [x]

  optimizer:
    lr: 0.01
    lr_decay_factor: 0.1
    scheduler_patience: 8

  inference:
    gamma: 0.5             # Proposal width (0=posterior, 1=prior)
    discard_samples: true

ray

Per-node Ray resource allocation:

ray:
  num_gpus: 1
  num_cpus: 2

Global Ray Configuration

ray:
  num_cpus: 8
  num_gpus: 1
  object_store_memory: 1000000000

Observation Syntax

Load data from NPZ files with optional key extraction:

# Single-key NPZ (auto-extracted)
observed: "./data/obs.npz"

# Specific key extraction
observed: "./data/obs.npz['x']"

Overriding Configuration

Override any parameter via CLI:

falcon launch buffer.max_epochs=1000 graph.theta.estimator.optimizer.lr=0.001