> ## 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.

# Architecture and the pulse loop

> pulse-core runs a backtest as a loop over timestamps. Each timestamp is a pulse.

pulse-core runs a backtest as a loop over timestamps. Each timestamp is a **pulse**. On every pulse
your strategy gets a chance to look at the market and place orders, the broker fills any orders, and
the portfolio marks everything to market. The pieces below are wired together for you by
`run_sequentially`; you normally only write a `Strategy`.

## The components

| Component | Role |
| - | - |
| `Strategy` | Your code. You subclass it and implement `on_update()`, called once per pulse. |
| `PulseIndex` | The clock. Holds the ordered timestamps and the current one (`last_pulse`). |
| `DataFeed` | Market data: `instrument` (prices, greeks), `smile` (the vol curve), `surface` (every strike and expiry), `reference` (settlements, contract sizes). |
| `ResolverRegistry` | Turns relative specs into concrete contracts: strikes by delta/moneyness, expiries by month/`nth`. |
| `Broker` (`SimulationBroker`) | Turns orders into trades. Market orders only, no slippage. |
| `Portfolio` | Holds trades, marks them to market, tracks equity, fees and greeks. |
| `Stats`, `charts`, `StrategyReport` | Read the finished run: metrics, plots, a self-contained HTML report. |

A `Strategy` reaches all of these through `self`: `self.datafeed`, `self.resolver`, `self.broker`,
`self.portfolio`, `self.pulse_index`, plus `self.last_pulse` and `self.current_equity`.

`DataFeed` and `ResolverRegistry` come from **pulse-data-components** (`pdc`), the sibling package
that owns the data layer. pulse-core re-exports them, so `from pulse import DataFeed` and
`from pulse_data_components import DataFeed` are the same class; the engine modules themselves live
under `pulse.core` (`pulse.core.atm`, `pulse.core.strategy`, `pulse.core.trade`, ...) and are
re-exported from `pulse` too.

## One pulse, step by step

`Strategy.pulse()` does the same five steps every time:

```mermaid theme={null}
sequenceDiagram
    participant PI as PulseIndex
    participant S as Strategy.on_update()
    participant B as Broker
    participant P as Portfolio
    PI->>PI: 1. advance to the next timestamp
    PI->>S: 2. call on_update()
    S->>B: place orders (self.buy / self.sell)
    B->>P: 3. fill open orders into trades
    P->>P: 4. add new trades, mark all open trades to market
    P->>P: 5. update equity, fees, greeks
```

1. **Advance the clock.** `PulseIndex` moves to the next timestamp; it becomes `self.last_pulse`.
2. **Run your logic.** `on_update()` reads data as of `self.last_pulse` and places orders with
   `self.buy(...)` / `self.sell(...)` / `self.broker.create_order(...)`.
3. **Fill orders.** The broker turns every open order into a trade at the current pulse.
4. **Book the trades.** New trades are added to the portfolio; all open trades are repriced. A
   contract missing from this pulse's snapshot books a flat pulse and logs a warning rather than
   stopping the run (see [DataFeed](https://docs.allasso.ch/dev/pulse/concepts/datafeed.md)).
5. **Update the books.** Equity, fees and greeks are recomputed for this pulse.

> [!NOTE]
>
> **How fills and entry pricing work**
>
> The simulation broker uses a simple, idealized fill model:
>
> * **Fills are immediate and frictionless.** An order fills on the same pulse you place it, at the
>   price you saw in `on_update()` - no delay, no slippage, no partial fills. Entries are therefore
>   slightly optimistic, since you always trade at the observed price.
> * **Fine for slow strategies, watch it for timing.** Filling at the close you just saw is the
>   standard "trade-at-close" assumption. It is harmless for slow, path-driven strategies (monthly
>   rolls, theta harvesting), where the underlying's move dwarfs the entry tick; it matters more for
>   signal-timing or higher-frequency strategies, which implicitly assume they can transact at the
>   exact print their signal fired on. For those, place the order on the next pulse to model "decide
>   now, fill next."
> * **A position opens flat.** On the pulse it opens, a trade is marked at its own fill price, so it
>   carries no PnL until the next pulse.
> * **The entry price is yours to set.** Pass `fill_price=` to `self.buy(...)`, `self.sell(...)`, or
>   `self.broker.create_order(...)` to trade at a price you choose - a fixed level, or the observed
>   price adjusted for slippage - rather than the settlement price.

Because `on_update()` only ever sees data as of `self.last_pulse`, a backtest cannot look into the
future - you can only act on what was knowable at the time. See
[DataFeed and market data](https://docs.allasso.ch/dev/pulse/concepts/datafeed.md) for how that "as of" rule is enforced.

## Running a backtest

`run_sequentially` builds the whole environment from defaults and runs your strategy:

```python theme={null}
from pulse import Strategy, run_sequentially

class MyStrategy(Strategy):
    def __init__(self):
        super().__init__(name="My strategy", underlying_id="COM.BRN")

    def on_update(self) -> None:
        ...  # place orders here

result = run_sequentially([MyStrategy()], initial_equity=1_000_000)[0]
print(result.strategy.stats)
```

`run_sequentially` takes a **list** of strategies, so one call runs one strategy or a whole
[parameter sweep](https://docs.allasso.ch/dev/pulse/how-to/parameter-sweeps.md). It accepts the pieces you want to override -
`datetimes`, `datafeed`, `resolver`, `fee_calculator` - and fills the rest with local defaults built
from `PDC_PATH`. To build the environment explicitly (for example to share one datafeed across runs)
use `EnvironmentBuilder`.

Without `datetimes`, the calendar is the underlying's own settlement dates, intersected across its
instrument families (`available_settlements(uid, unified=True)`) and across underlyings. See
[Timing](https://docs.allasso.ch/dev/pulse/concepts/timing.md).

**Related:** [Timing](https://docs.allasso.ch/dev/pulse/concepts/timing.md) · [DataFeed and market data](https://docs.allasso.ch/dev/pulse/concepts/datafeed.md) ·
[Orders, trades and the broker](https://docs.allasso.ch/dev/pulse/concepts/orders-trades-broker.md) · [Portfolio, equity and PnL](https://docs.allasso.ch/dev/pulse/concepts/portfolio-pnl.md)


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