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

> API reference for pulse.core.atm.

## `TradingEnvironment`

`dataclass`

```python theme={null}
TradingEnvironment(
    pulse_index: PulseIndex,
    datafeed: DataFeed,
    resolver: ResolverRegistry,
    broker: Broker,
    portfolio: Portfolio,
)
```

Container for all trading components.

### `TradingEnvironment.attach_to_strategy`

```python theme={null}
TradingEnvironment.attach_to_strategy(strategy: Strategy) -> None
```

Attach all components to a strategy.

## `EnvironmentBuilder`

```python theme={null}
EnvironmentBuilder(
    underlying_ids: str | Sequence[str],
    initial_equity: float,
)
```

Builder for creating trading environments with sensible defaults.

Record the ids and starting equity; every component stays unset until `build()`.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `underlying_ids` | `str \| Sequence[str]` | One id or several, wrapped by `to_underlying_ids`. Their common settlements become the pulse calendar unless `with_datetimes` or `with_pulse_index` supplies the clock. | *required* |
| `initial_equity` | `float` | Starting capital of the default `Portfolio`. Ignored when `with_portfolio` supplies one. | *required* |

### `EnvironmentBuilder.with_datafeed`

```python theme={null}
EnvironmentBuilder.with_datafeed(
    datafeed: DataFeed,
) -> EnvironmentBuilder
```

Use `datafeed` instead of the default local one.

`build()` then requires a matching resolver from `with_resolver`.

### `EnvironmentBuilder.with_resolver`

```python theme={null}
EnvironmentBuilder.with_resolver(
    resolver: ResolverRegistry,
) -> EnvironmentBuilder
```

Use `resolver` instead of the default local resolver registry.

### `EnvironmentBuilder.with_broker`

```python theme={null}
EnvironmentBuilder.with_broker(broker: Broker) -> EnvironmentBuilder
```

Use `broker` instead of the default `SimulationBroker`.

### `EnvironmentBuilder.with_portfolio`

```python theme={null}
EnvironmentBuilder.with_portfolio(
    portfolio: Portfolio,
) -> EnvironmentBuilder
```

Use `portfolio` instead of one built from `initial_equity`.

Its own fee calculator stands: `with_fee_calculator` is then ignored.

### `EnvironmentBuilder.with_pulse_index`

```python theme={null}
EnvironmentBuilder.with_pulse_index(
    pulse_index: PulseIndex,
) -> EnvironmentBuilder
```

Use `pulse_index` as the clock, in preference to any calendar.

`build()` still derives the underlyings' common settlements when `with_datetimes`
is absent; only the resulting value goes unused.

### `EnvironmentBuilder.with_datetimes`

```python theme={null}
EnvironmentBuilder.with_datetimes(
    datetimes: list[datetime],
) -> EnvironmentBuilder
```

Pulse on `datetimes` instead of on the underlyings' common settlements.

Copied, and ignored if `with_pulse_index` supplies a clock of its own. Mutually
exclusive with `with_date_range`: an explicit calendar is already bounded.

### `EnvironmentBuilder.with_date_range`

```python theme={null}
EnvironmentBuilder.with_date_range(
    start_datetime: datetime | None = None,
    end_datetime: datetime | None = None,
) -> EnvironmentBuilder
```

Bound the derived calendar, inclusive at both ends.

The bounds go to pdc's `available_settlements`, so the calendar is bisected rather than
derived whole and trimmed. Mutually exclusive with `with_datetimes`, and ignored if
`with_pulse_index` supplies a clock of its own.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `start_datetime` | `datetime \| None` | Inclusive first pulse. Defaults to None. | `None` |
| `end_datetime` | `datetime \| None` | Inclusive last pulse. Defaults to None. | `None` |

### `EnvironmentBuilder.with_fee_calculator`

```python theme={null}
EnvironmentBuilder.with_fee_calculator(
    fee_calculator: FeeCalculator,
) -> EnvironmentBuilder
```

Apply `fee_calculator` to the default `Portfolio` built by `build()`.

Ignored if a portfolio was already supplied via `with_portfolio`.

### `EnvironmentBuilder.build`

```python theme={null}
EnvironmentBuilder.build() -> TradingEnvironment
```

Build the trading environment with defaults for missing components.

## `ExecutionResult`

`dataclass`

```python theme={null}
ExecutionResult(
    strategy: Strategy,
    environment: TradingEnvironment,
    strategy_parameters: dict[str, Any] | None = dict(),
    execution_time: float | None = None,
)
```

Result of a strategy execution.

## `StrategyExecutor`

Bases: `ABC`

Abstract base class for strategy executors.

### `StrategyExecutor.execute`

`abstractmethod`

```python theme={null}
StrategyExecutor.execute(
    strategies: list[Strategy],
    trading_environments: list[TradingEnvironment],
    strategy_parameters: list[dict[str, Any]] | list[None] | None = None,
) -> list[ExecutionResult]
```

Execute a strategy in the given environment.

## `SequentialBatchExecutor`

Bases: [`StrategyExecutor`](https://docs.allasso.ch/dev/pulse/api/core/atm#strategyexecutor)

Executes multiple strategies in sequence.

### `SequentialBatchExecutor.execute`

```python theme={null}
SequentialBatchExecutor.execute(
    strategies: list[Strategy],
    trading_environments: list[TradingEnvironment],
    strategy_parameters: list[dict[str, Any]] | list[None] | None = None,
) -> list[ExecutionResult]
```

Execute every strategy in order, each against its own environment.

A strategy that raises aborts the batch and the exception propagates. Collecting it onto
the result instead is what the removed `stop_on_error=False` did, and it left a sweep
looking finished until `strategy.stats` raised.

## `AllassoTradeMachine`

```python theme={null}
AllassoTradeMachine(executor: StrategyExecutor)
```

The engine that runs strategies against their trading environments.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `executor` | [`StrategyExecutor`](https://docs.allasso.ch/dev/pulse/api/core/atm#strategyexecutor) | Drives the runs. `AllassoTradeMachine.sequential()` builds one with the sequential executor, which is the only one shipped. | *required* |

### `AllassoTradeMachine.sequential`

`classmethod`

```python theme={null}
AllassoTradeMachine.sequential() -> AllassoTradeMachine
```

Create ATM for sequential strategy execution.

### `AllassoTradeMachine.run`

```python theme={null}
AllassoTradeMachine.run(
    strategies: list[Strategy],
    trading_environments: list[TradingEnvironment],
    strategy_parameters: list[dict[str, Any]] | list[None] | None = None,
) -> list[ExecutionResult]
```

Run the strategy(ies) against the given environments.

## `warm_readers`

```python theme={null}
warm_readers(
    datafeed: DataFeed,
    underlying_ids: Sequence[UnderlyingID],
    datetimes: Sequence[datetime],
) -> None
```

Open every snapshot reader the calendar will touch, before the first pulse.

pdc opens a day file on first request, so an unwarmed run pays for the whole tree one file at
a time inside the loop. `get_reader` caches, so this only front-loads that work: warming a
datafeed twice (a sweep builds one environment per strategy) costs a dict lookup per pulse.
Providers that are not pdc's local ones have nothing to open and are skipped, as is an
underlying whose tree the provider does not cover (a futures-only root has no option
snapshots); those keep the lazy path.

## `run_sequentially`

```python theme={null}
run_sequentially(
    strategies: list[Strategy],
    initial_equity: float,
    strategy_parameters: list[dict[str, Any]] | list[None] | None = None,
    datetimes: list[datetime] | None = None,
    start_datetime: datetime | None = None,
    end_datetime: datetime | None = None,
    datafeed: DataFeed | None = None,
    resolver: ResolverRegistry | None = None,
    fee_calculator: FeeCalculator | None = None,
) -> list[ExecutionResult]
```

Run strategies one after another, each in its own trading environment.

One `EnvironmentBuilder` per strategy, built from that strategy's own `underlying_id`,
so a sweep is just a list of strategies here. Every strategy gets its own portfolio, broker
and pulse index; the datafeed and resolver are shared, which is what makes the warmed readers
worth paying for once.

The pulse calendar is the underlyings' common settlements, optionally bounded by
`start_datetime` / `end_datetime`, which are handed to pdc's `available_settlements`
and are inclusive at both ends. `datetimes` replaces that calendar outright instead, so it
cannot be combined with the bounds.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `strategies` | [`list[Strategy]`](https://docs.allasso.ch/dev/pulse/api/core/strategy#strategy) | The strategies to run, in order. | *required* |
| `initial_equity` | `float` | Starting capital, per strategy. | *required* |
| `strategy_parameters` | `list[dict[str, Any]] \| list[None] \| None` | Parameters recorded on each `ExecutionResult`, positionally matched to `strategies`. They are carried, not applied: the strategy is already constructed. Defaults to None. | `None` |
| `datetimes` | `list[datetime] \| None` | An explicit calendar for every strategy. Defaults to None, deriving it from the underlyings. | `None` |
| `start_datetime` | `datetime \| None` | Inclusive first pulse of the derived calendar. Defaults to None (from the first common settlement). | `None` |
| `end_datetime` | `datetime \| None` | Inclusive last pulse of the derived calendar. Defaults to None (to the last common settlement). | `None` |
| `datafeed` | `DataFeed \| None` | Defaults to None, building a local one. Passing one requires passing `resolver` too. | `None` |
| `resolver` | `ResolverRegistry \| None` | Defaults to None, building a local one. | `None` |
| `fee_calculator` | [`FeeCalculator \| None`](https://docs.allasso.ch/dev/pulse/api/core/fees#feecalculator) | Applied to every strategy's portfolio. Defaults to None, meaning no fees. | `None` |

**Raises**

| Type | Description |
| - | - |
| `ValueError` | if `datetimes` is combined with either bound, if a datafeed is passed without a resolver, or if the underlyings share no settlement in the range. |
| `Exception` | whatever a strategy raised. A failing strategy aborts the batch, so the results of the strategies that already finished are lost with it. |

**Returns**

| Type | Description |
| - | - |
| [`list[ExecutionResult]`](https://docs.allasso.ch/dev/pulse/api/core/atm#executionresult) | list\[ExecutionResult]: One result per strategy, in the order given. |


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