.. 本文件是Cvxportfolio的一部分。

.. Cvxportfolio是自由软件：你可以根据自由软件基金会发布的GNU通用公共许可证的条款重新分发或修改它， .. 可以选择使用第3版许可证，或（根据你的选择）任何更新的版本。

.. Cvxportfolio的发布是希望它能够有用，但不提供任何保证；甚至不提供对适销性或特定用途适用性的暗示保证。 .. 更多细节请参见GNU通用公共许可证。

.. 你应该已经收到了GNU通用公共许可证的副本以及Cvxportfolio。 .. 如果没有，请查看https://www.gnu.org/licenses/。

`Cvxportfolio <https://www.cvxportfolio.com>`_

Cvxportfolio <https://cvxportfolio.readthedocs.io>_是一个面向对象的投资组合优化和回测库。它实现了相关论文<https://cvxportfolio.readthedocs.io/en/stable/_static/cvx_portfolio.pdf>_中描述的模型。

该库的文档位于www.cvxportfolio.com <https://www.cvxportfolio.com>_。

.. 安装

新闻：

自2023年底以来，我们每天都在使用开发（master）分支<https://github.com/cvxgrp/cvxportfolio/tree/master/>运行示例策略<https://github.com/cvxgrp/cvxportfolio/tree/master/examples/strategies>；每天我们都会将目标权重和初始持仓提交到存储库。运行它们的所有代码，包括cron脚本<https://github.com/cvxgrp/cvxportfolio/blob/master/strategies_runner.sh>_，都在存储库中。

安装

Cvxportfolio是用Python <https://docs.python.org/>_编写的，可以在任何Python环境<https://docs.python.org/3/library/venv.html>_中通过简单的方式安装：

.. code:: bash

pip install -U cvxportfolio

你可以在我们的安装和Hello World <https://youtu.be/1ThOKEu371M>_ YouTube视频中看到它是如何工作的。 Anaconda安装也受支持 <https://anaconda.org/conda-forge/cvxportfolio>_。

Cvxportfolio的主要依赖项是Cvxpy <https://www.cvxpy.org>（用于与数值求解器接口）和Pandas <https://pandas.pydata.org/>（用于与数据库接口）。我们不要求特定版本的依赖项，并测试了所有最近的版本（可追溯到几年前）。

高级：安装开发版本


你也可以安装开发版本。它每天都通过示例策略进行测试。我们将其托管在`master分支<https://github.com/cvxgrp/cvxportfolio/tree/master/>`_中。它以当前稳定版本命名；每次发布新版本时，我们都会`用git标记它<https://github.com/cvxgrp/cvxportfolio/tags>`_。
如果这听起来很复杂，请避免安装开发版本。

.. code:: bash

   pip install --upgrade --force-reinstall git+https://github.com/cvxgrp/cvxportfolio@master

.. 测试

测试
----

安装后，你可以在本地环境中运行我们的单元测试套件：

.. code:: bash

   python -m cvxportfolio.tests

我们针对最新的Python版本（3.8、3.9、3.10、3.11、3.12）和主要依赖项的最新版本（从pandas 1.4、cvxpy 1.1开始，一直到当前版本）在所有主要操作系统上进行测试。你可以查看`自动测试代码<https://github.com/cvxgrp/cvxportfolio/blob/master/.github/workflows/test.yml>`_。

.. 简单示例

简单示例
--------------

在以下示例中，市场数据由公共来源（Yahoo finance）下载，预测在回测的每个时间点上通过过去的数据迭代计算。

.. code:: python

   import cvxportfolio as cvx

   gamma = 3       # 风险厌恶参数（第4.2章）
   kappa = 0.05    # 协方差预测误差风险参数（第4.3章）
   objective = cvx.ReturnsForecast() - gamma * (
       cvx.FullCovariance() + kappa * cvx.RiskForecastError()
   ) - cvx.StocksTransactionCost()
   constraints = [cvx.LeverageLimit(3)]

   policy = cvx.MultiPeriodOptimization(objective, constraints, planning_horizon=2)

   simulator = cvx.StockMarketSimulator(['AAPL', 'AMZN', 'TSLA', 'GM', 'CVX', 'NKE'])

   result = simulator.backtest(policy, start_time='2020-01-01')

   # 打印回测结果统计
   print(result)

   # 绘制回测结果
   result.plot()
在回测的每个时间点，策略对象只处理**历史数据**，因此得到的结果是该策略在实际市场中表现的真实模拟。收益率预测采用历史平均收益率，协方差采用历史协方差（均忽略``np.nan``）。模拟器默认包含持仓成本和交易成本，使用论文中描述的模型，以及美国股票市场的典型默认参数。

其他示例
--------

文档网站上展示了`许多示例<https://cvxportfolio.readthedocs.io/en/stable/examples.html>`_，包括输出结果和注释。

代码仓库中还提供了`更多示例脚本<https://github.com/cvxgrp/cvxportfolio/blob/master/examples>`_。

我们在`用户自定义预测器<https://cvxportfolio.readthedocs.io/en/stable/examples/user_provided_forecasters.html>`_的示例中展示了用户如何定义自定义类来预测预期收益率和协方差。这些类提供在回测过程中每个时间点执行的回调函数。系统确保因果性和数值错误的安全性。我们建议在进行任何分析时都包含我们提供的默认预测器，因为它们非常稳健且经过充分测试。

我们在`道琼斯30指数成分股<https://cvxportfolio.readthedocs.io/en/stable/examples/dow30.html>`_和`大类资产ETF<https://cvxportfolio.readthedocs.io/en/stable/examples/etfs.html>`_的示例中展示了如何利用我们复杂的并行回测机制进行简单的超参数扫描，快速得出适用于任何给定资产组合的最佳策略结果。

类似项目
--------

有许多用于投资组合优化和回测的软件项目。Python生态系统中一些值得注意的项目包括：`Zipline <https://github.com/quantopian/zipline>`_，它实现了与我们提供的非常相似的回测回调模型；`Riskfolio-Lib <https://riskfolio-lib.readthedocs.io/en/latest/examples.html>`_，它实现了（许多！）投资组合优化模型，并采用与我们类似的模块化方法；`VectorBT <https://vectorbt.dev/>`_，一个适用于高频应用的回测库；`PyPortfolioOpt <https://pyportfolioopt.readthedocs.io/en/latest/>`_，一个简单但功能强大的投资组合优化库，使用众所周知的模型；`YFinance <https://github.com/ranaroussi/yfinance>`_，虽然不是投资组合优化库（它只提供雅虎财经的数据接口），但曾是我们的依赖项之一；以及`CVXPY <https://www.cvxpy.org>`_本身，它被上述一些库使用，并有一套专门用于投资组合优化的`示例集<https://www.cvxpy.org/examples/index.html#finance>`_（事实上，Cvxportfolio就是从这些示例发展而来的）。

贡献
----

我们欢迎贡献，您无需签署CLA。

即使您不熟悉该库的底层细节，修复bug、改进文档和示例、添加新的约束条件、新的成本对象等都是很好的贡献。

开发
----

要在本地设置开发环境，您应该克隆仓库（或者在Github上`fork<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_，然后克隆您的fork）

.. code:: bash

   git clone https://github.com/cvxgrp/cvxportfolio.git
   cd cvxportfolio

然后，您应该查看我们的`Makefile <https://www.gnu.org/software/make/manual/make.html#Introduction>`_，并可能需要更改``PYTHON``变量以匹配您系统的Python解释器。完成后，执行：

.. code:: bash

   make env
   make test

这将复制我们的`开发环境<https://docs.python.org/3/library/venv.html>`_并运行我们的测试套件。

您可以使用``env/bin``（Windows上为``env\Scripts``）中的脚本之一激活shell环境，例如，如果您在POSIX上使用bash：

.. code:: bash

   source env/bin/activate

在环境中，您可以运行examples目录下的任何脚本（cvxportfolio包以`可编辑模式<https://setuptools.pypa.io/en/latest/userguide/development_mode.html>`_安装）。或者，如果您不想激活环境，可以像我们在Makefile中那样直接使用``env/bin/python``（Windows上为``env\Scripts\python``）运行脚本。

此外，为了匹配我们的CI/CD流程，您可以设置以下`git hooks <https://git-scm.com/docs/githooks>`_：

.. code:: bash

   echo "make lint" > .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   echo "make test" > .git/hooks/pre-push
   chmod +x .git/hooks/pre-push

代码风格和质量
--------------
Cvxportfolio遵循PEP8代码风格规范。这通过Pylint自动检查工具强制执行，相关选项在Pyproject配置文件中设置。Pylint还用于强制执行代码质量标准，以及一些可选插件。

文档字符串采用Sphinx风格编写，同样由Pylint检查，并用于生成文档。

版本和发布
---------------------

Cvxportfolio遵循语义化版本规范。在下一个主版本（2.0.0）之前，不会对其公共API引入破坏性更改，而这还需要一段时间。公共API的新功能会在次要版本（1.1.0、1.2.0等）中引入，每次修订仅进行错误修复。

我们的发布历史（源代码分发和轮子）可在PyPI页面上查看。

发布也在我们的Git仓库中标记，并在其提交消息中包含简短的更改摘要。

引用
------------

如果您在导致出版的工作中使用了Cvxportfolio，您可以引用以下内容：

[此处省略引用内容]

后者也是以下博士论文的第一章：

[此处省略引用内容]

法律声明
-----

Cvxportfolio是自由软件。它根据通用公共许可证第3版的条款发布。