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

> API reference for pulse.core.strategy.

## `Strategy`

```python theme={null}
Strategy(
    underlying_id: str | Sequence[str],
    name: str = 'My Strategy',
    description: str = 'A custom trading strategy.',
)
```

A backtest strategy: subclass it, implement `on_update()` and trade through `self`.

`on_update()` runs once per pulse, after the clock has advanced and before the broker
fills that pulse's orders. The collaborators it reaches for (`datafeed`, `resolver`,
`broker`, `portfolio`, `pulse_index`) are attached by the `TradingEnvironment` when
the run starts, which is why they are not constructor arguments.

Initialize the Strategy with its underlying id(s), a name and a description.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `underlying_id` | `str \| Sequence[str]` | One id or several, each wrapped into an `UnderlyingID` by `to_underlying_ids`, so `self.underlying_id` is always a list of them whatever was passed in. | *required* |
| `name` | `str` | Display name. | `'My Strategy'` |
| `description` | `str` | Free-text description. | `'A custom trading strategy.'` |

### `Strategy.id`

`property`

```python theme={null}
Strategy.id: str
```

Get the unique identifier of the strategy.

### `Strategy.underlying_id`

`property`

```python theme={null}
Strategy.underlying_id: list[UnderlyingID]
```

Get the underlying ID(s) of the strategy.

### `Strategy.pulse_index`

`property`

```python theme={null}
Strategy.pulse_index: PulseIndex
```

Get the pulse index of the strategy.

### `Strategy.last_pulse`

`property`

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

Get the last pulse time of the strategy.

### `Strategy.open_trades`

`property`

```python theme={null}
Strategy.open_trades: list[Trade]
```

Get the list of open trades in the portfolio.

### `Strategy.has_open_trades`

`property`

```python theme={null}
Strategy.has_open_trades: bool
```

Check if there are any open trades in the portfolio.

### `Strategy.trades`

`property`

```python theme={null}
Strategy.trades: list[Trade]
```

Get the list of all trades in the portfolio.

### `Strategy.broker`

`property`

```python theme={null}
Strategy.broker: Broker
```

Get the broker associated with the strategy.

### `Strategy.portfolio`

`property`

```python theme={null}
Strategy.portfolio: Portfolio
```

Get the portfolio associated with the strategy.

### `Strategy.current_equity`

`property`

```python theme={null}
Strategy.current_equity: float
```

Get the current equity of the portfolio.

### `Strategy.initial_equity`

`property`

```python theme={null}
Strategy.initial_equity: float
```

Get the strategy's starting capital.

### `Strategy.pnl`

`property`

```python theme={null}
Strategy.pnl: float
```

Cumulative net PnL of the strategy.

`current_equity - initial_equity`. Includes the impact of fees
(because both terms are post-fee).

### `Strategy.pnl_pct`

`property`

```python theme={null}
Strategy.pnl_pct: float
```

Cumulative PnL as a fraction of the account equity right now.

`pnl / abs(current_equity)`. The denominator is the *current*
portfolio equity, so this is the live, sizing-aware return of the whole
strategy. Same basis as `TradesSummary.pnl_pct`; **differs from**
`Trade.pnl_pct`, which is fixed to each trade's equity-at-open
snapshot. `abs` keeps the sign coming from `pnl`. Returns `0.0` if
`current_equity` is `0`.

### `Strategy.pnl_pct_of_initial_equity`

`property`

```python theme={null}
Strategy.pnl_pct_of_initial_equity: float
```

Cumulative PnL as a fraction of the strategy's starting capital.

`pnl / abs(initial_equity)`. Stable denominator across the entire
run, mirroring `Trade.pnl_pct_of_initial_equity` and
`TradesSummary.pnl_pct_of_initial_equity`. Returns `0.0` if
`initial_equity` is `0`.

### `Strategy.datafeed`

`property`

```python theme={null}
Strategy.datafeed: DataFeed
```

Get the datafeed associated with the strategy.

### `Strategy.resolver`

`property`

```python theme={null}
Strategy.resolver: ResolverRegistry
```

Get the resolver associated with the strategy.

### `Strategy.stats`

`property`

```python theme={null}
Strategy.stats: Stats
```

Get the statistics for the strategy.

### `Strategy.set_datafeed`

```python theme={null}
Strategy.set_datafeed(datafeed: DataFeed) -> None
```

Set the datafeed for the strategy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `datafeed` | `DataFeed` | The DataFeed to set for the strategy. | *required* |

### `Strategy.set_resolver`

```python theme={null}
Strategy.set_resolver(resolver: ResolverRegistry) -> None
```

Set the resolver for the strategy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `resolver` | `ResolverRegistry` | The ResolverRegistry to set for the strategy. | *required* |

### `Strategy.set_broker`

```python theme={null}
Strategy.set_broker(broker: Broker) -> None
```

Set the broker for the strategy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `broker` | [`Broker`](https://docs.allasso.ch/dev/pulse/api/core/broker#broker) | The Broker to set for the strategy. | *required* |

### `Strategy.set_portfolio`

```python theme={null}
Strategy.set_portfolio(portfolio: Portfolio) -> None
```

Set the portfolio for the strategy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `portfolio` | [`Portfolio`](https://docs.allasso.ch/dev/pulse/api/core/portfolio#portfolio) | The Portfolio to set for the strategy. | *required* |

### `Strategy.set_pulse_index`

```python theme={null}
Strategy.set_pulse_index(pulse_index: PulseIndex) -> None
```

Set the pulse index for the strategy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `pulse_index` | [`PulseIndex`](https://docs.allasso.ch/dev/pulse/api/core/time#pulseindex) | The PulseIndex to set for the strategy. | *required* |

### `Strategy.on_update`

```python theme={null}
Strategy.on_update() -> None
```

This method should be implemented in the Strategy subclass to define the strategy's logic.

### `Strategy.pulse`

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

Pulse the strategy, executing trades.

### `Strategy.create_order`

```python theme={null}
Strategy.create_order(
    underlying_id: str,
    instrument_type: InstrumentTypeComb,
    expiration_date: datetime | None = None,
    strike: float | None = None,
    quantity: float | None = None,
    tags: list[str] | None = None,
    fill_price: float | None = None,
    is_lots: bool = False,
)
```

Place a market order. It is filled on the same pulse, at the current pulse's market data.

This is just a wrapper around the broker's create\_order method.

You can also use::

```python theme={null}
self.broker.create_order(
    pulse_index=self.pulse_index,
    quantity=quantity,
    instrument=create_instrument(
        underlying_id=underlying_id,
        instrument_type=instrument_type,
        expiration_date=expiration_date,
        strike=strike,
    ),
)
```

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `underlying_id` | `str` | Underlying id for the instrument. | *required* |
| `instrument_type` | `InstrumentTypeComb` | Instrument type (call, put, future or spot). | *required* |
| `expiration_date` | `datetime \| None` | Expiration date of the option/future. Spot takes none. | `None` |
| `strike` | `float \| None` | Strike price of the option. Futures and spot take none. | `None` |
| `quantity` | `float \| None` | Quantity. Required (keyword for spot, e.g. `self.create_order("EQT.AAPL.NDAQ", "s", quantity=10)`). | `None` |

### `Strategy.buy`

```python theme={null}
Strategy.buy(
    underlying_id: str,
    instrument_type: InstrumentTypeComb,
    expiration_date: datetime | None = None,
    strike: float | None = None,
    quantity: float | None = None,
    tags: list[str] | None = None,
    fill_price: float | None = None,
    is_lots: bool = False,
) -> None
```

Buy an instrument. The order is filled on the same pulse, at the current pulse's market data.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `underlying_id` | `str` | Underlying id for the instrument. | *required* |
| `instrument_type` | `InstrumentTypeComb` | Instrument type (call, put, future or spot). | *required* |
| `expiration_date` | `datetime \| None` | Expiration date of the option/future. Spot takes none. | `None` |
| `strike` | `float \| None` | Strike price of the option. Futures and spot take none. | `None` |
| `quantity` | `float \| None` | Quantity. Required (keyword for spot, e.g. `self.buy("EQT.AAPL.NDAQ", "s", quantity=10)`). | `None` |

### `Strategy.sell`

```python theme={null}
Strategy.sell(
    underlying_id: str,
    instrument_type: InstrumentTypeComb,
    expiration_date: datetime | None = None,
    strike: float | None = None,
    quantity: float | None = None,
    tags: list[str] | None = None,
    fill_price: float | None = None,
    is_lots: bool = False,
) -> None
```

Sell an instrument. The order is filled on the same pulse, at the current pulse's market data.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `underlying_id` | `str` | Underlying id for the instrument. | *required* |
| `instrument_type` | `InstrumentTypeComb` | Instrument type (call, put, future or spot). | *required* |
| `expiration_date` | `datetime \| None` | Expiration date of the option/future. Spot takes none. | `None` |
| `strike` | `float \| None` | Strike price of the option. Futures and spot take none. | `None` |
| `quantity` | `float \| None` | Quantity. Required (keyword for spot, e.g. `self.sell("EQT.AAPL.NDAQ", "s", quantity=10)`). | `None` |

### `Strategy.close_all`

```python theme={null}
Strategy.close_all() -> None
```

Close all open trades in the portfolio.

**Raises**

| Type | Description |
| - | - |
| `ValueError` | If the portfolio is not set. |

### `Strategy.calculate_stats`

```python theme={null}
Strategy.calculate_stats(
    risk_free_rate: float | None = None,
    pulses_per_year: float | None = None,
) -> Stats
```

Get the statistics for the strategy.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `risk_free_rate` | `float` | The risk-free rate to use in calculations. Defaults to 0. | `None` |
| `pulses_per_year` | `float` | Pulses per year for annualizing Sharpe/Sortino. When `None`, derived from `self.pulse_index.pulses_per_year` (the live cadence). | `None` |

**Returns**

| Name | Type | Description |
| - | - | - |
| `Stats` | [`Stats`](https://docs.allasso.ch/dev/pulse/api/metrics/stats#stats) | The statistics for the strategy. |

### `Strategy.get_trades_by_tags`

```python theme={null}
Strategy.get_trades_by_tags(
    tags: list[str],
    match_all: bool = False,
) -> list[Trade]
```

Get all trades with specific tags.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `tags` | `str \| list[str]` | The tag or list of tags to filter trades by. | *required* |

**Returns**

| Type | Description |
| - | - |
| [`list[Trade]`](https://docs.allasso.ch/dev/pulse/api/core/trade#trade) | list\[Trade]: List of trades with the specified tag. |

### `Strategy.close_trades_by_tags`

```python theme={null}
Strategy.close_trades_by_tags(
    tags: list[str],
    match_all: bool = False,
) -> None
```

Close all open trades with specific tags.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `tags` | `str \| list[str]` | The tag or list of tags to filter trades by. | *required* |

### `Strategy.calculate_trades_summary`

```python theme={null}
Strategy.calculate_trades_summary(
    trades: list[Trade],
) -> TradesSummary
```

Aggregate a group of trades into one `TradesSummary`, marked at the current pulse.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `trades` | [`list[Trade]`](https://docs.allasso.ch/dev/pulse/api/core/trade#trade) | The trades to aggregate. Must not be empty. | *required* |

**Returns**

| Name | Type | Description |
| - | - | - |
| `TradesSummary` | [`TradesSummary`](https://docs.allasso.ch/dev/pulse/api/core/models#tradessummary) | Count and notionals, PnL against both the live and the starting equity, `min_dte`, the average `iv`, and the greeks. The `*_contract` greeks are each leg's per-unit greek times its raw `quantity`, so a lot-sized leg contributes lots and nothing here is contract-size scaled; `delta`, `quick_delta` and `gamma` are those totals over the smallest leg's absolute `quantity`, so a structure reads per lot. `theta` and `vega` are the same totals, with no per-lot twin. `iv` is `None` when no leg carries one, and `min_dte` is `math.inf` when nothing in the group expires. |

**Raises**

| Type | Description |
| - | - |
| `ValueError` | If `trades` is empty. |

### `Strategy.get_trades_summary_by_tags`

```python theme={null}
Strategy.get_trades_summary_by_tags(
    tags: list[str],
    match_all: bool = False,
) -> TradesSummary
```

Get a summary of trades with specific tags.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `tags` | `str \| list[str]` | The tag or list of tags to filter trades by. | *required* |

**Returns**

| Name | Type | Description |
| - | - | - |
| `TradesSummary` | [`TradesSummary`](https://docs.allasso.ch/dev/pulse/api/core/models#tradessummary) | Summary of trades with the specified tag. |

## `to_underlying_ids`

```python theme={null}
to_underlying_ids(ids: str | Sequence[str]) -> list[UnderlyingID]
```

Wrap one id or several into `UnderlyingID`s, in the order given.

A plain `str` gains the default declaration; an already declared id keeps its
`variable_contract_size`. A single `UnderlyingID` is itself a `str`, which is why the
`isinstance` branch treats it as one id rather than as a sequence of characters.


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