AppMarkowitz

Historical mean-variance portfolio analysis and constrained optimization implemented in Python.

Original period: 2 June 2023 – 13 July 2023
2026 status: completed historical project with a reproducible remediation path
Project Atlas: ready after the validation workflow passes

This project is for educational and portfolio purposes and does not constitute financial advice. Historical or synthetic results do not predict future performance.

Author and project lineage

Hubert Ronald — original author and maintainer of AppMarkowitz.

The project has a documented historical antecedent:

• ModeloMarkowitz — a 2020 educational/community implementation.
• The earlier repository was created in response to the Stack Overflow en español question:
  “Maximizar una variable con la restricción de una volatilidad fija”.
• AppMarkowitz (2023) is the package-oriented successor that expanded that earlier work with market-data ingestion, tests, a notebook and container scaffolding.
• The 2026 remediation corrects mathematical and reproducibility defects while preserving the Git history and clearly separating current fixes from the original implementation.

What this repository demonstrates

prices or reproducible fixture
→ logarithmic returns
→ annualized expected returns and covariance
→ constrained optimization
→ portfolio construction
→ efficient-frontier analysis
→ local CLI artifacts

The repository demonstrates applied mathematics, numerical optimization and reproducible Python engineering. It is not a trading system, an investment recommendation, or a production portfolio-management service.

Mathematical snapshot

Let (P_{t,i}) be the price of asset (i) at time (t). The project models daily logarithmic returns as:

$$ r_{t,i} = \ln\left(\frac{P_{t,i}}{P_{t-1,i}}\right) $$

For daily log returns, the 2026 reproducibility path annualizes the sample mean and covariance by scaling:

$$ \mu = 252,\mathbb{E}[r_t] $$

$$ \Sigma = 252,\mathrm{Cov}(r_t) $$

For a portfolio weight vector (w):

$$ \mu_p = w^\top \mu $$

$$ \sigma_p^2 = w^\top \Sigma w $$

$$ \sigma_p = \sqrt{w^\top \Sigma w} $$

With an annual risk-free rate (r_f), the Sharpe ratio is:

$$ S_p = \frac{w^\top\mu-r_f}{\sqrt{w^\top\Sigma w}} $$

The default long-only, fully invested constraints are:

$$ \mathbf{1}^\top w = 1, \qquad 0 \leq w_i \leq 1 $$

For derivations, assumptions, the historical CVXOPT formulation, the 2026 SLSQP formulation, and the literature retained from the original README, see Mathematical Foundations.

2026 efficient-frontier method

The current reproducibility path constructs frontier points with SciPy SLSQP by minimizing portfolio variance for explicit target returns:

$$ \begin{aligned} \min_w \quad & w^\top \Sigma w \\ \text{s.t.}\quad & \mathbf{1}^\top w = 1 \\ & w^\top\mu = \mu^* \\ & 0 \leq w_i \leq 1 \end{aligned} $$

This method differs from the historical 2023 CVXOPT risk-aversion sweep and is intentionally documented as a remediation rather than retroactive history.

Random Monte Carlo sampling remains separate from mathematical optimization.

Data policy and provenance

The historical project used:

• Alpaca Markets for daily close-price data.
• DataHub for an S&P 500 company list.

The current reproducible path uses AppMarkowitz/data/synthetic_prices.csv, a deterministic synthetic fixture generated with seed 4042023. It is not market data and carries no investment meaning.

The historical Alpaca CSV is removed from the current tree because provider terms must be respected before redistributing API-derived market-data snapshots. The historical file remains visible in preserved Git history; the project does not rewrite historical commits.

A controlled external-data step downloads S&P 500 constituent metadata from DataHub and records the source URL, retrieval timestamp, license metadata and SHA-256 digest.

Alpaca access remains optional and credential-gated through requirements-alpaca.txt and .env.example. Secrets are never printed.

Validation tiers

After bash scripts/validate_all.sh succeeds:

Tier	Status	Evidence
A — imports and configuration	Completed	clean dependency install + compileall
B — tests and functions	Completed	pytest
C — included data	Completed	deterministic synthetic fixture
D — controlled external download	Completed	DataHub download + SHA-256 provenance metadata
E — optimization and frontier	Completed	min-volatility, max-Sharpe and target-return frontier
F — local application	Completed	CLI generates JSON and CSV artifacts

Quick start

git clone https://github.com/HubertRonald/AppMarkowitz.git
cd AppMarkowitz
bash scripts/validate_all.sh

Or run the local CLI after dependencies are installed:

python scripts/generate_synthetic_data.py
python -m AppMarkowitz.main \
  --data AppMarkowitz/data/synthetic_prices.csv \
  --output-dir artifacts/run

Outputs:

artifacts/run/summary.json
artifacts/run/efficient_frontier.csv

Docker

docker compose build
docker compose run --rm appmarkowitz

This is a local analytical CLI, not a web deployment.

Optional Alpaca integration

python -m pip install -r requirements-alpaca.txt
cp .env.example .env
# Fill local credentials; never commit .env.

Use API-derived market data only under the provider's current terms. Do not redistribute downloaded snapshots without explicit rights.

Evaluation scope and limitations

The project remains an in-sample analytical demonstration. It does not include:

• rolling or walk-forward backtesting;
• transaction costs or slippage;
• turnover or taxes;
• liquidity modeling;
• benchmark evaluation;
• production execution.

The synthetic fixture validates the mathematics and software path; it does not establish financial performance.

Documentation and literature

• Mathematical Foundations — notation, equations, optimization problems, assumptions, historical method, current method and references.
• ModeloMarkowitz — historical antecedent.
• Original Stack Overflow en español question.

License

Repository code is licensed under the MIT License. Third-party data and APIs retain their own terms and licenses.