Skip to content

Retained forecasts

fast_vollib.forecasting describes targets and retained sample sets without portfolio, pricing, broker or training dependencies. Numerical adapters load the existing simulation and surface APIs only when called. No model is trained here.

Draw once, query stored values

from datetime import datetime, timezone
from fast_vollib.forecasting import ForecastQuery, ProcessDistribution
from fast_vollib.instruments import InstrumentRef
from fast_vollib.processes import GBM

origin = datetime(2026, 1, 1, tzinfo=timezone.utc)
query = ForecastQuery(origin=origin, times=(0.0, 0.25, 1.0),
    convention="act_365", targets=("asset",), kind="path")
law = ProcessDistribution(process=GBM(drift=0.05, volatility=0.2),
    initial_state=100.0, underlier=InstrumentRef(identifier="ACME", currency="USD"),
    query=query, measure="physical", backend_metadata={"backend": "numpy"},
    conditioning_cutoff=origin, observations_digest="example:observations")
draws = law.draw(n_samples=100, rng=17)
result = draws.query(query)
view = result.to_scenario_view(target_id="asset")
assert view.scenario.states.shape == (100, 3, 1)

The process adapter delegates to simulation.simulate; it never changes drift because of a measure label. Backend, device and dtype follow the existing simulation inputs. Its backend_metadata is caller-declared provenance, not a backend selector. JAX needs an explicit PRNG key; NumPy and Torch accept their existing RNG inputs. Same seed comparisons apply to a fixed backend, version and grid, and do not establish consistency on arbitrary grids.

FixedGridDrawSet.query() only selects retained targets and stored times. It never consumes randomness, interpolates, refines, extends or replays a sampler. Repeated and subset queries preserve draw-set identity, sample IDs, values and weights. Queries cannot change origin or day count. Each independent draw gets a fresh draw_set_id, even if its numbers replay exactly from the same seed. Sample IDs are text namespaced by that ID, rather than unqualified row numbers.

A path query requires at least two strictly increasing times beginning at zero. Aware datetime inputs normalize to elapsed years using the required act_365, act_365_25 or act_360 convention. Negative, nonfinite, mixed and duplicate times are refused. A marginal query can request a single stored date without an origin row. Single-date blocks answer one marginal time per query; make separate queries for multiple marginal dates. A marginal cannot become a path by supplying an initial spot later.

Targets and blocks

Every ForecastTarget has a unique target_id, entity, Quantity, units and resolution. Coordinates describe additional axes. ReturnSpec is required exactly for return targets, naming simple/log, cumulative/incremental, base time and whether distributions are included. A target contains no implicit conversion to spot. Channel names are unique within a target; the same channel on two targets remains distinct.

ForecastResult carries the requested target descriptors as well as its query. Blocks are keyed by target ID, never by channel name. Each block shares the same sample axis and the query's time convention:

Block Values and validity
TrajectoryBlock (sample, time, channel); validity (sample, time)
MarginalBlock One date, (sample, channel); validity (sample,)
SurfaceBlock One date, canonical SurfacePoints, IV and validity (sample, point)
CurveBlock One date, increasing tenors, values and validity (sample, tenor)
EventBlock Sample-aligned tuples of ordered MarkedEvent records

Missing or invalid cells retain their explicit masks. Valid entries must be finite; valid IV is strictly positive. Spot projection consumes only its own target's validity, so an invalid volume target does not invalidate a spot trajectory. Reporting blocks own sealed host NumPy copies. Changing an input buffer or an external native Scenario cannot change a retained report. This boundary detaches native tensors and does not promise gradients or device retention. Use native simulation directly when those are needed.

ForecastMeta declares measure, weighting, sampling dependence, target coupling, point/distributed initial state, generator, draw-set identity, conditioning cutoff, observation digest and optional checkpoint/seed/backend metadata. Conditioning cannot use observations available after the forecast origin. Matching sample counts alone never establishes joint target coupling.

Equal weighting uses weights=None; explicit importance weights must be finite, nonnegative and have positive finite mass. They are normalized once, retaining original_weight_mass. Stress sets use measure="stress_only" and weighting_scheme="none", with no probability weights. Generic nonfinancial targets may have no measure. Financial projection requires one. These containers provide no probability-of-profit or risk-summary methods.

Financial projection

ForecastResult.to_scenario_view(target_id=..., channels=("spot",)) requires an identified spot TrajectoryBlock, an InstrumentRef underlier, a declared measure and a grid starting at zero. ScenarioView owns the resulting scenario, IDs, weights, validity, origin, convention, target identity and metadata. It has no contract marks, inventory or P&L fields. Marginals, surfaces, curves and events cannot masquerade as scenarios.

returns_to_spot is an explicit adapter requiring a matching underlier and positive initial price. The declared return base must equal the forecast origin and the origin return must be zero. It accumulates incremental log returns or compounds incremental simple returns; cumulative returns are applied directly. Total returns need a caller-supplied dividend mapping to ex-distribution prices. No initial row, dividend convention or settlement interval is fabricated.

Surface draws

SurfaceDistributionAdapter(surface_distribution=..., points=..., date=..., query=..., target=..., meta=..., market=...) wraps the existing joint surface sampling protocol for one aware date and fixed canonical (k, T) points. The date must agree with the single-date marginal query. Drawing calls sample() once over all points and checks sample count, coordinates and point identities/order. Retained queries never resample. This adapter supplies neither temporal coupling nor an arbitrary evaluable surface. SurfaceBlock.surfaces is currently required to be None: retaining live mutable model objects has no ownership guarantee.

Forecast snapshots, context updates, external learned-model adapters, evaluation and portfolio readouts are separate capabilities. A retained fixed-grid draw alone does not establish calibrated probabilities or a continuous-time path law.