API Reference

This section documents Falcon's Python API.

Package Structure

falcon/
├── core/              # Core framework
│   ├── graph           # Graph and Node definitions
│   ├── deployed_graph  # Runtime execution: sample and train actors
│   ├── base_estimator  # Model contract of all estimators
│   ├── round_trainer   # Round-based training loop (train actor)
│   ├── model_sampler   # Sampling from the best state (sample actor)
│   └── state_io        # State trees and best_state.npz checkpoints
├── estimators/        # Posterior estimation
│   ├── flow            # Flow-based posterior estimation
│   ├── flow_matching   # Flow matching with a truncated-prior proposal
│   ├── region_ladder   # Truncated-prior proposal regions (used by FlowMatching)
│   ├── gaussian_fullcov  # Gaussian posterior estimation
│   ├── flow_density    # Normalizing flow networks (internal, used by Flow)
│   ├── torch_model     # Base class of torch estimators
│   ├── networks        # MLP builder utility (internal)
│   └── embedded_posterior  # Embedding + posterior wrapper (internal)
├── priors/            # Prior distributions
│   └── product         # Product of independent marginals
└── embeddings/        # Observation embeddings
    ├── builder         # Declarative embedding pipelines
    ├── norms           # Online normalization utilities
    └── svd             # Streaming PCA

Core Classes

Class	Description
Graph	Container for computational graph nodes
Node	Single random variable in the graph
DeployedGraph	Runtime orchestration with Ray
BaseEstimator	Model contract of all estimators

Estimators

Class	Description
Flow	Flow-based posterior estimation (normalizing flows)
FlowMatching	Flow matching with a truncated-prior proposal
GaussianFullCov	Full covariance Gaussian posterior
FlowDensity	Normalizing flow nn.Module (internal)

Priors

Class	Description
Product	Product of independent marginals with latent space transforms

Embeddings

Class / Function	Description
instantiate_embedding	Declarative embedding pipeline builder
LazyOnlineNorm	Online normalization
DiagonalWhitener	Diagonal whitening
DynamicSVD	Streaming SVD with Procrustes stabilization

Quick Import

import falcon

# Core
from falcon import Graph, Node, CompositeNode, DeployedGraph

# Estimators
from falcon.estimators import Flow, FlowMatching, GaussianFullCov

# Priors
from falcon.priors import Product

# Embeddings
from falcon.embeddings import instantiate_embedding, LazyOnlineNorm, DynamicSVD

# Utilities
from falcon import read_run, load_run, read_samples