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

# Quickstart Guide

> Pulse is a flexible Python backtesting framework designed for systematic trading strategies, particularly focused on options and derivatives trading.

It provides comprehensive tools for strategy development, execution simulation, and performance analysis with access to real market data.

Key features of Pulse include:

* **Datafeed** - Access market data for options, futures, and other instruments
* **Resolver** - Convert relative parameters (delta, moneyness) into concrete values
* **Strategy Framework** - Build custom trading strategies with maximum flexibility
* **Execution Engine** - Run backtests with realistic order execution and portfolio management
* **Performance Analytics** - Track P\&L, risk metrics, and equity curves

## Resolver

The Resolver component translates relative parameters into concrete values. For example, it can convert a "25-delta put" specification into an actual strike price at a specific point in time and expiration date.

```python theme={null}
import datetime

from pulse import (
    Option,
    InstrumentType,
    PeriodID,
    PeriodType,
    create_local_components,
)

AS_OF_TIME = datetime.datetime(2020, 1, 2)

# One call builds both a local datafeed and a local resolver registry over PDC_PATH.
# `create_local_datafeed()` and `create_local_resolver_registry()` build them separately.
datafeed, resolver = create_local_components()
```

### Resolving expiration dates

The expiry resolver finds expiration dates based on criteria such as minimum days to expiration (DTE) and Nth front month. In this example, we're finding the first monthly expiration for call options on Brent crude oil that has at least 14 days to expiration as of January 2, 2020.

`min_dte` is required: there is no implicit default, so every resolved expiry states how much time it needs.

```python theme={null}
expiration_date = resolver.expiry.relative(
    underlying_id="COM.BRN",
    as_of_time=AS_OF_TIME,
    period_type=PeriodType.MONTH,
    instrument_type=InstrumentType.CALL,
    nth=1,
    period_id=PeriodID.ALL,
    min_dte=14,
)
expiration_date
```

```text Output theme={null}
[datetime.datetime(2020, 1, 28, 0, 0)]
```

### Resolving strikes

The strike resolver converts delta values into actual strike prices. Here we're finding the strike price for a 25-delta put option using the expiration date we resolved above.

```python theme={null}
strike = resolver.strike.delta.resolve(
    underlying_id="COM.BRN",
    as_of_time=AS_OF_TIME,
    expiration_date=expiration_date[0], # Previously resolved expiration date
    instrument_type=InstrumentType.PUT,
    strike_value=0.25,
)
print(f"Strike for 25-delta put for {expiration_date[0].date()} on {AS_OF_TIME.date()} is: {strike}")
```

```text Output theme={null}
Strike for 25-delta put for 2020-01-28 on 2020-01-02 is: 63.0
```

## Datafeed

The Datafeed component provides access to financial market data, including options, futures and spot instruments. It ensures no forward-looking bias by requiring an `as_of_time` parameter for all data requests. `as_of_time` represents the current time in the backtest, and can be accessed in strategies via `self.last_pulse`. It is matched **exactly** against the prepared settlement datetimes, so it must be a datetime the underlying actually has (`datafeed.reference.available_settlements(...)` lists them).

```python theme={null}
# `create_local_components()` above already returned one; this is how you build a datafeed on its own.
from pulse import create_local_datafeed

datafeed = create_local_datafeed()
```

```python theme={null}
instrument = Option(
    underlying_id="COM.BRN",
    instrument_type=InstrumentType.PUT,
    strike=strike,
    expiration_date=expiration_date[0]
)
observation = datafeed.instrument.last(
    instrument=instrument,
    as_of_time=AS_OF_TIME
)
pprint(observation)
```

```text Output theme={null}
OptionValues(as_of_time=datetime.datetime(2020, 1, 2, 0, 0),
             instrument_type=<InstrumentType.PUT: 'p'>,
             price=0.7342112980863558,
             expiration_date=datetime.datetime(2020, 1, 28, 0, 0),
             underlying_expiration_date=datetime.datetime(2020, 1, 31, 0, 0),
             dte=26.0,
             tte=0.0712328776717186,
             open_interest=5801.0,
             volume=1316.0,
             strike=63.0,
             underlying_price=66.25,
             iv=0.28231304368126164,
             delta=-0.23517301144693192,
             quick_delta=-0.22163897559718085,
             gamma=0.061586291622006684,
             theta=-0.028724946193275695,
             vega=0.05435845270227446)
```

```python theme={null}
observation = datafeed.smile.last(
    underlying_id="COM.BRN",
    expiration_date=expiration_date[0],
    as_of_time=AS_OF_TIME
)
pprint(observation)
```

```text Output theme={null}
SmileValues(as_of_time=datetime.datetime(2020, 1, 2, 0, 0),
            expiration_date=datetime.datetime(2020, 1, 28, 0, 0),
            underlying_expiration_date=datetime.datetime(2020, 1, 31, 0, 0),
            dte=26.0,
            tte=0.0712328776717186,
            underlying_price=66.25,
            instrument_type=[<InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
                             <InstrumentType.CALL: 'c'>,
                             <InstrumentType.PUT: 'p'>,
… (2366 more lines)
```

## Simple strategy

Now we'll implement a complete trading strategy that demonstrates how to combine all Pulse components. This strategy will sell put options monthly based on delta targeting.

### Importing Strategy Components

These imports provide the core classes and functions needed to build and execute trading strategies.

```python theme={null}
from pulse import (
    InstrumentType,
    PeriodID,
    PeriodType,
    Strategy,
    run_sequentially,
)
from pulse.charts import plot_equity
```

### Strategy Implementation

The `ShortPut` class demonstrates a complete trading strategy implementation. It inherits from the `Strategy` base class and implements custom trading logic in the `on_update()` method.

Key features of this strategy:

* **Monthly rebalancing**: Opens new positions at the start of each month
* **Delta targeting**: Sells put options at a specified delta value
* **Position sizing**: Uses a percentage of available equity for position sizing
* **Automatic expiration management**: Resolves expiration dates based on minimum DTE criteria

```python theme={null}
class ShortPut(Strategy):
    def __init__(
        self,
        underlying_id: str,
        delta: float = 0.5,
        expiry_nearest: int = 1,
        min_dte: int = 30,
        equity_percentage: float = 1,
        lot_size: int = 1,
    ):
        super().__init__(
            name=f"Short {delta * 100:.0f}d Put Strategy",
            description=f"A simple strategy that sells a {delta * 100:.0f}d put option on a given underlying asset.",
            underlying_id=underlying_id,
        )
        self._delta = delta
        self._expiry_nearest = expiry_nearest
        self._min_dte = min_dte
        self._equity_percentage = equity_percentage
        self._lot_size = lot_size

        self._previous_month = None

    def on_update(self) -> None:
        # Check if the month has changed since the last pulse
        # since the strategy opens and closes a trade once at the
        # start of each month
        if self._previous_month != self.last_pulse.month:
            # Close all previous trades
            self.close_all()

            # Find the expriation date given the min_dte and expiry_nearest
            expiration_date = self.resolver.expiry.relative(
                underlying_id=self.underlying_id[0],
                as_of_time=self.last_pulse,
                period_type=PeriodType.MONTH,
                instrument_type=InstrumentType.PUT,
                nth=self._expiry_nearest,
                period_id=PeriodID.ALL,
                min_dte=self._min_dte,
            )[0]
            # Find the strike price based on the delta
            strike = self.resolver.strike.delta.resolve(
                underlying_id=self.underlying_id[0],
                as_of_time=self.last_pulse,
                expiration_date=expiration_date,
                instrument_type=InstrumentType.PUT,
                strike_value=self._delta,
            )
            # Create the instrument for the call option
            instrument = Option(
                underlying_id=self.underlying_id[0],
                instrument_type=InstrumentType.PUT,
                strike=strike,
                expiration_date=expiration_date,
            )

            # Get the current underlying price of instrument
            underlying_price: float = self.datafeed.instrument.last(
                instrument, self.last_pulse
            ).underlying_price
            # Calculate desired size based on equity percentage and underlying price
            desired_size = (
                self.current_equity * self._equity_percentage / underlying_price
            )
            # Round to nearest lot size and ensure it's negative for selling
            actual_size = round(desired_size / self._lot_size) * self._lot_size
            self.broker.create_order(
                self.pulse_index,
                instrument,
                -actual_size,
            )
            self._previous_month = self.last_pulse.month
```

### Strategy Execution

To run a backtest, we initialize the strategy with specific parameters and pass it to the `run_sequentially` function along with initial capital.

```python theme={null}
strategy = ShortPut(
    underlying_id="COM.BRN",
    delta=0.4,
    expiry_nearest=1,
    min_dte=30,
    equity_percentage=0.5,
)
result = run_sequentially(
    [strategy],
    initial_equity=1_000_000,
)[0]

print(f"Strategy run completed successfully in {result.execution_time} seconds.")
```

```text Output theme={null}
Strategy run completed successfully in 10.430670022964478 seconds.
```

### Visualizing Results

After execution, we can visualize the strategy's performance using the built-in charting functionality. This creates an interactive equity curve showing how the strategy's value changed over time.

You can easily access detailed performance metrics and trade logs for further analysis.

```python theme={null}
plot_equity(result.strategy)
```

![Chart output 1](https://mintcdn.com/allasso/5PMuHlzYzX1FYPYw/images/pulse/notebooks/quickstart-1.png?fit=max\&auto=format\&n=5PMuHlzYzX1FYPYw\&q=85\&s=b4857f4eda1dfe7aa6e886526ea7a0dd)

#### Accessign Performance Metrics

```python theme={null}
strategy.stats
```

```text Output theme={null}
Strategy Metrics:
Start Date: 				2015-02-02 00:00:00
End Date: 				2026-09-22 00:00:00
Duration: 				4251 days, 0:00:00
***********************************************************
Total Return (%): 			51.48
CAGR (%): 				3.63
***********************************************************
Start Equity ($): 			1000000.00
End Equity ($): 			1514794.95
Diff ($): 				514794.95
***********************************************************
Annualized Sharpe Ratio: 		0.37
Calmar Ratio: 				0.11
Annualized Sortino Ratio: 		0.47
***********************************************************
Daily Mean Return (%): 			0.01
Daily Volatility (%): 			0.59
Best Daily Return (%): 			4.02
Best Day Date: 				2020-03-19 00:00:00
Worst Daily Return (%): 		-9.51
Worst Day Date: 			2020-03-09 00:00:00
***********************************************************
Monthly Mean Return (%): 		0.33
Monthly Volatility annualized (%): 	9.38
Best Monthly Return (%): 		5.35
Best Month Date: 			2020-05
Worst Monthly Return (%): 		-19.10
Worst Month Date: 			2020-03
MTD Return (%): 			1.44
3-Month Return (%): 			5.65
Positive Months (%): 			69.78
Average Up Month (%): 			1.53
Average Down Month (%): 		-2.46
***********************************************************
6-Month Return (%): 			4.20
Year-to-Date Return (%): 		10.92
1-Year Return (%): 			12.00
Yearly Mean Return (%): 		5.17
Yearly Volatility annualized (%): 	9.41
… (32 more lines)
```

#### Accessing P\&L History

```python theme={null}
strategy.portfolio.pulse_total_pnl_history[-3:]
```

```text Output theme={null}
[93.97613362408379, -4831.553384273949, -3165.1952764858106]
```

```python theme={null}
strategy.portfolio.equity_pct_change_history[-3:]
```

```text Output theme={null}
[6.171686754630201e-05, -0.0031728261915784373, -0.0020851636239311855]
```

```python theme={null}
strategy.portfolio.equity_history[-3:]
```

```text Output theme={null}
[1522791.6981706258, 1517960.1447863518, 1514794.949509866]
```

#### Accessing Trades

```python theme={null}
strategy.trades
```

```text Output theme={null}
[<Trade entry: 2015-02-03 00:00:00; exit: 2015-03-02 00:00:00; Instrument: COM.BRN|p|57.0|2015-03-11 00:00:00; Quantity: -8475; PnL: -2335.869454876092; Cummulative PnL: 13957.14063337827>,
 <Trade entry: 2015-03-02 00:00:00; exit: 2015-04-01 00:00:00; Instrument: COM.BRN|p|59.0|2015-04-10 00:00:00; Quantity: -8442; PnL: 13062.779007902827; Cummulative PnL: 2415.830776660465>,
 <Trade entry: 2015-04-01 00:00:00; exit: 2015-05-01 00:00:00; Instrument: COM.BRN|p|57.0|2015-05-11 00:00:00; Quantity: -8621; PnL: 268.3421437991561; Cummulative PnL: 25342.839181214677>,
 <Trade entry: 2015-05-01 00:00:00; exit: 2015-06-01 00:00:00; Instrument: COM.BRN|p|66.0|2015-06-10 00:00:00; Quantity: -7745; PnL: -2591.921592085358; Cummulative PnL: 2019.8611828185008>,
 <Trade entry: 2015-06-01 00:00:00; exit: 2015-07-01 00:00:00; Instrument: COM.BRN|p|64.0|2015-07-13 00:00:00; Quantity: -7986; PnL: -8257.759946611128; Cummulative PnL: -4198.878751221234>,
 <Trade entry: 2015-07-01 00:00:00; exit: 2015-08-03 00:00:00; Instrument: COM.BRN|p|61.0|2015-08-11 00:00:00; Quantity: -8386; PnL: -22558.72230371388; Cummulative PnL: -80105.36434830425>,
 <Trade entry: 2015-08-03 00:00:00; exit: 2015-09-01 00:00:00; Instrument: COM.BRN|p|49.0|2015-09-10 00:00:00; Quantity: -9783; PnL: -9402.633272810639; Cummulative PnL: 2295.0392020571053>,
 <Trade entry: 2015-09-01 00:00:00; exit: 2015-10-01 00:00:00; Instrument: COM.BRN|p|49.0|2015-10-12 00:00:00; Quantity: -9642; PnL: -3578.3118817478457; Cummulative PnL: 6996.063512676816>,
 <Trade entry: 2015-10-01 00:00:00; exit: 2015-11-02 00:00:00; Instrument: COM.BRN|p|47.0|2015-11-10 00:00:00; Quantity: -10049; PnL: -1169.586590310949; Cummulative PnL: 12961.797858699023>,
 <Trade entry: 2015-11-02 00:00:00; exit: 2015-12-01 00:00:00; Instrument: COM.BRN|p|48.0|2015-12-11 00:00:00; Quantity: -9906; PnL: -1677.1454698757848; Cummulative PnL: -22438.797571504794>,
 <Trade entry: 2015-12-01 00:00:00; exit: 2016-01-04 00:00:00; Instrument: COM.BRN|p|44.0|2016-01-11 00:00:00; Quantity: -10656; PnL: -763.7687269249802; Cummulative PnL: -51162.874323498945>,
 <Trade entry: 2016-01-04 00:00:00; exit: 2016-02-01 00:00:00; Instrument: COM.BRN|p|37.0|2016-02-24 00:00:00; Quantity: -11812; PnL: -15926.919844526756; Cummulative PnL: -23144.13321524099>,
 <Trade entry: 2016-02-01 00:00:00; exit: 2016-03-01 00:00:00; Instrument: COM.BRN|p|34.0|2016-03-24 00:00:00; Quantity: -12858; PnL: 2012.6625207470431; Cummulative PnL: 21407.576948084476>,
 <Trade entry: 2016-03-01 00:00:00; exit: 2016-04-01 00:00:00; Instrument: COM.BRN|p|36.0|2016-04-26 00:00:00; Quantity: -12067; PnL: -4092.3332191869995; Cummulative PnL: 18645.558185743965>,
 <Trade entry: 2016-04-01 00:00:00; exit: 2016-05-02 00:00:00; Instrument: COM.BRN|p|38.0|2016-05-25 00:00:00; Quantity: -11884; PnL: -846.5889156336193; Cummulative PnL: 23384.406994349134>,
 <Trade entry: 2016-05-02 00:00:00; exit: 2016-06-01 00:00:00; Instrument: COM.BRN|p|45.0|2016-06-27 00:00:00; Quantity: -10264; PnL: -669.4934080582341; Cummulative PnL: 21313.95045134524>,
 <Trade entry: 2016-06-01 00:00:00; exit: 2016-07-01 00:00:00; Instrument: COM.BRN|p|49.0|2016-07-26 00:00:00; Quantity: -9675; PnL: 3431.609407396939; Cummulative PnL: 10213.096114482289>,
 <Trade entry: 2016-07-01 00:00:00; exit: 2016-08-01 00:00:00; Instrument: COM.BRN|p|50.0|2016-08-25 00:00:00; Quantity: -9594; PnL: -12501.227671278979; Cummulative PnL: -54266.54608013181>,
 <Trade entry: 2016-08-01 00:00:00; exit: 2016-09-01 00:00:00; Instrument: COM.BRN|p|41.0|2016-09-27 00:00:00; Quantity: -11011; PnL: -1288.5749668401552; Cummulative PnL: 18528.379654529388>,
 <Trade entry: 2016-09-01 00:00:00; exit: 2016-10-03 00:00:00; Instrument: COM.BRN|p|45.0|2016-10-26 00:00:00; Quantity: -10315; PnL: 1650.7802195180595; Cummulative PnL: 22625.774474211215>,
 <Trade entry: 2016-10-03 00:00:00; exit: 2016-11-01 00:00:00; Instrument: COM.BRN|p|50.0|2016-11-25 00:00:00; Quantity: -9378; PnL: -2048.3438106450894; Cummulative PnL: -8631.994523604433>,
 <Trade entry: 2016-11-01 00:00:00; exit: 2016-12-01 00:00:00; Instrument: COM.BRN|p|48.0|2016-12-22 00:00:00; Quantity: -9808; PnL: -20.71927166084987; Cummulative PnL: 15290.887952415911>,
 <Trade entry: 2016-12-01 00:00:00; exit: 2017-01-02 00:00:00; Instrument: COM.BRN|p|53.0|2017-01-26 00:00:00; Quantity: -8918; PnL: 0.11954335398758076; Cummulative PnL: 27307.926680929122>,
 <Trade entry: 2017-01-02 00:00:00; exit: 2017-02-01 00:00:00; Instrument: COM.BRN|p|56.0|2017-02-23 00:00:00; Quantity: -8704; PnL: 5279.113387515123; Cummulative PnL: 6329.164517614181>,
 <Trade entry: 2017-02-01 00:00:00; exit: 2017-03-01 00:00:00; Instrument: COM.BRN|p|56.0|2017-03-28 00:00:00; Quantity: -8769; PnL: -11.301660690300121; Cummulative PnL: 7893.071360937622>,
 <Trade entry: 2017-03-01 00:00:00; exit: 2017-04-03 00:00:00; Instrument: COM.BRN|p|56.0|2017-04-25 00:00:00; Quantity: -8957; PnL: -2448.2739695608125; Cummulative PnL: -14080.387295260492>,
 <Trade entry: 2017-04-03 00:00:00; exit: 2017-05-01 00:00:00; Instrument: COM.BRN|p|52.0|2017-05-25 00:00:00; Quantity: -9393; PnL: -2727.885223611926; Cummulative PnL: -559.1967277041772>,
 <Trade entry: 2017-05-01 00:00:00; exit: 2017-06-01 00:00:00; Instrument: COM.BRN|p|51.0|2017-06-27 00:00:00; Quantity: -9671; PnL: 484.82087970116714; Cummulative PnL: 2114.895196019708>,
 <Trade entry: 2017-06-01 00:00:00; exit: 2017-07-03 00:00:00; Instrument: COM.BRN|p|50.0|2017-07-26 00:00:00; Quantity: -9829; PnL: 5329.371088921637; Cummulative PnL: 2268.297775346625>,
 <Trade entry: 2017-07-03 00:00:00; exit: 2017-08-01 00:00:00; Instrument: COM.BRN|p|49.0|2017-08-25 00:00:00; Quantity: -9996; PnL: -1407.7374389739364; Cummulative PnL: 10888.352873954651>,
 <Trade entry: 2017-08-01 00:00:00; exit: 2017-09-01 00:00:00; Instrument: COM.BRN|p|51.0|2017-09-26 00:00:00; Quantity: -9790; PnL: 274.12147686659; Cummulative PnL: 11737.763338861796>,
 <Trade entry: 2017-09-01 00:00:00; exit: 2017-10-02 00:00:00; Instrument: COM.BRN|p|52.0|2017-10-26 00:00:00; Quantity: -9728; PnL: -296.0450857415467; Cummulative PnL: 14288.114910353353>,
 <Trade entry: 2017-10-02 00:00:00; exit: 2017-11-01 00:00:00; Instrument: COM.BRN|p|55.0|2017-11-27 00:00:00; Quantity: -9321; PnL: 25.291736134807223; Cummulative PnL: 15299.688297646562>,
 <Trade entry: 2017-11-01 00:00:00; exit: 2017-12-01 00:00:00; Instrument: COM.BRN|p|59.0|2017-12-21 00:00:00; Quantity: -8774; PnL: 1225.4886641057062; Cummulative PnL: 12407.613774757681>,
 <Trade entry: 2017-12-01 00:00:00; exit: 2018-01-02 00:00:00; Instrument: COM.BRN|p|62.0|2018-01-26 00:00:00; Quantity: -8416; PnL: -37.23099694426867; Cummulative PnL: 10200.201490556752>,
 <Trade entry: 2018-01-02 00:00:00; exit: 2018-02-01 00:00:00; Instrument: COM.BRN|p|65.0|2018-02-23 00:00:00; Quantity: -8163; PnL: 634.812323182327; Cummulative PnL: 9823.865726322774>,
 <Trade entry: 2018-02-01 00:00:00; exit: 2018-03-01 00:00:00; Instrument: COM.BRN|p|68.0|2018-03-26 00:00:00; Quantity: -7850; PnL: -5785.110367506845; Cummulative PnL: -25041.539039711533>,
 <Trade entry: 2018-03-01 00:00:00; exit: 2018-04-02 00:00:00; Instrument: COM.BRN|p|63.0|2018-04-25 00:00:00; Quantity: -8414; PnL: -1431.001480178907; Cummulative PnL: 13638.790688843994>,
 <Trade entry: 2018-04-02 00:00:00; exit: 2018-05-01 00:00:00; Instrument: COM.BRN|p|66.0|2018-05-25 00:00:00; Quantity: -8034; PnL: -547.9289995445084; Cummulative PnL: 14655.250921827037>,
 <Trade entry: 2018-05-01 00:00:00; exit: 2018-06-01 00:00:00; Instrument: COM.BRN|p|71.0|2018-06-26 00:00:00; Quantity: -7518; PnL: -321.7896948470323; Cummulative PnL: 13013.866460020403>,
… (100 more lines)
```


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