From 0f3a43b6e2b223f3f1d96f2c03f280e8e74fc0e9 Mon Sep 17 00:00:00 2001 From: imilev Date: Tue, 17 Jun 2025 19:57:09 +0300 Subject: [PATCH] Added high-level diagrams --- .codeboarding/AlgorithmSimulator.md | 281 ++++++++++++++++++++++++++++ .codeboarding/Blotter.md | 173 +++++++++++++++++ .codeboarding/DataPortal.md | 257 +++++++++++++++++++++++++ .codeboarding/MetricsTracker.md | 209 +++++++++++++++++++++ .codeboarding/TradingAlgorithm.md | 269 ++++++++++++++++++++++++++ .codeboarding/on_boarding.md | 153 +++++++++++++++ 6 files changed, 1342 insertions(+) create mode 100644 .codeboarding/AlgorithmSimulator.md create mode 100644 .codeboarding/Blotter.md create mode 100644 .codeboarding/DataPortal.md create mode 100644 .codeboarding/MetricsTracker.md create mode 100644 .codeboarding/TradingAlgorithm.md create mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/AlgorithmSimulator.md b/.codeboarding/AlgorithmSimulator.md new file mode 100644 index 0000000000..276d2b7e7f --- /dev/null +++ b/.codeboarding/AlgorithmSimulator.md @@ -0,0 +1,281 @@ +```mermaid + +graph LR + + AlgorithmSimulator["AlgorithmSimulator"] + + TradingAlgorithm["TradingAlgorithm"] + + DataPortal["DataPortal"] + + Clock["Clock"] + + SimulationBlotter["SimulationBlotter"] + + MetricsTracker["MetricsTracker"] + + BarData["BarData"] + + Order["Order"] + + Slippage_Models["Slippage Models"] + + Commission_Models["Commission Models"] + + AlgorithmSimulator -- "Orchestrates" --> TradingAlgorithm + + AlgorithmSimulator -- "Interacts with" --> DataPortal + + AlgorithmSimulator -- "Driven by" --> Clock + + AlgorithmSimulator -- "Manages orders via" --> SimulationBlotter + + AlgorithmSimulator -- "Updates and queries" --> MetricsTracker + + AlgorithmSimulator -- "Creates" --> BarData + + TradingAlgorithm -- "Executed by" --> AlgorithmSimulator + + TradingAlgorithm -- "Places orders with" --> SimulationBlotter + + TradingAlgorithm -- "Accesses data via" --> BarData + + TradingAlgorithm -- "Receives performance from" --> MetricsTracker + + DataPortal -- "Provides data to" --> AlgorithmSimulator + + DataPortal -- "Provides data to" --> BarData + + Clock -- "Drives" --> AlgorithmSimulator + + SimulationBlotter -- "Processes" --> Order + + SimulationBlotter -- "Applies" --> Slippage_Models + + SimulationBlotter -- "Applies" --> Commission_Models + + SimulationBlotter -- "Managed by" --> TradingAlgorithm + + MetricsTracker -- "Receives updates from" --> AlgorithmSimulator + + MetricsTracker -- "Provides reports to" --> TradingAlgorithm + + BarData -- "Used by" --> TradingAlgorithm + + BarData -- "Retrieves data from" --> DataPortal + + Order -- "Created by" --> SimulationBlotter + + Order -- "Processed by" --> SimulationBlotter + + Slippage_Models -- "Used by" --> SimulationBlotter + + Commission_Models -- "Used by" --> SimulationBlotter + + click AlgorithmSimulator href "https://github.com/quantopian/zipline/blob/main/.codeboarding//AlgorithmSimulator.md" "Details" + + click TradingAlgorithm href "https://github.com/quantopian/zipline/blob/main/.codeboarding//TradingAlgorithm.md" "Details" + + click DataPortal href "https://github.com/quantopian/zipline/blob/main/.codeboarding//DataPortal.md" "Details" + + click MetricsTracker href "https://github.com/quantopian/zipline/blob/main/.codeboarding//MetricsTracker.md" "Details" + +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Component Details + + + +Component overview for AlgorithmSimulator, focusing on its core interactions with the most fundamental components of the Zipline backtesting engine. + + + +### AlgorithmSimulator + +The central orchestrator of the backtest. It drives the simulation by iterating through market data, advancing the simulation clock, and triggering the `TradingAlgorithm`'s lifecycle methods (`before_trading_start`, `handle_data`). It coordinates with the `DataPortal`, `SimulationBlotter`, and `MetricsTracker` to execute trades and record performance. + + + + + +**Related Classes/Methods**: + + + +- `AlgorithmSimulator` (0:0) + + + + + +### TradingAlgorithm + +Encapsulates the user-defined trading logic. Users implement methods like `initialize`, `handle_data`, and `before_trading_start`, which are invoked by the `AlgorithmSimulator` at specific points during the simulation. It holds references to the `SimulationBlotter` for order execution and `MetricsTracker` for performance insights. + + + + + +**Related Classes/Methods**: + + + +- `TradingAlgorithm` (0:0) + + + + + +### DataPortal + +Provides a unified interface for accessing historical and current market data, including OHLCV data, splits, and other financial information. It serves as the primary data source for the `AlgorithmSimulator` and `BarData`. + + + + + +**Related Classes/Methods**: + + + +- `DataPortal` (99:1424) + + + + + +### Clock + +Generates simulation events (e.g., `BAR`, `SESSION_START`, `BEFORE_TRADING_START_BAR`) and manages the advancement of simulation time. It dictates when the `AlgorithmSimulator` should perform its actions, ensuring proper temporal progression of the backtest. + + + + + +**Related Classes/Methods**: + + + +- `Clock` (0:0) + + + + + +### SimulationBlotter + +Manages the lifecycle of orders within the simulated trading environment. It handles order placement, cancellation, and applies `Slippage Models` and `Commission Models` during transaction processing. The `AlgorithmSimulator` interacts with it to execute trades. + + + + + +**Related Classes/Methods**: + + + +- `SimulationBlotter` (42:392) + + + + + +### MetricsTracker + +Tracks and calculates various performance metrics of the trading algorithm, such as portfolio value, positions, transactions, and commissions. It aggregates data for daily and minute performance reports, providing insights into the algorithm's profitability and risk. + + + + + +**Related Classes/Methods**: + + + +- `MetricsTracker` (0:0) + + + + + +### BarData + +Provides a convenient and abstracted interface for the `TradingAlgorithm` to access current and historical market data for assets. It simplifies data retrieval by abstracting away the direct interaction with the `DataPortal`. + + + + + +**Related Classes/Methods**: + + + +- `BarData` (0:0) + + + + + +### Order + +Represents a single trading order within the simulation. It encapsulates details such as the asset, amount, order type (e.g., limit, stop), fill status, and commission incurred. Orders are created and processed by the `SimulationBlotter`. + + + + + +**Related Classes/Methods**: + + + +- `Order` (40:257) + + + + + +### Slippage Models + +A family of models that calculate the price impact of trades due to factors like market liquidity and order size. These models are applied by the `SimulationBlotter` to make the simulated trade execution more realistic. + + + + + +**Related Classes/Methods**: + + + +- `Slippage Models` (0:0) + + + + + +### Commission Models + +A family of models that calculate the fees incurred on trades. These models are applied by the `SimulationBlotter` to determine the cost of transactions, which is essential for accurate profit/loss calculation in the simulation. + + + + + +**Related Classes/Methods**: + + + +- `Commission Models` (0:0) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Blotter.md b/.codeboarding/Blotter.md new file mode 100644 index 0000000000..b7e7e73c90 --- /dev/null +++ b/.codeboarding/Blotter.md @@ -0,0 +1,173 @@ +```mermaid + +graph LR + + SimulationBlotter["SimulationBlotter"] + + Order["Order"] + + FixedBasisPointsSlippage["FixedBasisPointsSlippage"] + + VolatilityVolumeShare["VolatilityVolumeShare"] + + PerShare["PerShare"] + + PerContract["PerContract"] + + expect_types["expect_types"] + + SimulationBlotter -- "initializes with" --> FixedBasisPointsSlippage + + SimulationBlotter -- "initializes with" --> VolatilityVolumeShare + + SimulationBlotter -- "initializes with" --> PerShare + + SimulationBlotter -- "initializes with" --> PerContract + + SimulationBlotter -- "creates" --> Order + + SimulationBlotter -- "modifies" --> Order + + SimulationBlotter -- "calls simulate on" --> FixedBasisPointsSlippage + + SimulationBlotter -- "calls simulate on" --> VolatilityVolumeShare + + SimulationBlotter -- "calls calculate on" --> PerShare + + SimulationBlotter -- "calls calculate on" --> PerContract + + SimulationBlotter -- "uses" --> expect_types + + Order -- "uses" --> expect_types + +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Component Details + + + +The `Blotter` subsystem in Zipline is the operational core for managing the lifecycle of trading orders within a simulation. It translates abstract trading intentions into concrete, simulated market actions, applying realistic financial models for slippage and commission, and subsequently updating the portfolio state. + + + +### SimulationBlotter + +The central orchestrator of the Blotter subsystem. It manages the creation, cancellation, and processing of orders. It integrates slippage and commission models to simulate realistic trade executions and is responsible for generating transactions and commissions that reflect these simulated fills. + + + + + +**Related Classes/Methods**: + + + +- `Order` (40:257) + +- `FixedBasisPointsSlippage` (0:0) + +- `VolatilityVolumeShare` (0:0) + +- `PerShare` (0:0) + +- `PerContract` (0:0) + +- `expect_types` (0:0) + +- `SimulationBlotter:get_transactions` (305:365) + +- `SimulationBlotter:order` (94:153) + + + + + +### Order + +Represents a single trading instruction within the simulation. It encapsulates all critical details of a trade, including the asset, amount, execution style (stop/limit prices), fill status, and incurred commission. It also handles updates related to price triggers and stock splits. + + + + + +**Related Classes/Methods**: + + + +- `expect_types` (0:0) + +- `Order:__init__` (49:76) + + + + + +### FixedBasisPointsSlippage + +A concrete implementation of a slippage model, primarily used for equities. It simulates market impact by applying a fixed percentage (basis points) to the trade price, constrained by a volume limit, to reflect the cost of executing large orders. + + + + + +**Related Classes/Methods**: _None_ + + + +### VolatilityVolumeShare + +A concrete slippage model specifically designed for futures contracts. It calculates market impact based on the asset's volatility and the proportion of the average daily volume that the order represents. + + + + + +**Related Classes/Methods**: _None_ + + + +### PerShare + +A concrete commission model that calculates the cost of a trade based on a fixed amount per share, with an optional minimum cost per trade. This is the default commission model for equities. + + + + + +**Related Classes/Methods**: _None_ + + + +### PerContract + +A concrete commission model tailored for futures contracts. It calculates commission based on a cost per contract and incorporates exchange fees, with an optional minimum trade cost. + + + + + +**Related Classes/Methods**: _None_ + + + +### expect_types + +A utility decorator used for input validation. It ensures that function arguments conform to their expected data types, thereby enhancing the robustness and reliability of the code by catching type-related errors early. + + + + + +**Related Classes/Methods**: _None_ + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/DataPortal.md b/.codeboarding/DataPortal.md new file mode 100644 index 0000000000..0fb87896bb --- /dev/null +++ b/.codeboarding/DataPortal.md @@ -0,0 +1,257 @@ +```mermaid + +graph LR + + DataPortal["DataPortal"] + + AssetFinder["AssetFinder"] + + TradingCalendar["TradingCalendar"] + + BarReader["BarReader"] + + AdjustmentReader["AdjustmentReader"] + + RollFinder["RollFinder"] + + HistoryLoader["HistoryLoader"] + + DailyHistoryAggregator["DailyHistoryAggregator"] + + Asset["Asset"] + + HistoryWindowStartsBeforeData["HistoryWindowStartsBeforeData"] + + DataPortal -- "utilizes" --> AssetFinder + + DataPortal -- "depends on" --> TradingCalendar + + DataPortal -- "delegates to" --> BarReader + + DataPortal -- "applies" --> AdjustmentReader + + DataPortal -- "manages" --> RollFinder + + DataPortal -- "orchestrates" --> HistoryLoader + + DataPortal -- "aggregates with" --> DailyHistoryAggregator + + DataPortal -- "operates on" --> Asset + + DataPortal -- "raises" --> HistoryWindowStartsBeforeData + + click DataPortal href "https://github.com/quantopian/zipline/blob/main/.codeboarding//DataPortal.md" "Details" + +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Component Details + + + +Analysis of the DataPortal component and its related components within the Zipline project. + + + +### DataPortal + +The primary interface for accessing all historical and current market data (prices, adjustments, dividends, splits) for various assets. It abstracts the underlying data storage mechanisms, providing a consistent and efficient way for other components to retrieve necessary financial information. It acts as the "memory" or "knowledge base" of the system. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.data_portal.DataPortal` (99:1424) + + + + + +### AssetFinder + +Responsible for resolving asset identifiers (SIDs) into `Asset` objects and providing metadata about financial instruments. + + + + + +**Related Classes/Methods**: + + + +- `zipline.assets.assets.AssetFinder` (275:1515) + + + + + +### TradingCalendar + +Defines the trading schedule, including market open/close times, sessions, and holidays. It provides utilities for navigating time-series data according to market conventions. + + + + + +**Related Classes/Methods**: + + + +- `zipline.utils.calendar.exchange_calendar.TradingCalendar` (1:1) + + + + + +### BarReader + +Defines the interface for reading raw historical price data (bars) at different frequencies (minute, daily). `DataPortal` uses concrete implementations of this interface to fetch the actual OHLCV (Open, High, Low, Close, Volume) data. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.bar_reader.BarReader` (42:147) + +- `zipline.data.dispatch_bar_reader.AssetDispatchMinuteBarReader` (133:136) + +- `zipline.data.dispatch_bar_reader.AssetDispatchSessionBarReader` (139:148) + + + + + +### AdjustmentReader + +Provides access to corporate action data such as splits, dividends, and mergers, which are used to adjust historical prices to ensure accuracy. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.adjustments.AdjustmentReader` (1:1) + +- `zipline.data.adjustments.SQLiteAdjustmentWriter` (337:702) + + + + + +### RollFinder + +Specifically used for continuous futures contracts, this component helps in determining the "roll" dates, which are crucial for stitching together data from different futures contracts to form a continuous series. + + + + + +**Related Classes/Methods**: + + + +- `zipline.assets.roll_finder.RollFinder` (23:136) + +- `zipline.assets.roll_finder.CalendarRollFinder` (139:153) + +- `zipline.assets.roll_finder.VolumeRollFinder` (156:274) + + + + + +### HistoryLoader + +Responsible for loading historical data windows, including applying adjustments, for a given set of assets and a specified time range. It works in conjunction with `BarReader` and `AdjustmentReader`. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.history_loader.HistoryLoader` (295:554) + +- `zipline.data.history_loader.DailyHistoryLoader` (557:573) + +- `zipline.data.history_loader.MinuteHistoryLoader` (576:595) + + + + + +### DailyHistoryAggregator + +Aggregates minute-level data into daily bars, particularly useful when only minute data is available but daily data is requested. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.data_portal.DailyHistoryAggregator` (1:1) + + + + + +### Asset + +Represents financial instruments (equities, futures, etc.) and holds metadata about them, such as start/end dates, symbol, and exchange. + + + + + +**Related Classes/Methods**: + + + +- `zipline.assets.assets.Asset` (1:1) + + + + + +### HistoryWindowStartsBeforeData + +A custom exception raised when a requested historical data window extends before the available data for a given asset or the overall data start date. + + + + + +**Related Classes/Methods**: + + + +- `zipline.errors.HistoryWindowStartsBeforeData` (770:774) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/MetricsTracker.md b/.codeboarding/MetricsTracker.md new file mode 100644 index 0000000000..d5252e814c --- /dev/null +++ b/.codeboarding/MetricsTracker.md @@ -0,0 +1,209 @@ +```mermaid + +graph LR + + MetricsTracker["MetricsTracker"] + + Metric["Metric"] + + Ledger["Ledger"] + + TradingCalendar["TradingCalendar"] + + DataPortal["DataPortal"] + + TradingAlgorithm["TradingAlgorithm"] + + AssetFinder["AssetFinder"] + + BenchmarkSource["BenchmarkSource"] + + TradingAlgorithm -- "initializes" --> MetricsTracker + + TradingAlgorithm -- "drives" --> MetricsTracker + + MetricsTracker -- "manages" --> Metric + + MetricsTracker -- "delegates_state_management_to" --> Ledger + + MetricsTracker -- "retrieves_financial_data_from" --> Ledger + + MetricsTracker -- "consults" --> TradingCalendar + + MetricsTracker -- "receives_data_from" --> DataPortal + + MetricsTracker -- "uses" --> AssetFinder + + MetricsTracker -- "incorporates" --> BenchmarkSource + + click MetricsTracker href "https://github.com/quantopian/zipline/blob/main/.codeboarding//MetricsTracker.md" "Details" + + click Metric href "https://github.com/quantopian/zipline/blob/main/.codeboarding//Metric.md" "Details" + + click DataPortal href "https://github.com/quantopian/zipline/blob/main/.codeboarding//DataPortal.md" "Details" + + click TradingAlgorithm href "https://github.com/quantopian/zipline/blob/main/.codeboarding//TradingAlgorithm.md" "Details" + +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Component Details + + + +This subsystem focuses on the collection, aggregation, and calculation of financial performance metrics within the Zipline simulation. It provides the essential reporting and analysis capabilities for evaluating trading strategy performance. + + + +### MetricsTracker + +The central component responsible for orchestrating the collection, aggregation, and calculation of various financial performance metrics throughout a trading simulation. It maintains the overall financial state of the portfolio and account by interacting with the `Ledger`. It dynamically binds and invokes "hook" methods from registered `Metric` objects at various points in the simulation lifecycle (e.g., start/end of simulation, start/end of session, end of bar) to update metrics based on market events. It also leverages `TradingCalendar` for time-based calculations and `DataPortal` for market data synchronization. + + + + + +**Related Classes/Methods**: + + + +- `MetricsTracker` (1:1) + + + + + +### Metric + +An abstract base class representing an individual performance or risk metric (e.g., returns, volatility, drawdown). Concrete implementations of `Metric` provide specific calculation logic and expose "hook" methods (e.g., `start_of_simulation`, `end_of_bar`) that `MetricsTracker` calls. This allows for a modular and extensible way to add new metrics without modifying the core `MetricsTracker` logic. + + + + + +**Related Classes/Methods**: + + + +- `Metric` (1:1) + + + + + +### Ledger + +A fundamental financial component that maintains the algorithm's detailed financial state. This includes the portfolio, account balances, and individual asset positions. `MetricsTracker` delegates many state-updating operations to the `Ledger`, such as processing transactions, commissions, splits, capital changes, and syncing last sale prices. The `MetricsTracker` retrieves portfolio and account information directly from the `Ledger` to generate performance packets. + + + + + +**Related Classes/Methods**: + + + +- `Ledger` (341:839) + + + + + +### TradingCalendar + +Defines and provides information about the trading schedule, including session open and close times, and the range of trading sessions for the simulation. `MetricsTracker` uses `TradingCalendar` to determine market open/close times, iterate through sessions, and align metric updates with the correct market events. + + + + + +**Related Classes/Methods**: + + + +- `TradingCalendar` (1:1) + + + + + +### DataPortal + +Serves as the primary interface for accessing market data within the simulation. It provides historical and real-time price data, as well as adjustment information (e.g., dividends, splits). `MetricsTracker` interacts with `DataPortal` (often indirectly via `Ledger` or directly for `sync_last_sale_prices` and `process_dividends`) to ensure that financial calculations are based on the most current and accurate market data. + + + + + +**Related Classes/Methods**: + + + +- `DataPortal` (99:1424) + + + + + +### TradingAlgorithm + +The main simulation engine that orchestrates the entire trading simulation. It initializes and manages the lifecycle of `MetricsTracker` and other core components. `TradingAlgorithm` drives the simulation forward, calling `MetricsTracker` methods at appropriate times (e.g., `handle_minute_close`, `handle_market_open`, `handle_market_close`) to trigger metric updates and performance packet generation. + + + + + +**Related Classes/Methods**: + + + +- `TradingAlgorithm` (1:1) + + + + + +### AssetFinder + +A utility component responsible for resolving asset identifiers (e.g., ticker symbols) to internal asset objects. `MetricsTracker` passes an `AssetFinder` instance to the `Ledger` (specifically when processing dividends via `handle_market_open`) to ensure that financial adjustments are correctly applied to the right assets. + + + + + +**Related Classes/Methods**: + + + +- `AssetFinder` (1:1) + + + + + +### BenchmarkSource + +Provides benchmark data against which the algorithm's performance is compared. `MetricsTracker` receives a `BenchmarkSource` instance during its `handle_start_of_simulation` method and uses it when generating the final simulation end packet. This allows for the calculation of relative performance metrics. + + + + + +**Related Classes/Methods**: + + + +- `BenchmarkSource` (24:311) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/TradingAlgorithm.md b/.codeboarding/TradingAlgorithm.md new file mode 100644 index 0000000000..298a18d7ed --- /dev/null +++ b/.codeboarding/TradingAlgorithm.md @@ -0,0 +1,269 @@ +```mermaid + +graph LR + + TradingAlgorithm["TradingAlgorithm"] + + AlgorithmSimulator["AlgorithmSimulator"] + + DataPortal["DataPortal"] + + Blotter["Blotter"] + + MetricsTracker["MetricsTracker"] + + AssetFinder["AssetFinder"] + + PipelineEngine["PipelineEngine"] + + EventManager["EventManager"] + + Clock["Clock"] + + ZiplineAPI["ZiplineAPI"] + + TradingAlgorithm -- "interacts with" --> DataPortal + + AlgorithmSimulator -- "orchestrates" --> TradingAlgorithm + + AlgorithmSimulator -- "interacts with" --> MetricsTracker + + DataPortal -- "depends on" --> AssetFinder + + TradingAlgorithm -- "places orders on" --> Blotter + + Blotter -- "provides state to" --> TradingAlgorithm + + AlgorithmSimulator -- "feeds data to" --> MetricsTracker + + MetricsTracker -- "provides state to" --> TradingAlgorithm + + TradingAlgorithm -- "uses" --> AssetFinder + + TradingAlgorithm -- "invokes" --> PipelineEngine + + PipelineEngine -- "provides data to" --> TradingAlgorithm + + TradingAlgorithm -- "schedules events with" --> EventManager + + EventManager -- "dispatches events to" --> TradingAlgorithm + + Clock -- "controls time for" --> AlgorithmSimulator + + TradingAlgorithm -- "configures/instantiates" --> Clock + + AlgorithmSimulator -- "uses" --> Clock + + TradingAlgorithm -- "uses" --> ZiplineAPI + + ZiplineAPI -- "provides context to" --> TradingAlgorithm + + click TradingAlgorithm href "https://github.com/quantopian/zipline/blob/main/.codeboarding//TradingAlgorithm.md" "Details" + + click AlgorithmSimulator href "https://github.com/quantopian/zipline/blob/main/.codeboarding//AlgorithmSimulator.md" "Details" + + click DataPortal href "https://github.com/quantopian/zipline/blob/main/.codeboarding//DataPortal.md" "Details" + + click Blotter href "https://github.com/quantopian/zipline/blob/main/.codeboarding//Blotter.md" "Details" + + click MetricsTracker href "https://github.com/quantopian/zipline/blob/main/.codeboarding//MetricsTracker.md" "Details" + +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Component Details + + + +Updated analysis based on feedback, focusing on corrected source code references and revised relationships to align with architectural feedback. + + + +### TradingAlgorithm + +The core user-defined component that contains the trading strategy logic. It defines the `initialize`, `handle_data`, `before_trading_start`, and `analyze` lifecycle methods that users implement. It interacts with various other components to execute trades, access data, and manage events. + + + + + +**Related Classes/Methods**: + + + +- `zipline.algorithm.TradingAlgorithm` (149:2415) + + + + + +### AlgorithmSimulator + +The central orchestrator of the backtesting process. It drives the simulation forward in time, manages simulation parameters, and coordinates interactions between the TradingAlgorithm, data sources, order execution, and performance tracking. It consumes time-based events provided by the Clock. + + + + + +**Related Classes/Methods**: + + + +- `zipline.gens.tradesimulation.AlgorithmSimulator` (33:305) + + + + + +### DataPortal + +Provides a unified interface for accessing all market data, including historical OHLCV data, asset metadata, and adjustments. It serves as the primary data provider for the TradingAlgorithm and other simulation components. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.data_portal.DataPortal` (99:1424) + + + + + +### Blotter + +Simulates the order management and execution process. It handles the creation, modification, cancellation, and filling of orders, and manages the algorithm's positions and transactions. + + + + + +**Related Classes/Methods**: + + + +- `zipline.finance.blotter.simulation_blotter.SimulationBlotter` (42:392) + + + + + +### MetricsTracker + +Responsible for tracking and calculating the performance metrics of the trading algorithm throughout the simulation. It aggregates financial events (transactions, orders, commissions) and generates comprehensive performance reports. + + + + + +**Related Classes/Methods**: + + + +- `zipline.finance.metrics.tracker.MetricsTracker` (25:352) + + + + + +### AssetFinder + +Manages and provides access to information about financial assets (equities, futures). It handles asset lookup by symbol or unique identifier (SID) and resolves asset information based on specific dates, accounting for corporate actions and delistings. + + + + + +**Related Classes/Methods**: + + + +- `zipline.assets.assets.AssetFinder` (275:1515) + + + + + +### PipelineEngine + +Executes data pipelines defined using Zipline's Pipeline API. It processes complex data transformations and filters across a universe of assets, providing structured dataframes of computed results to the TradingAlgorithm for advanced analysis and signal generation. + + + + + +**Related Classes/Methods**: + + + +- `zipline.pipeline.engine.PipelineEngine` (86:165) + + + + + +### EventManager + +Manages and dispatches custom events scheduled by the TradingAlgorithm. It allows users to define rules for when specific functions should be executed, providing flexibility for implementing time-based or condition-based logic. + + + + + +**Related Classes/Methods**: + + + +- `zipline.utils.events.EventManager` (183:218) + + + + + +### Clock + +Manages the time progression within the simulation. It emits time-based events (e.g., BAR, SESSION_START, SESSION_END) that drive the AlgorithmSimulator. While the `TradingAlgorithm` configures and instantiates the specific `Clock` implementation, the `AlgorithmSimulator` is the primary consumer of its time-based events. + + + + + +**Related Classes/Methods**: + + + +- `zipline.gens.sim_engine.MinuteSimulationClock` (20:200) + + + + + +### ZiplineAPI + +A utility component that acts as a context manager to expose Zipline's built-in API functions (e.g., order, record, log) directly to the user's TradingAlgorithm script, simplifying interaction with the simulation environment. + + + + + +**Related Classes/Methods**: + + + +- `zipline.utils.api_support.ZiplineAPI` (20:40) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 0000000000..44871713bb --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,153 @@ +```mermaid + +graph LR + + TradingAlgorithm["TradingAlgorithm"] + + AlgorithmSimulator["AlgorithmSimulator"] + + DataPortal["DataPortal"] + + Blotter["Blotter"] + + MetricsTracker["MetricsTracker"] + + TradingAlgorithm -- "uses" --> DataPortal + + TradingAlgorithm -- "places orders through" --> Blotter + + AlgorithmSimulator -- "executes strategy logic of" --> TradingAlgorithm + + AlgorithmSimulator -- "fetches data from" --> DataPortal + + DataPortal -- "provides data to" --> AlgorithmSimulator + + DataPortal -- "provides data to" --> TradingAlgorithm + + Blotter -- "receives orders from" --> TradingAlgorithm + + Blotter -- "updates" --> MetricsTracker + + MetricsTracker -- "receives updates from" --> AlgorithmSimulator + + MetricsTracker -- "receives trade data from" --> Blotter + + click TradingAlgorithm href "https://github.com/quantopian/zipline/blob/main/.codeboarding//TradingAlgorithm.md" "Details" + + click AlgorithmSimulator href "https://github.com/quantopian/zipline/blob/main/.codeboarding//AlgorithmSimulator.md" "Details" + + click DataPortal href "https://github.com/quantopian/zipline/blob/main/.codeboarding//DataPortal.md" "Details" + + click Blotter href "https://github.com/quantopian/zipline/blob/main/.codeboarding//Blotter.md" "Details" + + click MetricsTracker href "https://github.com/quantopian/zipline/blob/main/.codeboarding//MetricsTracker.md" "Details" + +``` + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Component Details + + + +The `zipline` backtesting engine is built around a few critical components that orchestrate the simulation of trading strategies against historical market data. These components work in concert to provide a realistic and robust environment for strategy development and evaluation. + + + +### TradingAlgorithm + +The central user-defined component where the trading strategy logic is implemented. It defines how the algorithm reacts to market data, places orders, and manages its state. It's the "brain" of the backtest, encapsulating the user's investment thesis. + + + + + +**Related Classes/Methods**: + + + +- `zipline.finance.trading_algorithm.TradingAlgorithm` (0:0) + + + + + +### AlgorithmSimulator + +The core execution engine that drives the backtest. It iterates through market data bar by bar, advances the simulation clock, and triggers the `TradingAlgorithm`'s lifecycle methods (`before_trading_start`, `handle_data`). It's the "heartbeat" that orchestrates the entire simulation process. + + + + + +**Related Classes/Methods**: + + + +- `zipline.gens.tradesimulation.AlgorithmSimulator` (33:305) + + + + + +### DataPortal + +The unified interface for accessing all historical and current market data (prices, adjustments, dividends, splits) for various assets. It abstracts the underlying data storage mechanisms, providing a consistent and efficient way for other components to retrieve necessary financial information. It acts as the "memory" or "knowledge base" of the system. + + + + + +**Related Classes/Methods**: + + + +- `zipline.data.data_portal.DataPortal` (99:1424) + + + + + +### Blotter + +Manages the lifecycle of orders, from creation to execution. It applies financial models (like slippage and commission) to simulate realistic trade costs and updates the portfolio state based on executed trades. This component is the "action arm," translating theoretical orders into simulated market actions. + + + + + +**Related Classes/Methods**: + + + +- `zipline.finance.blotter.simulation_blotter.SimulationBlotter` (42:392) + + + + + +### MetricsTracker + +Collects, aggregates, and calculates various financial performance metrics (e.g., PNL, returns, risk, portfolio value) throughout the simulation. It maintains the overall financial state of the portfolio and account, providing the essential "reporting and analysis" for evaluating strategy performance. + + + + + +**Related Classes/Methods**: + + + +- `zipline.finance.metrics.tracker.MetricsTracker` (25:352) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file