Skip to main content
The DataFeed is how a strategy reads the market. Everything it returns is read “as of” a timestamp, so a backtest only ever sees what was knowable then. You reach it through self.datafeed. The data itself lives in pulse-data-components (pdc), the sibling package pulse-core depends on for everything below. It memory-maps the prepared Arrow files under PDC_PATH; pulse-core never touches the disk layout directly.

Four providers

DataFeed bundles four providers, each answering a different question:

Reading one instrument

instrument gives you a single contract’s data. Two methods, both keyed off a timestamp:
  • last(instrument, as_of_time) returns one row of values exactly at as_of_time. It does not search backwards: pass a timestamp that is on the calendar (normally self.last_pulse).
  • history(instrument, as_of_time, count) returns the last count observations at or before as_of_time. count is a row count, not a duration, so it follows the run’s own cadence.
The return type narrows to the instrument you passlast() returns OptionValues for an option, FutureValues for a future and SpotValues for spot; history() returns the matching *HistoryValues. Greeks (delta, gamma, theta, vega, iv) only exist on the option types. So last(future).delta is not a field - futures carry open/high/low/close instead. The type checker knows which fields are present from the instrument you pass in.

What a row carries

Every instrument shares a small common core; options, futures and spot each add their own fields. dte is days to expiry, tte is time to expiry as a year fraction. The history variants carry the same fields, but the per-pulse ones become lists. A spot position is marked at close_adj_div.

When a contract is missing

A contract that is not in the snapshot for a pulse raises LookupError. How the engine reacts depends on what it was doing:
  • Opening a trade propagates it. Trying to buy a contract that does not print is a strategy bug, not a data gap, so the run stops.
  • Marking an open trade does not. The trade books a flat pulse (PnL 0, the previous mark and greeks carried) and a warning names the instrument and the timestamp. Strategy.calculate_trades_summary behaves the same way: it reuses the trade’s last known greeks, and leaves that leg out of the iv average and out of min_dte.
An unknown underlying, or a PDC_PATH that does not exist, raises FileNotFoundError when the run builds its calendar. See Gotchas & FAQ.

Reading the smile

smile.last(...) returns one SmileValues row: the full curve for an expiry as of a timestamp. Where OptionValues is a single strike, SmileValues holds parallel lists across every strike on that expiry - strike, moneyness, iv, delta, quick_delta, gamma, theta, vega, price - alongside the single underlying_price. This is the curve the strike resolvers search to turn a delta or moneyness target into a concrete strike.

Reading the whole surface

surface hands you every expiry and strike at once, for when you want to analyse rather than trade a single leg. Each method comes in three flavours, one per frame type:
  • arrow_last / pandas_last / polars_last - one snapshot, every row of it.
  • arrow_history / pandas_history / polars_history - every snapshot between start_time and end_time, concatenated.
The columns are the raw snapshot columns (datetime, expiration_date, type, strike, mny, underlying_price, iv, value, the greeks, dte, tte, volume, open_interest). Reading a long span is a lot of rows, so bound it.

Reference data

reference reads the static facts about an underlying from its metadata:
  • available_settlements(underlying_id, start_datetime=None, end_datetime=None, *, instrument_type=None, unified=False) - the timestamps that have data, ascending. An underlying holds up to three instrument families (options, futures, spot) with separate calendars: instrument_type picks which to draw on and unified=True intersects them instead of unioning. The engine builds a run’s timeline with unified=True, so every pulse is a timestamp every family can be marked on. See Timing.
  • contract_size(underlying_id, instrument_type, futures_expiration_date=None) - units per lot, the multiplier behind is_lots=True sizing.
  • price_format_multiplier(underlying_id, instrument_type) - the factor turning the stored price into the marking price.
Contract sizes keyed by delivery monthSome underlyings (TTF) size the lot per delivery month rather than per instrument type. Those need UnderlyingID(id, variable_contract_size=True) and the futures expiry: for an option that is OptionValues.underlying_expiration_date, never the option’s own expiry. Passing the flag when the metadata is keyed per instrument type (or omitting it when it is keyed per month) raises ValueError naming which way round it should be. Trades read this once at open, so you normally only meet it when you call contract_size yourself.Only declare the flag for an underlying whose underlying_expiration_date varies per contract. A calendar-spread root records one value (the prompt futures expiry) for its whole surface, so month keying would size every trade opened on a pulse alike and move that size with the trade date rather than the contract, without raising anything.

No lookahead

Every read takes a timestamp (as_of_time, normally self.last_pulse) and returns only data at or before it. A strategy that reads as of self.last_pulse cannot see a future price or a greek that had not printed yet, so a backtest cannot cheat by peeking ahead. This is the same “as of” rule the pulse loop enforces by advancing the clock before on_update() runs. Related: Architecture and the pulse loop · Timing · Resolvers · Structures
Last modified on November 4, 2026