[nep7une (shancun-c)]

Description

Document the existing price/volume/order unit contract and add offline regression coverage for both consumers of volume in Exchange.

• Explain adjusted_volume = raw_volume_in_shares / factor and matching adjusted order amounts, including price normalization to 1.
• Clarify that vendor lots must be converted at the data-producer boundary; CN region alone is not evidence for a multiplier.
• Distinguish the impact-cost denominator from volume_threshold, including why changing only a threshold or substituting turnover does not repair both paths.
• Expand get_volume()'s docstring without changing runtime behavior.
• Add synthetic share-native, correctly converted lot-native, and unconverted-lot fixtures. Cover BUY/SELL and three adjustment factors; verify fill, traded value, and cost, including negative controls.

Motivation and Context

Related to #2362. This is a documentation and regression-test contribution, not a fix to a particular community dataset or an automatic scale-detection proposal. It does not download market data, change existing binary datasets, or add a blanket CN multiplier. The impact-cost description refers to the amount after volume clipping and before later cash/position clipping.

How Has This Been Tested?

Python 3.12, source checkout on Linux and Windows:

python -m pytest -q tests/backtest/test_exchange_volume_units.py tests/backtest/test_soft_topk_strategy_cold_start.py tests/backtest/test_soft_topk_strategy.py

15 passed on each platform, including 12 new cases. Existing NumPy timedelta deprecation warnings remain.

• Black 25.12.0 --check --line-length 120 on the changed Python files: passed.
• git diff --check: passed.
• New RST section parsed with Docutils and warnings treated as errors: passed.
• Independently reviewed and the 12 new tests independently rerun on Linux.

The full pipeline suite and full Sphinx build were not run. No claim is made to reproduce or validate any particular community market-data archive.

Types of changes

• Fix bugs
• Add new feature
• Update documentation
• Add regression tests

[nep7une (shancun-c)]

@microsoft-github-policy-service agree