From bbe56de9ce8bebc24249bedb5b9285d93833079d Mon Sep 17 00:00:00 2001 From: Thomas Schmelzer Date: Mon, 10 Nov 2025 17:30:53 +0400 Subject: [PATCH 1/4] revisit the README file --- README.md | 91 ++++++++++++++++++------------------------------------- 1 file changed, 30 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 120df47b..469d0e50 100755 --- a/README.md +++ b/README.md @@ -19,9 +19,6 @@ build   - - codecov   downloads   @@ -72,72 +69,33 @@ Head over to the **[documentation on ReadTheDocs](https://pyportfolioopt.readthe - [Contributing](#contributing) - [Getting in touch](#getting-in-touch) -## Getting started +## 🚀 Installation -If you would like to play with PyPortfolioOpt interactively in your browser, you may launch Binder [here](https://mybinder.org/v2/gh/pyportfolio/pyportfolioopt/main). It takes a -while to set up, but it lets you try out the cookbook recipes without having to deal with all of the requirements. - -_Note: macOS users will need to install [Command Line Tools](https://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)._ - -_Note: if you are on windows, you first need to installl C++. ([download](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16), [install instructions](https://drive.google.com/file/d/0B4GsMXCRaSSIOWpYQkstajlYZ0tPVkNQSElmTWh1dXFaYkJr/view))_ - -This project is available on PyPI, meaning that you can just: +### Using pip ```bash -pip install PyPortfolioOpt +pip install pyportfolioopt ``` -(you may need to follow separate installation instructions for [cvxopt](https://cvxopt.org/install/index.html#) and [cvxpy](https://www.cvxpy.org/install/)). - -However, it is best practice to use a dependency manager within a virtual environment. -My current recommendation is to get yourself set up with [poetry](https://github.com/sdispater/poetry) then just run - -```bash -poetry add PyPortfolioOpt -``` +### From source -Otherwise, clone/download the project and in the project directory run: +Clone the repository and install using the provided Makefile: ```bash -python setup.py install +git clone https://github.com/PyPortfolio/PyPortfolioOpt.git +cd PyPortfolioOpt +make install ``` -PyPortfolioOpt supports Docker. Build your first container with `docker build -f docker/Dockerfile . -t pypfopt`. You can use the image to run tests or even launch a Jupyter server. - -```bash -# iPython interpreter: -docker run -it pypfopt poetry run ipython - -# Jupyter notebook server: -docker run -it -p 8888:8888 pypfopt poetry run jupyter notebook --allow-root --no-browser --ip 0.0.0.0 -# click on http://127.0.0.1:8888/?token=xxx - -# Pytest -docker run -t pypfopt poetry run pytest - -# Bash -docker run -it pypfopt bash -``` - -For more information, please read [this guide](https://docker-curriculum.com/#introduction). - -### For development - -If you would like to make major changes to integrate this with your proprietary system, it probably makes sense to clone this repository and to just use the source code. - -```bash -git clone https://github.com/pyportfolio/pyportfolioopt -``` - -Alternatively, you could try: - -```bash -pip install -e git+https://github.com/pyportfolio/pyportfolioopt.git -``` +This will install [uv](https://github.com/astral-sh/uv) +(a fast Python package installer) and create a +virtual environment with all dependencies. ## A quick example -Here is an example on real life stock data, demonstrating how easy it is to find the long-only portfolio that maximises the Sharpe ratio (a measure of risk-adjusted returns). +Here is an example on real life stock data, +demonstrating how easy it is to find the long-only portfolio +that maximises the Sharpe ratio (a measure of risk-adjusted returns). ```python import pandas as pd @@ -190,7 +148,10 @@ Annual volatility: 22.2% Sharpe Ratio: 1.28 ``` -This is interesting but not useful in itself. However, PyPortfolioOpt provides a method which allows you to convert the above continuous weights to an actual allocation that you could buy. Just enter the most recent prices, and the desired portfolio size ($10,000 in this example): +This is interesting but not useful in itself. +However, PyPortfolioOpt provides a method which allows you to +convert the above continuous weights to an actual allocation +that you could buy. Just enter the most recent prices, and the desired portfolio size ($10,000 in this example): ```python from pypfopt.discrete_allocation import DiscreteAllocation, get_latest_prices @@ -211,18 +172,26 @@ Discrete allocation: {'GOOG': 1, 'AAPL': 4, 'FB': 12, 'BABA': 4, 'BBY': 2, Funds remaining: $11.89 ``` -_Disclaimer: nothing about this project constitues investment advice, and the author bears no responsibiltiy for your subsequent investment decisions. Please refer to the [license](https://github.com/PyPortfolio/PyPortfolioOpt/blob/main/LICENSE.txt) for more information._ +_Disclaimer: nothing about this project constitues investment advice, +and the author bears no responsibiltiy for your subsequent investment decisions. +Please refer to the [license](https://github.com/PyPortfolio/PyPortfolioOpt/blob/main/LICENSE.txt) for more information._ ## An overview of classical portfolio optimization methods -Harry Markowitz's 1952 paper is the undeniable classic, which turned portfolio optimization from an art into a science. The key insight is that by combining assets with different expected returns and volatilities, one can decide on a mathematically optimal allocation which minimises the risk for a target return – the set of all such optimal portfolios is referred to as the **efficient frontier**. +Harry Markowitz's 1952 paper is the undeniable classic, +which turned portfolio optimization from an art into a science. +The key insight is that by combining assets with different expected returns and volatilities, +one can decide on a mathematically optimal allocation which minimises +the risk for a target return – the set of all such optimal portfolios is referred to as the **efficient frontier**.
-Although much development has been made in the subject, more than half a century later, Markowitz's core ideas are still fundamentally important and see daily use in many portfolio management firms. -The main drawback of mean-variance optimization is that the theoretical treatment requires knowledge of the expected returns and the future risk-characteristics (covariance) of the assets. Obviously, if we knew the expected returns of a stock life would be much easier, but the whole game is that stock returns are notoriously hard to forecast. As a substitute, we can derive estimates of the expected return and covariance based on historical data – though we do lose the theoretical guarantees provided by Markowitz, the closer our estimates are to the real values, the better our portfolio will be. +Although much development has been made in the subject, more than half a century later, +Markowitz's core ideas are still fundamentally important and see daily use in many portfolio management firms. +The main drawback of mean-variance optimization is that the theoretical +treatment requires knowledge of the expected returns and the future risk-characteristics (covariance) of the assets. Obviously, if we knew the expected returns of a stock life would be much easier, but the whole game is that stock returns are notoriously hard to forecast. As a substitute, we can derive estimates of the expected return and covariance based on historical data – though we do lose the theoretical guarantees provided by Markowitz, the closer our estimates are to the real values, the better our portfolio will be. Thus this project provides four major sets of functionality (though of course they are intimately related) From c1d0306e6705977d5a40e8fd574278f20f658db8 Mon Sep 17 00:00:00 2001 From: Thomas Schmelzer Date: Mon, 10 Nov 2025 17:31:26 +0400 Subject: [PATCH 2/4] revisit the README file --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 469d0e50..61fa73bf 100755 --- a/README.md +++ b/README.md @@ -22,9 +22,6 @@ downloads   - - binder  

From c44d6d61f2bb4a5f6067ebd4eb267d7da061c933 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz=20Kir=C3=A1ly?= Date: Fri, 14 Nov 2025 00:16:55 +0100 Subject: [PATCH 3/4] Update README.md --- README.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 61fa73bf..e0bdbfb7 100755 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ alt="downloads">  

+[binder notebooks](https://mybinder.org/v2/gh/pyportfolio/pyportfolioopt/main) + PyPortfolioOpt is a library that implements portfolio optimization methods, including @@ -76,19 +78,15 @@ pip install pyportfolioopt ### From source -Clone the repository and install using the provided Makefile: +Clone the repository, navigate to the folder, and install using pip: ```bash git clone https://github.com/PyPortfolio/PyPortfolioOpt.git cd PyPortfolioOpt -make install +pip install . ``` -This will install [uv](https://github.com/astral-sh/uv) -(a fast Python package installer) and create a -virtual environment with all dependencies. - -## A quick example +## Getting started Here is an example on real life stock data, demonstrating how easy it is to find the long-only portfolio From aa091c6f1d705cb794cab59977f993784433da77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz=20Kir=C3=A1ly?= Date: Fri, 14 Nov 2025 00:17:27 +0100 Subject: [PATCH 4/4] restore binder link --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e0bdbfb7..42fe7776 100755 --- a/README.md +++ b/README.md @@ -22,10 +22,11 @@ downloads   + + binder  

-[binder notebooks](https://mybinder.org/v2/gh/pyportfolio/pyportfolioopt/main) - PyPortfolioOpt is a library that implements portfolio optimization methods, including