Add example 06: spectral analysis with chirp signal inference

examples/06_spectral_analysis/config.yml

@@ -0,0 +1,138 @@
+# =============================================================================
+# Falcon Example Configuration: 06_spectral_analysis (tokenized variant)
+# -----------------------------------------------------------------------------
+# Uses Signal + Noise + Data decomposition with an intermediate "tokens" node
+# that caches the expensive STFT tokenization. Training operates on compact
+# token tensors instead of re-running the STFT every epoch.
+#
+# Graph: theta -> y (clean signal)
+#                  \
+#                   -> x (observed = y + n) -> tokens
+#                  /
+#        n (noise)
+#
+# NOTE: This config will currently FAIL during proposal/posterior sampling
+# because falcon's inference graph does not include intermediate deterministic
+# nodes (tokens has no estimator and no evidence).
+# =============================================================================
+
+logging:
+  wandb:
+    enabled: false
+    project: falcon_examples
+    group: 06_spectral_analysis
+    dir: ${run_dir}
+  local:
+    enabled: true
+    dir: ${paths.graph}
+
+paths:
+  import: "./src"
+  buffer: ${run_dir}/sim_dir
+  graph: ${run_dir}/graph_dir
+  samples: ${run_dir}/samples_dir
+
+buffer:
+  min_samples: 4092
+  max_samples: 4092
+  validation_samples: 256
+  simulate_count: 256
+  simulate_when_full: true
+  simulate_interval: 1
+  store_fraction: 0.0
+
+graph:
+  theta:
+    evidence: [tokens]
+    sample_chunk_size: 8
+
+    simulator:
+      _target_: falcon.priors.Product
+      priors:  # 10x CRB at N=100k
+        - ['normal', 2.75e-3, 1e-7]  # f0
+        - ['normal', 1.0,     1e-5]  # chirp_mass
+        - ['normal', 1.5,     1e-1]  # harmonic_decay
+
+    estimator:
+      _target_: falcon.estimators.Gaussian
+      loop:
+        num_epochs: 500
+        batch_size: 64
+        early_stop_patience: 32
+      network:
+        hidden_dim: 512
+        num_layers: 3
+        momentum: 0.1
+        min_var: 1.0e-25
+        eig_update_freq: 1
+      embedding:
+        _target_: fuge.nn.TransformerEmbedding
+        d_model: 64
+        n_heads: 4
+        n_layers: 2
+        d_ff: 256
+        dropout: 0.0
+        _input_:
+          _target_: falcon.embeddings.RunningNorm
+          momentum: 0.01
+          dim: [0, 1]
+          output_dtype: float32
+          _input_:
+            _target_: embeddings.SpectralTokenEmbed
+            n_freq: 10
+            phase_mode: boundary
+            _input_: [tokens]
+      optimizer:
+        lr: 0.005
+        lr_decay_factor: 0.5
+        scheduler_patience: 16
+      inference:
+        gamma: 1.0
+        discard_samples: false
+        log_ratio_threshold: -20.0
+
+    ray:
+      num_gpus: 0.2
+
+  y:
+    parents: [theta]
+    sample_chunk_size: 8
+    simulator:
+      _target_: model.Signal
+      N: 100000
+    ray:
+      num_gpus: 0.2
+
+  n:
+    simulator:
+      _target_: model.Noise
+      N: 100000
+      sigma: 1.0
+
+  x:
+    parents: [y, n]
+    sample_chunk_size: 8
+    simulator:
+      _target_: model.Data
+    observed: "./data/obs.npz['x']"
+    ray:
+      num_gpus: 0.2
+
+  tokens:
+    parents: [x]
+    sample_chunk_size: 8
+    simulator:
+      _target_: embeddings.Tokenizer
+      k: 10000  # 2024
+      n_peaks: 3
+      n_dlnf: 11
+      dlnf_min: 0.0
+      dlnf_max: 0.05
+    ray:
+      num_gpus: 0.2
+
+sample:
+  prior:
+    n: 1000
+  posterior:
+    n: 1000

examples/06_spectral_analysis/config2.yml

@@ -0,0 +1,110 @@
+# =============================================================================
+# Falcon Example Configuration: 06_spectral_analysis (SVD variant)
+# -----------------------------------------------------------------------------
+# Uses scaffolded streaming SVD embedding on raw signals.
+# Clean signal (y) and noise (n) are scaffolds — available during training
+# for whitening/PCA learning, but not at inference time.
+#
+# Graph: theta -> y (clean signal)
+#                  \
+#                   -> x (observed = y + n)
+#                  /
+#        n (noise)
+#
+# Prior ranges are 3x CRB at N=100k (narrow, for parameter estimation).
+# Amortized only (no proposal resampling).
+# =============================================================================
+
+logging:
+  wandb:
+    enabled: false
+    project: falcon_examples
+    group: 06_spectral_analysis
+    dir: ${run_dir}
+  local:
+    enabled: true
+    dir: ${paths.graph}
+
+paths:
+  import: "./src"
+  buffer: ${run_dir}/sim_dir
+  graph: ${run_dir}/graph_dir
+  samples: ${run_dir}/samples_dir
+
+buffer:
+  min_samples: 4092
+  max_samples: 4092
+  validation_samples: 256
+  simulate_count: 256
+  simulate_when_full: true
+  simulate_interval: 1
+  store_fraction: 0.0
+
+graph:
+  theta:
+    evidence: [x]
+    scaffolds: [y, n]
+
+    simulator:
+      _target_: falcon.priors.Product
+      priors:  # 10x CRB at N=100k
+        - ['normal', 2.75e-3, 1e-7]  # f0
+        - ['normal', 1.0,     1e-5]  # chirp_mass
+        - ['normal', 1.5,     1e-1]  # harmonic_decay
+
+    estimator:
+      _target_: falcon.estimators.Gaussian
+      loop:
+        num_epochs: 500
+        batch_size: 64
+        early_stop_patience: 32
+      network:
+        hidden_dim: 128
+        num_layers: 3
+        momentum: 0.1
+        min_var: 1.0e-25
+        eig_update_freq: 1
+      embedding:
+        _target_: embeddings.SVDEmbedding
+        N: 100000
+        n_components: 64
+        buffer_size: 256
+        momentum: 0.1
+        _input_: [x, y, n]
+      optimizer:
+        lr: 0.005
+        lr_decay_factor: 0.5
+        scheduler_patience: 16
+      inference:
+        gamma: 1.0
+        discard_samples: false
+        log_ratio_threshold: -20.0
+
+    ray:
+      num_gpus: 0.3
+
+  y:
+    parents: [theta]
+    simulator:
+      _target_: model.Signal
+      N: 100000
+    ray:
+      num_gpus: 0.3
+
+  n:
+    simulator:
+      _target_: model.Noise
+      N: 100000
+      sigma: 1.0
+
+  x:
+    parents: [y, n]
+    simulator:
+      _target_: model.Data
+    observed: "./data/obs.npz['x']"
+
+sample:
+  prior:
+    n: 1000
+  posterior:
+    n: 1000

examples/06_spectral_analysis/config3.yml

@@ -0,0 +1,106 @@
+# =============================================================================
+# Falcon Example Configuration: 06_spectral_analysis (N=256, no embedding)
+# -----------------------------------------------------------------------------
+# Minimal config with 256 data bins — raw signal fed directly into Gaussian
+# estimator (no embedding network needed at this data size).
+#
+# Graph: theta -> y (clean signal)
+#                  \
+#                   -> x (observed = y + n)
+#                  /
+#        n (noise)
+#
+# Prior ranges are ±10σ CRB at N=256.
+# =============================================================================
+
+logging:
+  wandb:
+    enabled: false
+    project: falcon_examples
+    group: 06_spectral_analysis
+    dir: ${run_dir}
+  local:
+    enabled: true
+    dir: ${paths.graph}
+
+paths:
+  import: "./src"
+  buffer: ${run_dir}/sim_dir
+  graph: ${run_dir}/graph_dir
+  samples: ${run_dir}/samples_dir
+
+buffer:
+  min_samples: 32000
+  max_samples: 32000
+  validation_samples: 256
+  simulate_count: 256
+  simulate_when_full: false
+  simulate_interval: 1
+  store_fraction: 0.0
+
+graph:
+  theta:
+    evidence: [x]
+
+    simulator:
+      _target_: falcon.priors.Product
+      priors:  # Normal, 5σ CRB at N=256
+        #        - ['normal', 2.7500000000e-3, 4.9540464808e-8]  # f0
+        #        - ['normal', 1.0000000000, 7.0304073517e-5]      # chirp_mass
+          #- ['normal', 1.5000000000, 2.9271998214e-1]       # harmonic_decay
+        - ['normal', 2.7500000200e-3, 4.9540464808e-8]  # f0
+        - ['normal', 1.0000200000, 7.0304073517e-5]      # chirp_mass
+        - ['normal', 1.6000000000, 2.9271998214e-1]       # harmonic_decay
+
+    estimator:
+      _target_: falcon.estimators.Gaussian
+      loop:
+        num_epochs: 500
+        batch_size: 256
+        early_stop_patience: 16
+      network:
+        hidden_dim: 512
+        num_layers: 3
+        momentum: 0.1
+        min_var: 1.0e-25
+        eig_update_freq: 1
+      embedding:
+        _target_: torch.nn.Identity
+        _input_: x
+      optimizer:
+        lr: 0.005
+        lr_decay_factor: 0.5
+        scheduler_patience: 16
+      inference:
+        gamma: 0.1
+        discard_samples: false
+        log_ratio_threshold: -20.0
+
+    ray:
+      num_gpus: 0.3
+
+  y:
+    parents: [theta]
+    simulator:
+      _target_: model.Signal
+      N: 256
+    ray:
+      num_gpus: 0.3
+
+  n:
+    simulator:
+      _target_: model.Noise
+      N: 256
+      sigma: 1.0
+
+  x:
+    parents: [y, n]
+    simulator:
+      _target_: model.Data
+    observed: "./data/obs_256.npz['x']"
+
+sample:
+  prior:
+    n: 1000
+  posterior:
+    n: 1000