Home /Modules/advantage/README.md

README.md

lib/advantage/learner-vs-professional/courseware/long-term-potencies/README.md · 103 line(s) · markdown

Long-Term-Potencies

An adult courseware topic defining, precisely, what "potency" means for a long-term position: how much of what is held has actually crossed the long-term line, and how concentrated the book's age is around its oldest lot. Both are read directly from SLLongBook's own age and term queries — nothing here invents a new fact about the book, only two named, exact ratios over facts the book already exposes.

Illustrative only. No real market, price or order is used, and this is not investment or tax advice. See ../ORGANIZED.md for the glossary of terms defined versus not defined elsewhere in this courseware (most importantly, "Flat 2" is unrelated to anything here and is still not defined).

Why "potency" needed a definition before any code

"Potency" is not a term used anywhere else in this library. Rather than use it loosely, SLTermPotency defines it as exactly two basis-point ratios:

nameformulareads
term potency(units held that are long term) / (units held), in bpSLLongBook.qtyLongTerm / totalQty
age potencyweightedAgeFloor / oldestAge, in bpSLLongBook.weightedAgeFloor / oldestAge

10,000 bp = 100%. Term potency answers "of what I still hold, what share has crossed the long-term line?" Age potency answers "how close is the average age of what I hold to the age of my single oldest lot?" — a book with many small, much-younger lots alongside one old one has a low age potency even though its term potency might already be partial.

The short-side gap, now closed

SLLongBook had isLongTerm/qtyLongTerm from the start; SLShortBook did not — it only had the three age queries (oldestAge, weightedAgeFloor, qtyOlderThan) that both books share, so termPotencyBp could not be computed for a short position. SLShortBook.isLongTerm/qtyLongTerm were added (mirroring SLLongBook's wording and behavior exactly), and SLTermPotency's three methods are each overloaded — one SLLongBook form, one SLShortBook form, resolved by the SLeeLa 3.0 compiler from the argument type — so every formula in this folder now works on either side of a book.

The six entries

Entries 1–4 use SLLongBook; entries 5–6 are the short-side mirror, now that SLShortBook has isLongTerm/qtyLongTerm (added for this purpose) and SLTermPotency's three methods are each overloaded for both book types (SLeeLa 3.0 overload resolution).

#folderwhat it shows
101-ages-as-the-book-agesone lot checked at exactly its 365-day age (not yet long term — the rule is strictly more than), then a second lot added and the book checked again as both potencies rise
202-fifo-sell-and-potencyselling exactly the oldest lot removes its whole contribution to both potencies in one exact before/after comparison
303-honest-empty-and-invalidan empty book and a day before the book's own last action day are each answered honestly (-2 or -1), never guessed
404-cross-checked-portfoliosten randomly generated portfolios checked against an independent Python model of both formulas
505-short-side-mirrorthe short-side overloads, exercised with entry 1's exact lot structure, confirming identical readings on either book shape
606-short-side-honesty-and-coverthe short-side counterpart of entries 2 and 3: honest answers on an empty/invalid input, then a FIFO cover removing a lot's whole contribution

A worked example, by hand

One lot of 40 units bought on day 0. Checked on day 365: age is exactly 365, and isLongTerm requires strictly more than the threshold, so this lot is not yet long term. Term potency is 0 bp; age potency is 10,000 bp (one lot, so the weighted average age trivially equals the oldest lot's age). A second lot of 60 units is bought on day 400. Checked on day 500: the day-0 lot (40 units) is now 500 days old, past the 365-day line, while the day-400 lot (60 units) is only 100 days old. Term potency is 40/100 = 4,000 bp (40%); age potency is weightedAgeFloor(500)/oldestAge(500) = 260/500 = 5,200 bp.

Assurance

Every entry prints ok/FAIL per check and ends checks passed=N failed=0. Expected values for all six entries were computed by an independent Python model of both formulas and compared with what SLeeLa printed; entry 4 does this across ten randomly generated portfolios rather than hand-picked ones. Entry 5 additionally checks that the short-side readings exactly match the long-side readings in entry 1 at the same lot sizes and ages, so the two overloads of each method are proven consistent with each other, not just each independently correct. test-suites/test-long-term-potencies.sh runs all six and compares each with its .expected.txt.

bash test-suites/test-long-term-potencies.sh

Set UPDATE=1 to rewrite the expected files after reviewing a deliberate change.

Honest limits