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

# pulse.core.time

> API reference for pulse.core.time.

## `PulseIndex`

```python theme={null}
PulseIndex(datetimes: list[datetime])
```

PulseIndex is a class that manages a list of datetimes and allows pulsing through them.
It keeps every component in sync with the current datetime index.

Initialize the PulseIndex with a list of datetimes.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `datetimes` | `list[datetime]` | List of datetimes to initialize the index. | *required* |

### `PulseIndex.datetimes`

`property`

```python theme={null}
PulseIndex.datetimes: list[datetime]
```

Get the list of datetimes in the pulse index.

**Returns**

| Type | Description |
| - | - |
| `list[datetime]` | list\[datetime]: List of datetimes in the pulse index. |

### `PulseIndex.last_pulse`

`property`

```python theme={null}
PulseIndex.last_pulse: datetime
```

Get the last pulse time.

**Returns**

| Name | Type | Description |
| - | - | - |
| `datetime` | `datetime` | Last pulse time. |

### `PulseIndex.pulses_per_year`

`cached` `property`

```python theme={null}
PulseIndex.pulses_per_year: float
```

Cadence rate as periods-per-calendar-year.

Used to annualize per-pulse return metrics (Sharpe, Sortino, etc.).
Formula: `len(datetimes) * 365 / span_calendar_days`.

Examples: SPX daily backtest (\~252 datetimes spanning \~365 days) -> \~252.
BTC hourly 24/7 (\~8760 over 365 days) -> \~8760. SPX hourly 6.5h sessions
(\~1638 over 365 days) -> \~1638.

Cached on first access. Invalidated by `append`.

### `PulseIndex.index`

`property`

```python theme={null}
PulseIndex.index: int
```

Get the current index in the pulse index.
Returns:
int: Current index in the pulse index.

### `PulseIndex.__clear_cache`

```python theme={null}
PulseIndex.__clear_cache() -> None
```

Drop the cached `pulses_per_year` so the next access recomputes over the new calendar.

`functools.cached_property` stores its value in the instance `__dict__` under the
property's own name (shadowing the descriptor); popping it re-exposes the getter. No-op
when the property was never accessed.

### `PulseIndex.append`

```python theme={null}
PulseIndex.append(dt: datetime) -> None
```

Append a new datetime to the pulse index.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `datetime` | `datetime` | The datetime to append. | *required* |

### `PulseIndex.extend`

```python theme={null}
PulseIndex.extend(datetimes: list[datetime]) -> None
```

Append the datetimes past the current last one (backtest continuation).

Tail-only: entries at or before the current last datetime are ignored, so passing a full
re-derived calendar and passing just the new datetimes both work. `datetimes` is assumed
sorted. The cursor stays where it is, so a finished run resumes on the first new datetime.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `datetimes` | `list[datetime]` | Sorted datetimes; only those after the current last are appended. | *required* |

### `PulseIndex.pulse`

```python theme={null}
PulseIndex.pulse() -> None
```

Advance the pulse index to the next datetime.

### `PulseIndex.has_next`

```python theme={null}
PulseIndex.has_next() -> bool
```

Check if there is a next pulse.

**Returns**

| Name | Type | Description |
| - | - | - |
| `bool` | `bool` | True if there is a next pulse, False otherwise. |

### `PulseIndex.peek_next`

```python theme={null}
PulseIndex.peek_next() -> datetime | None
```

The datetime the next `pulse` would land on, or `None` at the end.

Lets callers test "is this the next pulse" without reaching into the index arithmetic.

**Returns**

| Type | Description |
| - | - |
| `datetime \| None` | datetime \| None: `datetimes[index + 1]` when there is a next pulse, else `None`. |

### `PulseIndex.advance_to`

```python theme={null}
PulseIndex.advance_to(target: datetime) -> None
```

Fast-forward the cursor to the latest datetime `<= target` (assumes sorted datetimes).

A one-shot seek used to skip a leading span without pulsing through it step by step. When
`target` precedes the first datetime the cursor stays at index 0; when it is at or past the
last, it lands on the last.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `target` | `datetime` | The datetime to seek at or before. | *required* |

### `PulseIndex.pulse_history`

```python theme={null}
PulseIndex.pulse_history(index: int) -> datetime
```

Get the pulse history at a specific index.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `index` | `int` | Index of the pulse history to retrieve. | *required* |

**Returns**

| Name | Type | Description |
| - | - | - |
| `datetime` | `datetime` | Pulse history at the specified index. |

## `common_settlements`

```python theme={null}
common_settlements(
    datafeed: DataFeed,
    underlying_ids: Sequence[UnderlyingID],
    start_datetime: datetime | None = None,
    end_datetime: datetime | None = None,
) -> list[datetime]
```

The settlement datetimes every one of `underlying_ids` has: a pulse calendar.

Per underlying this is pdc's `available_settlements(uid, unified=True)`, which already
intersects that underlying's instrument families and returns them sorted and deduplicated.
Intersecting across underlyings is the one step pdc does not offer, so it lives here, once:
the engine's `EnvironmentBuilder` and the framework's executor and shadow evaluation all
call this rather than each keeping a copy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `datafeed` | `DataFeed` | The feed whose reference provider holds the calendars. | *required* |
| `underlying_ids` | `Sequence[UnderlyingID]` | The underlyings to intersect, at least one. | *required* |
| `start_datetime` | `datetime \| None` | Inclusive lower bound, handed to pdc, which bisects each calendar. Defaults to None (no bound). | `None` |
| `end_datetime` | `datetime \| None` | Inclusive upper bound. Defaults to None. | `None` |

**Raises**

| Type | Description |
| - | - |
| `ValueError` | for no ids, or when the underlyings share no settlement datetime in range. |

## `pulses_per_year`

```python theme={null}
pulses_per_year(datetimes: list[datetime]) -> float
```

Cadence rate of `datetimes` as periods-per-calendar-year.

Formula: `len(datetimes) * 365 / span_calendar_days`. Falls back to 252.0
(`pulse.metrics._core.NUMBER_OF_TRADING_DAYS_PER_YEAR`, the daily-cadence default;
not imported here to keep `pulse.core.time` dependency-free) for fewer than two datetimes
or a non-positive span. The single definition behind `PulseIndex.pulses_per_year`,
also usable on any raw datetime list (e.g. an aggregated pool curve).

## `aggregate_per_pulse_to_daily`

```python theme={null}
aggregate_per_pulse_to_daily(
    values: list[float],
    datetimes: list[datetime],
    op: Literal['sum', 'compound', 'last'] = 'sum',
) -> tuple[list[date], list[float], list[datetime]]
```

Group per-pulse values by date and collapse each group.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `values` | `list[float]` | Per-pulse values aligned to `datetimes`. | *required* |
| `datetimes` | `list[datetime]` | Per-pulse timestamps. | *required* |
| `op` | `Literal['sum', 'compound', 'last']` | "sum" for additive (abs P\&L); "compound" for multiplicative pct returns (prod(1+r)-1); "last" for level series (e.g. equity end-of-day). | `'sum'` |

**Returns**

| Type | Description |
| - | - |
| `tuple[list[date], list[float], list[datetime]]` | tuple\[list\[date], list\[float], list\[datetime]]: (unique dates, aggregated values, last per-pulse datetime per date) in chronological order. |


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