Cvxportfolio Documentation#

Cvxportfolio is a Python library for portfolio optimization. It enables users to quickly try optimization policies for asset management by back-testing their past performance with a sophisticated market simulator.

Most models implemented by Cvxportfolio, including the accounting methods, naming conventions, and assumptions, are described in the accompanying paper. This was written as a collaborative work by Stanford University researchers and BlackRock Inc. investment professionals.

News:

Since end of 2023 we’re running daily example strategies using the development (master) branch.; each day we commit target weights and initial holdings to the repository. All the code that runs them, including the cron script, is in the repository.

Installation#

Cvxportolio is written in Python and can be installed in any Python environment by simple:

pip install -U cvxportfolio

You can see how this works on our Installation and Hello World Youtube video. Anaconda installs are also supported.

Cvxportfolio’s main dependencies are Cvxpy for interfacing with numerical solvers and Pandas for interfacing with databases. We don’t require any specific version of our dependencies and test against all recent ones (up to a few years ago).

Advanced: install development version#

You can also install the development version. It is tested daily by the example strategies. We host it in the master branch. It is named after the current stable version; each time we make a new release we tag it with git. If this sounds complicated, avoid installing the development version.

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

Test#

After installing you can run our unit test suite in you local environment by

python -m cvxportfolio.tests

We test against recent python versions (3.8, 3.9, 3.10, 3.11, 3.12) and recent versions of the main dependencies (from pandas 1.4, cvxpy 1.1, …, up to the current versions) on all major operating systems. You can see the automated testing code.

Introduction#

Cvxportfolio is an object-oriented library for portfolio optimization and back-testing which focuses on ease of use. It implements the models described in the accompanying paper. and can be extended with user-defined objects and methods to accommodate different data sources, custom cost models (both for simulation and optimization), constraints, and so on.

The main abstractions used are the cvxportfolio.MarketSimulator, which faithfully mimics the trading activity of a financial market, the collection of policies, which include both simple policies such as cvxportfolio.RankAndLongShort, and the optimization-based policies cvxportfolio.SinglePeriodOptimization and cvxportfolio.MultiPeriodOptimization. For these two, the user specifies the objective function (which is maximized) and a list of constraints which apply to the optimization. All these types of objects can be customized in many ways, including by deriving or redefining them.

Then, we provide the cvxportfolio.data.MarketData abstraction, which both serves historical data during a back-test and real time data in online usage. We implement the interface to public data sources (Yahoo Finance and FRED), as well as user-provided data, which can also be passed to all other objects, see the manual section on passing data.

In addition, we provide logic to easily parallelize back-testing of many different policies, or the same policy with different choices of hyperparameters, and cache on disk both historical data (for reproducibility) and various expensive calculations, such as estimates of covariance matrices.

We present the results of each back-test with a clear interface, cvxportfolio.result.BacktestResult, which defines various metrics of backtest performance and the logic to both print and plot them.

Where to go next#

You can see the selection of examples in this documentation website (even more are available in the code repository).

Then, you can have a look at the manual page which explains some of the more important aspects to understand when using Cvxportfolio.

Or, you can look directly at the documentation of each object the user interacts with, like the market simulator, the collection of both simple and optimization-based policies, the objective terms (return, risk and cost models, which all have their specifities) or constraints which apply to optimization-based policies, and so on.

Versions and releases#

Cvxportfolio follows the semantic versioning specification. No breaking change in its public API will be introduced until the next major version (2.0.0), which won’t happen for some time. New features in the public API are introduced with minor versions (1.1.0, 1.2.0, …), and only bug fixes at each revision.

The history of our releases (source distributions and wheels) is visible on our PyPI page.

Releases are also tagged in our git repository and include a short summary of changes in their commit messages.

Citing#

If you use Cvxportfolio in work that leads to publication, you can cite the following:

@misc{busseti2017cvx,
    author    = "Busseti, Enzo and Diamond, Steven and Boyd, Stephen",
    title     = "Cvxportfolio",
    month    = "January",
    year     = "2017",
    note     = "Portfolio Optimization and Back--{T}esting",
    howpublished = {\url{https://github.com/cvxgrp/cvxportfolio}},
}

@article{boyd2017multi,
  author  = "Boyd, Stephen and Busseti, Enzo and Diamond, Steven and Kahn, Ron and Nystrup, Peter and Speth, Jan",
  journal = "Foundations and Trends in Optimization",
  title   = "Multi--{P}eriod Trading via Convex Optimization",
  month   = "August",
  year    = "2017",
  number  = "1",
  pages   = "1--76",
  volume  = "3",
  url     = {\url{https://stanford.edu/~boyd/papers/pdf/cvx_portfolio.pdf}},
}

The latter is also the first chapter of this PhD thesis:

@phdthesis{busseti2018portfolio,
    author    = "Busseti, Enzo",
    title     = "Portfolio Management and Optimal Execution via Convex Optimization",
    school    = "Stanford University",
    address   = "Stanford, California, USA",
    month    = "May",
    year     = "2018",
    url     = {\url{https://stacks.stanford.edu/file/druid:wm743bj5020/thesis-augmented.pdf}},
}

Table of Contents#