easy-tdx

The current version of the Web UI provides the following capabilities for single-asset strategy backtesting:

• Market Data Selection: Fetch data for Shanghai, Shenzhen, and Beijing markets across Daily, Weekly, and Minute intervals via the /api/v1/bars endpoint.
• Strategy Configuration: Select from preset strategies (e.g., MA Crossover, MACD, Bollinger Bands, RSI, KDJ). The parameter forms are dynamically rendered based on the backend schema.
• Backtest Reporting:
  • K-Line Chart: Main chart with buy/sell point annotations using ECharts candlestick and markPoint.
  • Equity Curve: Dual-axis chart showing net value and drawdown.
  • Performance Metrics: A table containing 19 performance indicators (covering returns, risk, and trade groupings).
  • Trade Records: A detailed table of all executed trades.

The v1.11.0 Factor Engine introduces a systematic way to calculate and manage quantitative factors within easy-tdx. It utilizes an ABC (Abstract Base Class) and Registry pattern, ensuring consistency with existing indicator patterns in the repository.

Key capabilities include:

• Factor Base & Registry: A structured way to define and register new factors.
• FactorEngine: A calculation engine supporting two modes: single-stock multi-factor calculation and cross-stock sectional calculation.
• Built-in Factors: 15 pre-implemented factors that bridge existing capabilities from MyTT and ChanlunAnalyser.
• CLI Integration: The easy-tdx factor list command to enumerate available factors.

All calculations are performed using pure numpy vectorization and do not depend on network calls, ensuring high performance.

The easy_tdx.backtest module is a pure-computation backtesting engine designed for vectorized strategy execution. It is built to be independent of network dependencies, allowing for high-performance local testing of trading strategies.

Key Features:

• Strategy Definition: Supports Python class-based strategy definitions.
• Execution: Vectorized execution pipeline.
• Matching Rules: Supports 5 different matching/order execution rules.
• Performance Metrics: Provides 18 distinct performance indicators.
• CLI Integration: One-click backtesting via command line.

Architecture Layers:

1. Data Types (types.py)
2. Strategy Base Class & Data Proxy (strategy.py)
3. Order Matcher (orders.py)
4. Portfolio Tracking (portfolio.py)
5. Performance Analysis (performance.py)
6. Engine Orchestration (engine.py)
7. CLI Integration (cli.py)

The easy-tdx project is structured into several functional layers:

• Clients: TdxClient (standard), MacClient (MAC protocol), and ExTdxClient (extended markets).
• Core Logic: indicator.py (technical indicators based on MyTT), chanlun (technical analysis), and factor (factor engine).
• Strategy & Backtesting: backtest (engine), portfolio (management), and screen (scanning).
• Real-time & Web: realtime (event-driven data push) and web (FastAPI REST/WebSocket API).
• Infrastructure: transport (sync/async connections), codec (data encoding/decoding), and models (dataclasses).

The backtesting engine uses a decoupled architecture for simulating market reality:

1. OrderSimulator manages the high-level backtest loop and state (cash, position). It uses a SlippageModel to calculate the cost of a trade based on current market conditions (price, volume, and volatility).
2. ExecutionModel (e.g., ImmediateExecution) defines the logic of when and how a signal becomes a trade. It takes a SlippageModel as an input to ensure that the simulated execution price includes the calculated slippage cost.

This separation allows you to swap out different execution strategies (e.g., immediate vs. scheduled) while keeping the same market impact (slippage) logic.

The factor system is built on a base Factor class and a central FACTORY_REGISTRY.

1. Registration: Factors are defined as classes and decorated with @register_factor. This automatically adds them to the FACTORY_REGISTRY during module import.
2. Discovery: The easy_tdx.factor.builtin module imports all sub-modules (momentum, volatility, etc.) to trigger this registration process. This makes all built-in factors available via list_factors() and get_factor().
3. Computation: Every factor class must implement a .compute(df) method that takes a DataFrame and returns a pd.Series of the same length.

The TDX protocol uses raw TCP (typically on port 7709) without HTTP wrapping. Communication follows a specific frame format discovered via packet sniffing:

Response Frame Structure: 16 bytes fixed header + variable length body

Header Layout (from codec/frame.py):

• Offset 0: 4 bytes (Unknown)
• Offset 4: 4 bytes (Unknown)
• Offset 8: 4 bytes (Unknown)
• Offset 12: 2 bytes (zipsize) — The actual length of the body.
• Offset 14: 2 bytes (unzipsize) — The length of the body after decompression.

Decompression Logic: If zipsize == unzipsize, the body is uncompressed. Otherwise, the body must be decompressed using zlib.

# Conceptual representation of the frame header
# Offset 12: H (2 bytes) -> zipsize
# Offset 14: H (2 bytes) -> unzipsize

The factor system is built on a plugin-style architecture using an Abstract Base Class (ABC) and a global registry:

1. Contract: The Factor class defines the mandatory interface (name, category, inputs, and compute).
2. Validation: The __init_subclass__ hook in Factor ensures that any new subclass defines all required attributes at the moment of class definition, preventing runtime errors during computation.
3. Discovery: The @register_factor decorator populates FACTORY_REGISTRY. This registry acts as a lookup table that maps string names to class types.
4. Execution: The FactorEngine uses the registry to resolve string names into executable logic, allowing users to request factors by name (e.g., via CLI or API) without needing to pass class objects manually.