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

# Timing and the pulse clock

> A backtest is a walk over an ordered list of timestamps. PulseIndex holds that list and tracks where the walk currently is. You rarely touch it directly - the strategy drives it for you.

A backtest is a walk over an ordered list of timestamps. `PulseIndex` holds that list and tracks
where the walk currently is. You rarely touch it directly - the strategy drives it for you.

## PulseIndex

`PulseIndex` is constructed from a `list[datetime]` and keeps a single cursor into it.

| Member | Meaning |
| - | - |
| `last_pulse` | The current timestamp. All data reads are "as of" this moment. |
| `index` | The cursor's position in the timestamp list. |
| `pulse()` | Advance the cursor to the next timestamp. Clamps at the end. |
| `has_next()` | `True` while another timestamp remains after the current one. |
| `pulses_per_year` | Cadence as periods-per-calendar-year, used to annualize metrics. |
| `pulse_history(i)` | The timestamp at index `i`. Negative indices count back, so `pulse_history(index - 1)` is the previous pulse. |
| `peek_next()` | The timestamp the next `pulse()` would land on, or `None` at the end. |

`pulses_per_year` is derived from the timestamp span (`len(datetimes) * 365 / span_days`), so a daily
SPX run lands near 252, an hourly 24/7 BTC run near 8760. It is cached and recomputed when timestamps
are appended.

## The clock advances before your logic

`Strategy.pulse()` runs the same fixed order every step:

1. `pulse_index.pulse()` - move the clock to the next timestamp.
2. `on_update()` - your logic, reading data as of the new `last_pulse`.
3. The broker fills any orders, the portfolio books and reprices.

The cursor starts at index `0`, and the clock is advanced **first**. So `on_update()` first runs on
the **second** timestamp in the list, never the first. The first timestamp is only ever the starting
mark the clock advances away from.

> [!NOTE]
>
> **You drive the clock through the strategy, not by hand**
>
> `run_sequentially` builds the `PulseIndex` from your `datetimes` and loops it while `has_next()`
> is `True`. Reach the current time through `self.last_pulse`; you should not call `pulse()`
> yourself inside a strategy.

## Where the timestamps come from

Unless you pass `datetimes=` explicitly, the environment builds the calendar from the underlying's
own settlement dates:

```python theme={null}
self.datafeed.reference.available_settlements("COM.BRN", unified=True)
```

`unified=True` **intersects** the underlying's instrument families (options, futures, spot), so every
pulse is a timestamp where every family has data - a mixed options-plus-futures book can be marked on
each one. With more than one underlying the per-underlying calendars are intersected again.

`available_settlements` also takes `start_datetime` / `end_datetime` bounds and an `instrument_type`
filter, so you can restrict a run to one period or to a single family and pass the result as
`datetimes=`:

```python theme={null}
dts = self.datafeed.reference.available_settlements(
    "COM.BRN", datetime(2024, 1, 1), datetime(2024, 12, 31), unified=True,
)
```

## Counting back, not stepping back

There is no calendar-step type: history is measured in **rows**, not in days.
`datafeed.instrument.history(instrument, as_of_time, count)` returns the last `count` observations at
or before `as_of_time`, and `pulse_index.pulse_history(pulse_index.index - 1)` names the previous
pulse. Both count in pulses, so they follow the run's own cadence (daily or hourly) instead of
assuming one.

**Related:** [Architecture and the pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.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.