Skip to content

Getting Started

This guide walks you through setting up and running your first Falcon project.

Prerequisites

  • Python 3.10+
  • PyTorch 2.0+

Installation

pip install falcon-sbi

Project Structure

A typical Falcon project has this structure:

my_project/
├── config.yml      # Graph and training configuration
├── model.py         # Your simulator and embedding definitions
└── data/
    └── obs.npz      # Observed data (optional)

Minimal Example

1. Define Your Simulator

Create model.py with a forward model:

import numpy as np

class Simulator:
    """Simple Gaussian simulator: x = theta + noise."""

    def simulate_batch(self, batch_size, theta):
        # theta shape: (batch_size, n_params)
        # return shape must match the observed data shape
        noise = np.random.randn(*theta.shape) * 0.1
        return theta + noise

2. Create Configuration

Create config.yml:

logging:
  wandb:
    enabled: false
  local:
    enabled: true

paths:
  imports: ["."]

buffer:
  min_samples: 1000
  max_samples: 10000
  validation_samples: 256
  simulate_count: 64
  simulate_interval: 1

graph:
  theta:
    evidence: [x]
    simulator:
      _target_: falcon.priors.Product
      priors:
        - ['uniform', -10.0, 10.0]
    estimator:
      _target_: falcon.estimators.Flow
      max_epochs: 100
      net_type: zuko_nice

  x:
    parents: [theta]
    simulator:
      _target_: model.Simulator
    observed: "./data/obs.npz['x']"

3. Prepare Observation Data

import numpy as np

# Single observed value for true_theta = 2.5.
# Shape must match what simulate_batch returns for one sample.
true_theta = np.array([[2.5]])        # shape (1, 1): one sample, one parameter
obs = true_theta + np.random.randn(1, 1) * 0.1   # shape (1, 1)

np.savez("data/obs.npz", x=obs)

Embedding

This minimal example omits an embedding: key. Without one, Falcon passes the raw observation tensor directly into the flow. For real problems where x has many dimensions, add an embedding network to compress it to a summary statistic.

4. Run Training

falcon launch -o output/run_01

5. Sample from Posterior

falcon sample posterior -o output/run_01

CLI Commands

Command Description
falcon launch Start training
falcon sample prior Sample from prior
falcon sample posterior Sample from learned posterior
falcon sample proposal Sample from proposal distribution
falcon sample ppd Sample posterior predictive distribution (forward model evaluated at posterior samples)
falcon graph Display graph structure

Next Steps