docs: add a paper on the HRP and Schur allocators

[tschm]

Adds docs/paper/main.tex (+ references.bib), so the github-paper workflow added
in #792 now has something to compile. 8 pages, builds clean with latexmk -pdf
(0 overfull boxes, no undefined references).

What it documents. The construction the package actually performs: the
correlation-to-distance map, the linkage and bisection trees (including why the
bisection tree's linkage rows carry the cluster diameter), the recursive
inverse-variance split, the Schur augmentation, and the implementation choices that
are not implied by the maths — the iterative post-order traversals that replaced
recursion, and the in-place/idempotent allocator contract.

What it finds. Every number comes from tests/resources/stock_prices.csv and is
reproducible from the appendix listings. Three claims the docs make about the Schur
allocator were tested:

• γ=0 reproduces HRP — holds exactly (max abs weight difference is 0.0, not
  merely below a tolerance).
• γ=1 recovers the minimum-variance portfolio — does not hold. On the 20-asset
  panel, γ=1 has variance 5.449e-5 against GMV's 4.137e-5, and in a two-asset
  case that can be checked by hand (Σ = [[4, 1.5], [1.5, 1]]) GMV is
  (-0.25, 1.25) while the allocator returns (0.2, 0.8). The reason is that the
  split rule stays inverse-variance at every γ, and the output is long-only by
  construction, so it cannot match a GMV portfolio that shorts.
• Variance falls as γ rises — holds on the shipped panel, but fails in 76 of 200
  random 8-asset trials, where variance rose with γ (by 0.33% in the first such
  case).

The practical upshot, stated in the conclusion: γ is a small perturbation of HRP
(it moves the largest weight by 0.002 on this panel), not a dial between HRP and
minimum variance. That reading of γ in the README is worth revising separately —
this PR only adds the paper, it changes no code and no docs.

Also of note: bisection improves both variance and concentration for all four
linkage methods here, and helps single most (variance −17%, effective N from 7.8
to 13.6), which is consistent with balance being what it supplies.

[coderabbitai]

Warning

Review limit reached

@tschm, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 1 minute

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 44581c7b-4a3e-49a1-a0dc-1ddaa756375b

📥 Commits

Reviewing files that changed from the base of the PR and between 58ff427 and 7b31ef3.

📒 Files selected for processing (2)

• docs/paper/main.tex
• docs/paper/references.bib

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.