{"id":13533759,"url":"https://github.com/cvxgrp/cvxportfolio","last_synced_at":"2025-05-14T00:08:23.224Z","repository":{"id":48462670,"uuid":"78590085","full_name":"cvxgrp/cvxportfolio","owner":"cvxgrp","description":"Portfolio optimization and back-testing.","archived":false,"fork":false,"pushed_at":"2025-05-07T18:43:07.000Z","size":175909,"stargazers_count":1075,"open_issues_count":27,"forks_count":267,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-05-07T19:43:15.391Z","etag":null,"topics":["convex-optimization","finance","optimization","optimization-algorithms","optimization-methods","optimizer","portfolio-optimization","python","time-series"],"latest_commit_sha":null,"homepage":"https://www.cvxportfolio.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cvxgrp.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"docs/contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-11T01:16:16.000Z","updated_at":"2025-05-07T18:43:11.000Z","dependencies_parsed_at":"2024-01-22T09:49:23.509Z","dependency_job_id":"9a7e693f-e74c-485b-b7c2-ac79cc6f3c71","html_url":"https://github.com/cvxgrp/cvxportfolio","commit_stats":{"total_commits":505,"total_committers":15,"mean_commits":"33.666666666666664","dds":0.5782178217821783,"last_synced_commit":"9eef395c63dafc5927e9bd89f5cb4f0f464e64c4"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvxgrp%2Fcvxportfolio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvxgrp%2Fcvxportfolio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvxgrp%2Fcvxportfolio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvxgrp%2Fcvxportfolio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cvxgrp","download_url":"https://codeload.github.com/cvxgrp/cvxportfolio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043981,"owners_count":22005047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["convex-optimization","finance","optimization","optimization-algorithms","optimization-methods","optimizer","portfolio-optimization","python","time-series"],"created_at":"2024-08-01T07:01:22.847Z","updated_at":"2025-05-14T00:08:18.208Z","avatar_url":"https://github.com/cvxgrp.png","language":"Python","funding_links":[],"categories":["Analytic tools","Python"],"sub_categories":["Optimization"],"readme":".. Copyright (C) 2023-2024 Enzo Busseti\n.. Copyright (C) 2016 Enzo Busseti, Stephen Boyd, Steven Diamond, BlackRock Inc.\n\n.. This file is part of Cvxportfolio.\n\n.. Cvxportfolio is free software: you can redistribute it and/or modify it under\n.. the terms of the GNU General Public License as published by the Free Software\n.. Foundation, either version 3 of the License, or (at your option) any later\n.. version.\n\n.. Cvxportfolio is distributed in the hope that it will be useful, but WITHOUT\n.. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS\n.. FOR A PARTICULAR PURPOSE. See the GNU General Public License for more\n.. details.\n\n.. You should have received a copy of the GNU General Public License along with\n.. Cvxportfolio. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n`Cvxportfolio \u003chttps://www.cvxportfolio.com\u003e`__\n===============================================\n\n|CVXportfolio on PyPI| |linting: pylint| |Coverage Status|\n|Documentation Status| |GPLv3| |Anaconda-Server Badge|\n\n\n`Cvxportfolio \u003chttps://cvxportfolio.readthedocs.io\u003e`__ is an object-oriented\nlibrary for portfolio optimization and back-testing. It implements models\ndescribed in the `accompanying paper\n\u003chttps://cvxportfolio.readthedocs.io/en/stable/_static/cvx_portfolio.pdf\u003e`_.\n\nThe documentation of the library is at\n`www.cvxportfolio.com \u003chttps://www.cvxportfolio.com\u003e`_.\n\n.. Installation\n\n*News:*\n\n   Since end of 2023 we're running daily `example strategies\n   \u003chttps://github.com/cvxgrp/cvxportfolio/tree/master/examples/strategies\u003e`_\n   using the `development (master) branch\n   \u003chttps://github.com/cvxgrp/cvxportfolio/tree/master/\u003e`_.; each day we commit\n   target weights and initial holdings to the repository. All the code that\n   runs them, including the `cron script\n   \u003chttps://github.com/cvxgrp/cvxportfolio/blob/master/strategies_runner.sh\u003e`_,\n   is in the repository.\n\nInstallation\n------------\n\nCvxportolio is written in `Python \u003chttps://docs.python.org/\u003e`_ and can be\ninstalled in any `Python environment\n\u003chttps://docs.python.org/3/library/venv.html\u003e`_ by simple:\n\n.. code:: bash\n\n   pip install -U cvxportfolio\n\nYou can see how this works on our `Installation and Hello\nWorld \u003chttps://youtu.be/1ThOKEu371M\u003e`_ Youtube video.\nAnaconda installs \n`are also supported \u003chttps://anaconda.org/conda-forge/cvxportfolio\u003e`_.\n\nCvxportfolio's main dependencies are `CVXPY \u003chttps://www.cvxpy.org\u003e`__ for\ninterfacing with numerical solvers and `Pandas \u003chttps://pandas.pydata.org/\u003e`_\nfor interfacing with databases. We don't require any specific version of our\ndependencies and test against all recent ones (up to a few years ago).\n\nAdvanced: install development version\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can also install the development version. It is tested daily by the\nexample strategies. We host it in the `master branch\n\u003chttps://github.com/cvxgrp/cvxportfolio/tree/master/\u003e`_. It is named after\nthe current stable version; each time we make a new release we `tag it with git\n\u003chttps://github.com/cvxgrp/cvxportfolio/tags\u003e`_.\nIf this sounds complicated, avoid installing the development\nversion.\n\n.. code:: bash\n\n   pip install --upgrade --force-reinstall git+https://github.com/cvxgrp/cvxportfolio@master\n\n.. Test\n\nTest\n----\n\nAfter installing you can run our unit test suite in you local environment by\n\n.. code:: bash\n\n   python -m cvxportfolio.tests\n\nWe test against recent Python versions (3.8, 3.9, 3.10, 3.11, 3.12) and recent versions\nof the main dependencies (from Pandas 1.4, CVXPY 1.1, ..., up to the current\nversions) on all major operating systems. You can see the `automated testing code \n\u003chttps://github.com/cvxgrp/cvxportfolio/blob/master/.github/workflows/test.yml\u003e`_.\n\n\n.. Simple Example\n\nSimple example\n--------------\n\nIn the following example market data is downloaded by a public source\n(Yahoo finance) and the forecasts are computed iteratively, at each\npoint in the backtest, from past data.\n\n.. code:: python\n\n   import cvxportfolio as cvx\n\n   gamma = 3       # risk aversion parameter (Chapter 4.2)\n   kappa = 0.05    # covariance forecast error risk parameter (Chapter 4.3)\n   objective = cvx.ReturnsForecast() - gamma * (\n       cvx.FullCovariance() + kappa * cvx.RiskForecastError()\n   ) - cvx.StocksTransactionCost()\n   constraints = [cvx.LeverageLimit(3)]\n\n   policy = cvx.MultiPeriodOptimization(objective, constraints, planning_horizon=2)\n\n   simulator = cvx.StockMarketSimulator(['AAPL', 'AMZN', 'TSLA', 'GM', 'CVX', 'NKE'])\n\n   result = simulator.backtest(policy, start_time='2020-01-01')\n\n   # print back-test result statistics\n   print(result)\n\n   # plot back-test results\n   result.plot()\n\nAt each point in the back-test, the policy object only operates on\n**past data**, and thus the result you get is a realistic simulation of\nwhat the strategy would have performed in the market. Returns are\nforecasted as the historical mean returns and covariances as historical\ncovariances (both ignoring ``np.nan``\\ ’s). The simulator by default\nincludes holding and transaction costs, using the models described in\nthe paper, and default parameters that are typical for the US stock\nmarket.\n\nOther examples\n--------------\n\n`Many examples \n\u003chttps://cvxportfolio.readthedocs.io/en/stable/examples.html\u003e`_\nare shown in the documentation website, along with\ntheir output and comments.\n\n`Even more example scripts\n\u003chttps://github.com/cvxgrp/cvxportfolio/blob/master/examples\u003e`_ \nare available in the code repository. \n\nWe show in the example on `user-provided\nforecasters \u003chttps://cvxportfolio.readthedocs.io/en/stable/examples/user_provided_forecasters.html\u003e`_\nhow the user can define custom classes to forecast the expected returns\nand covariances. These provide callbacks that are executed at each point\nin time during the back-test. The system enforces causality and safety\nagainst numerical errors. We recommend to always include the default\nforecasters that we provide in any analysis you may do, since they are\nvery robust and well-tested.\n\nWe show in the examples on `DOW30\ncomponents \u003chttps://cvxportfolio.readthedocs.io/en/stable/examples/dow30.html\u003e`_\nand `wide assets-classes\nETFs \u003chttps://cvxportfolio.readthedocs.io/en/stable/examples/etfs.html\u003e`_\nhow a simple sweep over hyper-parameters, taking advantage of our\nsophisticated parallel backtest machinery, quickly provides results on\nthe best strategy to apply to any given selection of assets.\n\nSimilar projects\n----------------\n\nThere are many software projects for portfolio optimization and back-testing.\nSome notable ones in the Python ecosystem are `Zipline \u003chttps://github.com/quantopian/zipline\u003e`_,\nwhich implements a call-back model for back-testing very similar to the one\nwe provide, `Riskfolio-Lib \u003chttps://riskfolio-lib.readthedocs.io/en/latest/examples.html\u003e`_\nwhich implements (many!) portfolio optimization models and also follows a modular\napproach like ours, `VectorBT \u003chttps://vectorbt.dev/\u003e`_, a back-testing library\nwell-suited for high frequency applications, `PyPortfolioOpt \u003chttps://pyportfolioopt.readthedocs.io/en/latest/\u003e`_,\na simple yet powerful library for portfolio optimization that uses well-known models,\n`YFinance \u003chttps://github.com/ranaroussi/yfinance\u003e`_, which is not a portfolio\noptimization library (it only provides a data interface to Yahoo Finance), but\nused to be one of our dependencies, and also `CVXPY \u003chttps://www.cvxpy.org\u003e`__ by\nitself, which is used by some of the above and has an extensive \n`set of examples \u003chttps://www.cvxpy.org/examples/index.html#finance\u003e`_\ndevoted to portfolio optimization (indeed, Cvxportfolio was born out of those).\n\n.. Contributions\n\nContributions\n-------------\n\nWe welcome contributions and you don't need to sign a CLA.\n\nBug fixes, improvements in the documentations and examples,\nnew constraints, new cost objects, ..., are good contributions and can be done\neven if you're not familiar with the low-level details on the library.\n\nDevelopment\n-----------\n\nTo set up a development environment locally you should clone the\nrepository (or, `fork on\nGithub \u003chttps://docs.github.com/en/get-started/quickstart/fork-a-repo\u003e`_\nand then clone your fork)\n\n.. code:: bash\n\n   git clone https://github.com/cvxgrp/cvxportfolio.git\n   cd cvxportfolio\n\n.. We develop in the ``main`` branch. So you should `check out\n.. \u003chttps://git-scm.com/docs/git-checkout\u003e`_ that one. The default branch shown on\n.. the homepage of the repository is the ``master`` branch. It hosts the last\n.. release.\n\nThen, you should have a look at our\n`Makefile \u003chttps://www.gnu.org/software/make/manual/make.html#Introduction\u003e`_\nand possibly change the ``PYTHON`` variable to match your system's\npython interpreter. Once you have done that,\n\n.. code:: bash\n\n   make env\n   make test\n\nThis will replicate our `development\nenvironment \u003chttps://docs.python.org/3/library/venv.html\u003e`_ and run our\ntest suite.\n\nYou activate the shell environment with one of scripts in ``env/bin``\n(or ``env\\Scripts`` on Windows), for example if you use bash on POSIX\n\n.. code:: bash\n\n   source env/bin/activate\n\nand from the environment you can run any of the scripts in the examples\n(the cvxportfolio package is installed in `editable\nmode \u003chttps://setuptools.pypa.io/en/latest/userguide/development_mode.html\u003e`_).\nOr, if you don't want to activate the environment, you can just run\nscripts directly using ``env/bin/python`` (or ``env\\Scripts\\python`` on\nWindows) like we do in the Makefile.\n\nAdditionally, to match our CI/CD pipeline, you may set the following\n`git hooks \u003chttps://git-scm.com/docs/githooks\u003e`_\n\n.. code:: bash\n\n   echo \"make lint\" \u003e .git/hooks/pre-commit\n   chmod +x .git/hooks/pre-commit\n   echo \"make test\" \u003e .git/hooks/pre-push\n   chmod +x .git/hooks/pre-push\n\n\nCode style and quality\n----------------------\n\nCvxportfolio follows the `PEP8 \u003chttps://peps.python.org/pep-0008/\u003e`_\nspecification for code style. This is enforced by the `Pylint\n\u003chttps://pylint.readthedocs.io/en/stable/\u003e`_ automated linter, with options \nin the `Pyproject \n\u003chttps://github.com/cvxgrp/cvxportfolio/blob/master/pyproject.toml\u003e`_\nconfiguration file.\nPylint is also used to enforce code quality standards, along with some of its\noptional plugins.\nDocstrings are written in the `Sphinx style \n\u003chttps://www.sphinx-doc.org/en/master/index.html\u003e`_, are also checked by \nPylint, and are used to generate the documentation.\n\n.. Versions\n\nVersions and releases\n---------------------\n\nCvxportfolio follows the `semantic versioning \u003chttps://semver.org\u003e`_\nspecification. No breaking change in its public API will be introduced\nuntil the next major version (``2.0.0``), which won't happen for some time. \nNew features in the public API are introduced with minor versions \n(``1.1.0``, ``1.2.0``, ...), and only bug fixes at each revision.\n\nThe history of our releases (source distributions and wheels) is visible on our \n`PyPI page \u003chttps://pypi.org/project/cvxportfolio/#history\u003e`_.\n\nReleases are also tagged in our git repository and include a short summary\nof changes in \n`their commit messages \u003chttps://github.com/cvxgrp/cvxportfolio/tags\u003e`_.\n\n\n.. Citing\n\nCiting\n------------\n\nIf you use Cvxportfolio in work that leads to publication, you can cite the following:\n\n.. code-block:: bibtex\n\n    @misc{busseti2017cvx,\n        author    = \"Busseti, Enzo and Diamond, Steven and Boyd, Stephen\",\n        title     = \"Cvxportfolio\",\n        month    = \"January\",\n        year     = \"2017\",\n        note     = \"Portfolio Optimization and Back--{T}esting\",\n        howpublished = {\\url{https://github.com/cvxgrp/cvxportfolio}},\n    }\n\n    @article{boyd2017multi,\n      author  = \"Boyd, Stephen and Busseti, Enzo and Diamond, Steven and Kahn, Ron and Nystrup, Peter and Speth, Jan\",\n      journal = \"Foundations and Trends in Optimization\",\n      title   = \"Multi--{P}eriod Trading via Convex Optimization\",\n      month   = \"August\",\n      year    = \"2017\",\n      number  = \"1\",\n      pages   = \"1--76\",\n      volume  = \"3\",\n      url     = {\\url{https://stanford.edu/~boyd/papers/pdf/cvx_portfolio.pdf}},\n    }\n\n\nThe latter is also the first chapter of this PhD thesis:\n\n.. code-block:: bibtex\n\n    @phdthesis{busseti2018portfolio,\n        author    = \"Busseti, Enzo\",\n        title     = \"Portfolio Management and Optimal Execution via Convex Optimization\",\n        school    = \"Stanford University\",\n        address   = \"Stanford, California, USA\",\n        month    = \"May\",\n        year     = \"2018\",\n        url     = {\\url{https://stacks.stanford.edu/file/druid:wm743bj5020/thesis-augmented.pdf}},\n    }\n\n\nLegal\n-----\n\nCvxportfolio is `free software \u003chttps://www.gnu.org/philosophy/free-sw.html\u003e`_.\nIt is released under the terms of the `General Public License, version 3\n\u003chttps://www.gnu.org/licenses/gpl-3.0.html\u003e`_.\n\n.. |CVXportfolio on PyPI| image:: https://img.shields.io/pypi/v/cvxportfolio.svg\n   :target: https://pypi.org/project/cvxportfolio/\n.. |linting: pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen\n   :target: https://github.com/pylint-dev/pylint\n.. |Coverage Status| image:: https://coveralls.io/repos/github/cvxgrp/cvxportfolio/badge.svg?branch=master\n   :target: https://coveralls.io/github/cvxgrp/cvxportfolio?branch=master\n.. |Documentation Status| image:: https://readthedocs.org/projects/cvxportfolio/badge/?version=stable\n   :target: https://cvxportfolio.readthedocs.io/en/stable/?badge=stable\n.. |GPLv3| image:: https://img.shields.io/badge/License-GPLv3-blue.svg\n   :target: https://www.gnu.org/licenses/gpl-3.0\n.. |Anaconda-Server Badge| image:: https://anaconda.org/conda-forge/cvxportfolio/badges/version.svg\n   :target: https://anaconda.org/conda-forge/cvxportfolio\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvxgrp%2Fcvxportfolio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcvxgrp%2Fcvxportfolio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvxgrp%2Fcvxportfolio/lists"}