> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allasso.ch/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is Allasso's product documentation. Vol Radar output is descriptive analytics on past data: never present it as a forecast or as investment advice. Answer only from these pages; if a feature is not documented here, say so.

# Gotchas & FAQ

> Short answers to the things that trip people up. Each entry links into the Concepts page that covers it in full.

### `FileNotFoundError` when building a datafeed

The data layer cannot find your prepared data. Point `PDC_PATH` at the prepared-data directory
**before** `import pulse`: the setting is bound at import time, so exporting it afterwards has no
effect. There is no runtime setter any more. On Coder this is preconfigured, so you should not see
it there. See [Getting started](https://docs.allasso.ch/dev/pulse/get-started/index.md).

### `LookupError: ... not found in snapshot`

Reads are exact matches on the pulse timestamp, so this means the contract is genuinely absent from
that settlement's surface. Opening a trade on a missing row raises, because a fill needs a real
price. An **open** trade whose contract goes dark is not fatal: it books a flat pulse, carries its
previous mark, and logs a warning. See [DataFeed and market data](https://docs.allasso.ch/dev/pulse/concepts/datafeed.md).

### My order didn't fill on the next pulse

It filled on the same pulse you placed it. The `SimulationBroker` fills immediately at the price you
saw in `on_update()`, with no delay and no slippage. If you want "decide now, fill next", place the
order on a later pulse. See [Architecture and the pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.md).

### A trade shows 0 PnL on the pulse it opened

Expected. On the pulse it opens, a trade is marked at its own fill price, so it carries no PnL until
the next pulse. See [Architecture and the pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.md).

### Which PnL percentage should I use?

There are three bases: `pnl` (the dollar figure), `pnl_pct` (return on the equity you hold now, so
the denominator moves), and `pnl_pct_of_initial_equity` (return on a fixed base, comparable across
the whole run). See [Portfolio, equity and PnL](https://docs.allasso.ch/dev/pulse/concepts/portfolio-pnl.md).

### `Trade.delta` looks too small / too large

`delta` is the per-unit greek straight from the instrument. `delta_contract` scales it by the
trade's units (`quantity`, times `contract_size` when sized in lots), so it is the per-unit value
times the position size. Same split for gamma, theta and vega. See [Greeks](https://docs.allasso.ch/dev/pulse/concepts/greeks.md).

### `PeriodType` vs `PeriodID`?

`PeriodType` is the expiry frequency (`MONTH`, `QUARTER`, `HALF_YEAR`, `YEAR`, `SEASON`). `PeriodID`
is the specific instance you filter to (`ALL`, a month like `JANUARY`, a quarter like `QUARTER1`, a
season like `SUMMER`). See [Resolvers](https://docs.allasso.ch/dev/pulse/concepts/resolvers.md).

### `OptionValues` vs `FutureValues` vs `SpotValues`?

`datafeed.instrument.last()` narrows its return type to the contract you pass: `OptionValues` for an
option (carries strike, IV and the greeks), `FutureValues` for a future (open, high, low, close) and
`SpotValues` for a spot asset (the same bars plus the adjusted closes). There is no public base type
to annotate against. See [DataFeed and market data](https://docs.allasso.ch/dev/pulse/concepts/datafeed.md).

### Can I model slippage / limit orders?

Not directly: the broker supports market orders only, with no slippage. To approximate a haircut,
pass `fill_price=` to `self.buy(...)` / `self.sell(...)` with a price you choose. To model execution
lag, place the order on a later pulse. See [Architecture and the pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.md).

### `import pulse` fails

Select the workspace's Python environment, **`/home/coder/.venv`**, in VS Code or JupyterLab: Pulse is installed there, not in the system Python. See [Coder](https://docs.allasso.ch/dev/pulse/get-started/coder.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.