State function API¶

This page is a curated map of the public API in SFI.statefunc. It summarises the main classes and functions and links to the full auto-generated API documentation.

For a conceptual introduction, see State function design and Models and state functions. For canonical recipes (Lorenz, harmonic underdamped, limit cycle, double-well) see Building bases.

What is a state function?¶

The package is built on three closely related abstractions:

Object	Purpose	Use when…
`Basis`	Dictionary of parameter-free vector features \(\{\phi_\alpha(x)\}\) used in linear inference.	You want closed-form regression: `infer_force_linear()` / `infer_diffusion_linear()`.
`PSF`	Parametric family \(F(x; \theta)\) — linear or nonlinear in \(\theta\).	You want parametric inference (`infer_force()`), or a typed handle for an MLP / gated drift.
`SF`	Fitted state function with frozen parameters; callable on data.	You want to evaluate / simulate / serialise a result, or define a ground-truth field for an `SFI.langevin` process.

The factories below are the three corresponding entry points.

Mini-examples¶

from SFI import make_sf
from SFI.statefunc import make_basis, make_psf

# rank is an int: 0 = scalar, 1 = vector, 2 = matrix

# Basis — used by linear inference
B = make_basis(lambda x: x, dim=2, rank=1)

# PSF — used by parametric / nonlinear inference.
# The parameters arrive in a keyword named ``params``; declare each
# block by shape (``()`` = scalar).
def spring(x, *, params):
    return -params["k"] * x

F_psf = make_psf(spring, dim=2, rank=1, n_features=1, params={"k": ()})

# SF — frozen ground truth for a simulator
F_sf = make_sf(lambda x: -1.33 * x, dim=2, rank=1)

Core classes¶

These are the main user-facing objects:

Basis – dictionary of parameter-free features used in linear inference.
PSF – parametric state-function family \(F(x; \theta)\) used in nonlinear inference and as a bridge to simulation.
SF – state function with fixed parameters, used for evaluation and Langevin processes.
StateExpr – underlying expression graph; most users see it indirectly through Basis/PSF/SF.
Interactor – local K-body interaction rule, dispatched to build global state functions.

Factories and helpers¶

High-level constructors:

make_basis() – wrap a single-sample function into a Basis.
make_sf() – wrap a single-sample callable into a fixed-parameter SF, typically to define a ground-truth force or diffusion field for a SFI.langevin simulator.
make_psf() – wrap a single-sample function with parameters into a PSF.
make_interactor() – build an Interactor from a local K-body rule.

Parameter handling:

ParamSpec – describes a single named parameter block (shape, dtype, init).
ParamSuite – immutable container of parameter specs, used internally by PSFs.

Execution, differentiation, and memory¶

Common methods shared by Basis, PSF, and SF:

StateExpr.__call__() – evaluate on trajectories; usually accessed via Basis/PSF/SF.
PSF.d_x() / SF.d_x() – derivative with respect to state coordinates.
PSF.d_v() / SF.d_v() – derivative with respect to velocities (for underdamped models).
PSF.d_theta() – derivative with respect to parameters \(\theta\).

Runtime / performance controls:

set_jit() – enable/disable JIT compilation of Basis/PSF/SF calls.
SFI.statefunc.memhint (MemHint, SampleMeta) – internal memory-usage estimates used by SFI.integrate for adaptive chunking.

Interacting particle systems (optional)¶

These are only relevant if you work with interacting particles or lattice fields. For a high-level explanation see the “Interacting particle systems” section in State function design.

Front-end:

Interactor – defines a local K-body rule on Xk.
Interactor.dispatch() – apply the rule over a neighbour graph to build a global Basis/PSF/SF.

Back-end interaction graph specs (expert use, stable subset only):

SFI.statefunc.nodes.interactions – interaction graph specifications and dispatchers.

Layout and sectors¶

For building structured multi-field models on regular grids or with heterogeneous tensor components. See Structured fields: Layout, Sectors, and Embed for the user guide (part of the experimental SPDE toolbox).

GridLayout – declares named sectors on a regular grid; provides differential operators and embed() compilation.
ScalarSector – a scalar field (one index per grid site).
VectorSector – a vector field (sdim indices per grid site).
SymTensorSector – a symmetric rank-2 tensor (Voigt-packed).
TensorSector – a general rank-2 tensor.
StateLayout – protocol shared by all layout types.

StructuredExpr – symbolic expression node in the inner world of layouts; supports +, *, &, dot, einsum, stack, eye.

Contracts¶

Every node carries the same static contract — shape and requirement metadata (rank, dim, pdepth, n_features, required extras keys, …) — which is what lets nodes be composed safely. See State function design for the meaning of each field. The one public handle you touch directly is:

Rank – enumeration of tensor ranks (SCALAR, VECTOR, MATRIX, …).

Full API¶

For complete signatures and member lists, run SFI_DOCS_RUN_APIDOC=1 make html to generate the full auto-documented API from source.