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 atas_of_time. It does not search backwards: pass a timestamp that is on the calendar (normallyself.last_pulse).history(instrument, as_of_time, count)returns the lastcountobservations at or beforeas_of_time.countis a row count, not a duration, so it follows the run’s own cadence.
The return type narrows to the instrument you pass
last() 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 raisesLookupError. 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_summarybehaves the same way: it reuses the trade’s last known greeks, and leaves that leg out of theivaverage and out ofmin_dte.
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 betweenstart_timeandend_time, concatenated.
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_typepicks which to draw on andunified=Trueintersects them instead of unioning. The engine builds a run’s timeline withunified=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 behindis_lots=Truesizing.price_format_multiplier(underlying_id, instrument_type)- the factor turning the stored price into the marking price.
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
