同步目录文档

Author: shinny-mayanqiong

doc/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = TianQin
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/_static/baidu.js

@@ -0,0 +1,7 @@
+var _hmt = _hmt || [];
+(function() {
+  var hm = document.createElement("script");
+  hm.src = "https://hm.baidu.com/hm.js?f7292fcf4a7be122de798d24f80e32f6";
+  var s = document.getElementsByTagName("script")[0]; 
+  s.parentNode.insertBefore(hm, s);
+})();

doc/_static/demo_t10.png

@@ -0,0 +1,82 @@
+.. _batch_backtest:
+
+批量回测, 参数搜索及其它
+=================================================
+在阅读本文档前, 请确保您已经熟悉了 :ref:`backtest` 
+
+参数优化/参数搜索
+-------------------------------------------------
+TqSdk 并不提供专门的参数优化机制. 您可以按照自己的需求, 针对可能的每个参数值安排一个回测, 观察它们的回测结果, 以简单的双均线策略为例::
+
+  from tqsdk import TqApi, TqAuth, TqSim, TargetPosTask, BacktestFinished, TqBacktest
+  from tqsdk.tafunc import ma
+  from datetime import date
+
+  LONG = 60
+  SYMBOL = "SHFE.cu1907"
+
+  for SHORT in range(20, 40): # 短周期参数从20-40分别做回测
+    acc = TqSim()             # 每次回测都创建一个新的模拟账户
+    try:
+      api = TqApi(acc, backtest=TqBacktest(start_dt=date(2019, 5, 6), end_dt=date(2019, 5, 10)), auth=TqAuth("信易账户", "账户密码"))
+      account = api.get_account()
+      klines = api.get_kline_serial(SYMBOL, duration_seconds=60, data_length=LONG + 2)
+      target_pos = TargetPosTask(api, SYMBOL)
+      while True:
+        api.wait_update()
+        if api.is_changing(klines.iloc[-1], "datetime"):
+          short_avg = ma(klines.close, SHORT)
+          long_avg = ma(klines.close, LONG)
+          if long_avg.iloc[-2] < short_avg.iloc[-2] and long_avg.iloc[-1] > short_avg.iloc[-1]:
+            target_pos.set_target_volume(-1)
+          if short_avg.iloc[-2] < long_avg.iloc[-2] and short_avg.iloc[-1] > long_avg.iloc[-1]:
+            target_pos.set_target_volume(1)
+    except BacktestFinished:
+      api.close()
+      print("SHORT=", SHORT, "最终权益=", account["balance"])   # 每次回测结束时, 输出使用的参数和最终权益
+
+
+多进程并发执行多个回测任务
+-------------------------------------------------
+如果您有大量回测任务想要尽快完成, 您首先需要一台给力的电脑(可以考虑到XX云上租一台32核的, 一小时几块钱). 然后您就可以并发执行N个回测了. 还是以上面的策略为例::
+
+  from tqsdk import TqApi, TqAuth, TqSim, TargetPosTask, BacktestFinished, TqBacktest
+  from tqsdk.tafunc import ma
+  from datetime import date
+  import multiprocessing
+  from multiprocessing import Pool
+
+  def MyStrategy(SHORT):
+    LONG = 60
+    SYMBOL = "SHFE.cu1907"
+    acc = TqSim()
+    try:
+      api = TqApi(acc, backtest=TqBacktest(start_dt=date(2019, 5, 6), end_dt=date(2019, 5, 10)), auth=TqAuth("信易账户", "账户密码"))
+      data_length = LONG + 2
+      klines = api.get_kline_serial(SYMBOL, duration_seconds=60, data_length=data_length)
+      target_pos = TargetPosTask(api, SYMBOL)
+      while True:
+        api.wait_update()
+        if api.is_changing(klines.iloc[-1], "datetime"):
+          short_avg = ma(klines.close, SHORT)
+          long_avg = ma(klines.close, LONG)
+          if long_avg.iloc[-2] < short_avg.iloc[-2] and long_avg.iloc[-1] > short_avg.iloc[-1]:
+            target_pos.set_target_volume(-3)
+          if short_avg.iloc[-2] < long_avg.iloc[-2] and short_avg.iloc[-1] > long_avg.iloc[-1]:
+            target_pos.set_target_volume(3)
+    except BacktestFinished:
+      api.close()
+      print("SHORT=", SHORT, "最终权益=", acc.account.balance)  # 每次回测结束时, 输出使用的参数和最终权益
+
+
+  if __name__ == '__main__':
+    multiprocessing.freeze_support()
+    p = Pool(4)                               # 进程池, 建议小于cpu数
+    for s in range(20, 40):
+      p.apply_async(MyStrategy, args=(s,))  # 把20个回测任务交给进程池执行
+    print('Waiting for all subprocesses done...')
+    p.close()
+    p.join()
+    print('All subprocesses done.')
+
+**注意: 由于服务器流控限制, 同时执行的回测任务请勿超过10个**

doc/_static/faq1.png

@@ -0,0 +1,41 @@
+.. _dingding:
+
+将程序信息推送到手机端
+=================================================
+TqSdk 并不提供专门的服务器来推送消息，但是你可以通过其他 SDK 来做到这个效果，在发生成交或者条件满足时，进行消息推送，以钉钉为例::
+
+    from datetime import datetime, time, timedelta
+    import requests
+    from json import dumps
+    from tqsdk import TqApi, TqAuth, TargetPosTask
+
+
+    def send_msg(content):
+        """钉钉消息提醒模块"""
+        webhook = "设置自己的钉钉 webhook"
+
+        # 钉钉安全规则将 天勤量化 设为关键字
+        msg = {"msgtype": "text",
+               "text": {"content": "{}\n{}\n".format("天勤量化\n" + content,
+                                                     datetime.now().strftime("%Y-%m-%d %H:%M:%S"))}, }
+        headers = {"content-type": "application/json;charset=utf-8"}
+        body = dumps(msg)
+        requests.post(webhook, data=body, headers=headers)
+        print(content)
+
+
+    api = TqApi(auth=TqAuth("信易账户", "账户密码"))
+    quote = api.get_quote("SHFE.rb2109")
+    target_pos = TargetPosTask(api, "SHFE.rb2110")
+    send_msg("策略开始运行")
+    a = 0
+    while True:
+        api.wait_update()
+        # 通过本地变量 a 来避免多次发送钉钉消息触发流控
+        if quote.last_price > 5110 and a == 0:
+            send_msg("行情满足条件，开多头5手")
+            target_pos.set_target_volume(5)
+            a = 1
+
+
+具体说明，请参考 `钉钉操作手册 <https://developers.dingtalk.com/document/app/custom-robot-access>`_

doc/_static/trading_system.svg

@@ -0,0 +1,104 @@
+.. _entry:
+
+策略程序的多种入口场景
+====================================================
+基于TqSdk开发的策略程序可能在多种场景下运行
+
+用户自己在独立python环境下执行策略程序
+----------------------------------------------------
+一种常见的运行方式是用户自己运行python策略程序, 象这样::
+
+    $python3 my_prog.py
+
+在这种场景下，用户需要在TqApi创建时提供必要的参数
+
+TqApi 独立运行模拟交易
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+创建 TqApi 实例时传入 TqSim ::
+
+    from tqsdk import TqApi, TqAuth, TqSim
+    api = TqApi(TqSim(), auth=TqAuth("信易账户", "账户密码"))
+
+或者不填其他参数, 默认为使用TqSim::
+
+    api = TqApi(auth=TqAuth("信易账户", "账户密码"))
+
+
+TqApi 独立运行实盘交易
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+创建 TqApi 实例时传入 TqAccount ::
+
+    from tqsdk import TqApi, TqAuth, TqAccount
+    api = TqApi(TqAccount("H海通期货", "022631", "123456"), auth=TqAuth("信易账户", "账户密码"))
+
+特别的, 如果需要连接到期货公司的特定服务器, 可以在 TqAccount 中指定::
+
+    api = TqApi(TqAccount("H海通期货", "022631", "123456", front_broker="8888", front_url="tcp://134.232.123.33:41205"), auth=TqAuth("信易账户", "账户密码"))
+
+如果要连接到自己架设的交易网关, 可以使用::
+
+    api = TqApi(TqAccount("H海通期货", "022631", "123456"), url="ws://202.33.21.34:7878/", auth=TqAuth("信易账户", "账户密码"))
+
+
+TqApi 独立运行回测
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+创建 TqApi 实例时传入 TqBacktest ::
+
+    from tqsdk import TqApi, TqAuth, TqSim, TqBacktest
+    api = TqApi(TqSim(), backtest=TqBacktest(start_dt=date(2018, 5, 1), end_dt=date(2018, 10, 1)), auth=TqAuth("信易账户", "账户密码"))
+
+
+由天勤拉起策略进程
+----------------------------------------------------
+策略程序由天勤拉起执行时, TqApi始终使用默认构造函数, 由天勤提供命令行参数设定策略程序运行方式. 命令行参数包括这些:
+
+* _action : run/backtest/mdreplay, 指定运行方式
+* _tq_pid : int, 天勤进程ID. 策略进程会监控天勤进程的存活情况, 天勤进程退出时所有由天勤创建的策略进程都会自行终止
+* _tq_url : str, 天勤ws入口. 策略进程通过此端口与天勤通讯
+
+当 _action == run 时, 策略程序按正常交易模式运行, 其它参数:
+
+* _broker_id : str, 期货公司代码
+* _account_id : str, 用户账号
+* _password : str, 用户密码
+
+当 _action == backtest 时, 策略程序按回测模式运行, 其它参数:
+
+* _dt_start : YYYYMMDD, 回测起始日期
+* _dt_end : YYYYMMDD, 回测结束日期
+
+当 _action == mdreplay 时, 策略程序按复盘模式运行, 其它参数:
+
+* _ins_url : url, 合约服务地址
+* _md_url : url, 行情服务地址
+
+
+天勤发起实盘运行(含快期模拟)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+天勤通过命令行参数传递交易账户信息给策略进程::
+
+    $ python3 my_prog.py --_action=run --_tq_pid=3233 --_tq_url=ws://127.0.0.1:7777 --_broker_id=快期模拟 --_account_id=13012345678 --_password=123456
+
+
+天勤发起回测
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+天勤通过命令行参数传递交易账户信息给策略进程::
+
+    $ python3 my_prog.py --_action=backtest --_tq_pid=3233 --_tq_url=ws://127.0.0.1:7777 --_dt_start=20180101 --_dt_end=20180630
+
+
+天勤发起复盘
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+天勤先创建好复盘服务器, 再传递::
+
+    $ python3 my_prog.py --_action=mdreplay --_tq_pid=3233 --_tq_url=ws://127.0.0.1:7777 --_md_url=ws://239.12.212.34:43232/... --ins_url=http://123.23.12.34/...
+
+
+更复杂的情形
+----------------------------------------------------
+
+将独立运行的策略进程连接到天勤作监控
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+暂未支持
+
+

doc/advanced/backtest.rst

@@ -0,0 +1,38 @@
+使用逐步完善的方式构建交易策略
+=================================================
+`TqSdk`_ 的目标是能尽可能减少编码环节引入的坑，而交易逻辑本身的坑则需要用户自己填，如果每次调整交易逻辑都需要大规模的代码重构会严重阻碍交易系统的演化。
+
+`TqSdk`_ 鼓励使用线性的编码风格，因此可以做到小调交易逻辑只需小改，只有大调交易逻辑时才需要大改。以 `R-Breaker`_ 策略为例，
+第一版是留仓过夜，回测下来可能发现留仓过夜引入了很大的风险，却没有获得与风险对应的收益，因此修改交易策略，收盘前清仓离场，
+对应代码的修改只需在主循环中加入判断是否接近收盘并平仓::
+
+    if api.is_changing(quote, "datetime"):
+        now = datetime.strptime(quote.datetime, "%Y-%m-%d %H:%M:%S.%f")
+        if now.hour == close_hour and now.minute >= close_minute:  # 到达平仓时间: 平仓
+            print("临近本交易日收盘: 平仓")
+            target_pos.set_target_volume(0)  # 平仓
+            deadline = time.time() + 60
+            while api.wait_update(deadline=deadline):  # 等待60秒
+                pass
+            api.close()
+            break
+
+上述代码在行情时间变化时判断是否接近收盘，如果是的话则将目标持仓设为0(即空仓)。由于下单之后不一定能立即成交，价格变化后可能还需撤单重下，
+因此等待一分钟后再退出，通常交易的合约不是太冷门的话一分钟应该足够了，如果不放心的话可以改为判断持仓手数是否为0。
+
+更多的用例可以参见: https://doc.shinnytech.com/pysdk/latest/demo.html
+
+
+
+
+.. _TqSdk: https://doc.shinnytech.com/pysdk/latest/index.html
+.. _TqSim: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.sim.TqSim
+.. _get_kline_serial: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.api.TqApi.get_kline_serial
+.. _TargetPosTask: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.lib.TargetPosTask
+.. _wait_update: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.api.TqApi.wait_update
+.. _DIFF: https://doc.shinnytech.com/diff/latest/index.html
+.. _get_account: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.api.TqApi.get_account
+.. _get_quote: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.api.TqApi.get_quote
+.. _is_changing: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.api.TqApi.is_changing
+.. _TqBacktest: https://doc.shinnytech.com/pysdk/latest/reference.html#tqsdk.backtest.TqBacktest
+.. _R-Breaker: https://github.com/shinnytech/tqsdk-python/blob/master/tqsdk/demo/example/rbreaker.py