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 version (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 easily 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).
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.
We maintain a document listing the planned changes and target releases.
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}},
}
Licensing¶
Cvxportfolio is licensed under the Apache 2.0 permissive open source license.
Table of Contents¶
- Manual
- Simulator
- Trading policies
- Return models
- Risk models
- Cost models
- Constraints
DollarNeutral
MarketNeutral
FactorMaxLimit
FactorMinLimit
FactorGrossLimit
FactorNeutral
FixedFactorLoading
LeverageLimit
LongCash
LongOnly
MaxWeights
MinWeights
MaxBenchmarkDeviation
MinBenchmarkDeviation
ParticipationRateLimit
TurnoverLimit
- Soft constraints
- Cost inequality as constraint
- Base classes (for extending Cvxportfolio)
- Back-test result
- Data Interfaces
- Internal Objects and Interfaces
- Examples
- Contributing to Cvxportfolio