SLShortMargin.sleela
lib/advantage/trading-actions-on-verb/SLShortMargin.sleela · 188 line(s) · sleela
<< lib/advantage/trading-actions-on-verb/SLShortMargin.sleela
SLeeLa Standard Library Definition.
Definition: Illustrative margin arithmetic for a short position in exact integers: the ceiling requirement, equity and excess, the deposit needed to meet a call, the fewest shares to cover to restore margin (binary search), and the day a borrow cost first causes a call. >>
#sleela 3.0
material;
artifact;
pure;
gasoline;
< Margin for a short position, as an illustration of careful integer code. >
< Not a statement of any broker or regulator rule: the required percentage is >
< a parameter in basis points (10000 = 100 percent of the short value). >
< Model: collateral is the cash held (sale proceeds plus any deposit). The short >
< value is shares * price. Equity = collateral - short value. Required = the >
< ceiling of short value * bp / 10000. Excess = equity - required, and a call >
< is due when excess < 0. Covering k shares at the current price leaves equity >
< unchanged (fees ignored) and lowers the required amount, so "enough" is >
< monotone in k and a binary search finds the fewest shares. >
< Exactness: SLeeLa comparisons are exact only up to 2^53 - 1. Short value is >
< at most maxValue = 4e15; the requirement is computed as q*bp + ceil(r*bp / >
< 10000) with q = value / 10000 and r = value mod 10000, so no product passes >
< 6e15 (maxBp = 15000) and the ceiling is exact. >
class SLShortMargin {
< ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
<< Eleven catalogued attributes with getter/setter pairs. A worker-class
lesson carries the baseline identity record. >>
String metaVersion = "1.0.0";
int metaId = 39204;
String metaAuthor = "Kiro Agent";
String metaDate = "2026-11-11";
String metaCopyright = "SLeeLa project";
String metaTrademark = "none";
String metaCorporation = "none";
< metaOrigin: National | <nation> | International | Galactic >
String metaOrigin = "International";
String metaBirthDate = "2026-11-11";
< metaScienceRating: maturity/robustness on a 1..10 scale >
int metaScienceRating = 5;
< metaNationalSchedule: a real, citable instrument or "none" >
String metaNationalSchedule = "none";
String getMetaVersion() { return metaVersion; }
void setMetaVersion(String v) { metaVersion = v; }
int getMetaId() { return metaId; }
void setMetaId(int v) { metaId = v; }
String getAuthor() { return metaAuthor; }
void setAuthor(String v) { metaAuthor = v; }
String getDate() { return metaDate; }
void setDate(String v) { metaDate = v; }
String getCopyright() { return metaCopyright; }
void setCopyright(String v) { metaCopyright = v; }
String getTrademark() { return metaTrademark; }
void setTrademark(String v) { metaTrademark = v; }
String getCorporation() { return metaCorporation; }
void setCorporation(String v) { metaCorporation = v; }
String getOrigin() { return metaOrigin; }
void setOrigin(String v) { metaOrigin = v; }
String getBirthDate() { return metaBirthDate; }
void setBirthDate(String v) { metaBirthDate = v; }
int getScienceRating() { return metaScienceRating; }
void setScienceRating(int v) { metaScienceRating = v; }
String getNationalSchedule() { return metaNationalSchedule; }
void setNationalSchedule(String v) { metaNationalSchedule = v; }
int maxValue = 4000000000000000;
int maxBp = 15000;
int maxShares = 100000000;
int maxPrice = 10000000;
int maxRate = 1000;
int maxDays = 10000000;
< Short value in cents, or -1 when shares or price are outside their bounds. >
int shortValue(int shares, int price) {
if (shares < 0 || shares > maxShares) { return 0 - 1; }
if (price < 1 || price > maxPrice) { return 0 - 1; }
return shares * price;
}
< Required margin: ceiling of value * bp / 10000, or -1 for an input out of >
< range. The ceiling never rounds in the holder favour. >
int required(int value, int bp) {
if (value < 0 || value > maxValue) { return 0 - 1; }
if (bp < 0 || bp > maxBp) { return 0 - 1; }
int q = value / 10000;
int r = value % 10000;
return q * bp + (r * bp + 9999) / 10000;
}
< Equity = collateral - short value. May be negative. An input out of range >
< answers -2*maxValue, which no valid equity can reach. >
int equity(int collateral, int shares, int price) {
int v = shortValue(shares, price);
if (v < 0 || collateral < 0 || collateral > maxValue) { return 0 - maxValue - maxValue; }
return collateral - v;
}
boolean inRange(int collateral, int shares, int price, int bp) {
if (shortValue(shares, price) < 0) { return false; }
if (collateral < 0 || collateral > maxValue) { return false; }
if (bp < 0 || bp > maxBp) { return false; }
return true;
}
< Excess = equity - required. Answers -2*maxValue when an input is out of range. >
int excess(int collateral, int shares, int price, int bp) {
if (!inRange(collateral, shares, price, bp)) { return 0 - maxValue - maxValue; }
return equity(collateral, shares, price) - required(shortValue(shares, price), bp);
}
boolean callDue(int collateral, int shares, int price, int bp) {
return excess(collateral, shares, price, bp) < 0 && inRange(collateral, shares, price, bp);
}
< Deposit that restores excess to zero, or 0 when no call is due. >
int callAmount(int collateral, int shares, int price, int bp) {
if (!inRange(collateral, shares, price, bp)) { return 0 - 1; }
int x = excess(collateral, shares, price, bp);
if (x >= 0) { return 0; }
return 0 - x;
}
< True when covering k shares leaves enough equity for the shares still short. >
boolean enoughAfterCover(int collateral, int shares, int price, int bp, int k) {
int eq = equity(collateral, shares, price);
int req = required(shortValue(shares - k, price), bp);
return eq >= req;
}
< Fewest shares to cover so the rest are adequately margined. Returns 0 when >
< no cover is needed, -1 when no cover can help (equity is negative) or the >
< input is out of range. >
< Binary search. Invariant: the answer is in [lo, hi]. enoughAfterCover is >
< monotone in k, because required falls as k grows while equity is fixed. >
< hi - lo strictly shrinks, so the loop ends after about log2(shares) passes. >
int sharesToCover(int collateral, int shares, int price, int bp) {
if (!inRange(collateral, shares, price, bp)) { return 0 - 1; }
if (equity(collateral, shares, price) < 0) { return 0 - 1; }
int lo = 0;
int hi = shares;
while (lo < hi) {
int mid = (lo + hi) / 2;
if (enoughAfterCover(collateral, shares, price, bp, mid)) { hi = mid; }
else { lo = mid + 1; }
}
return lo;
}
< Reference: try k = 0, 1, 2, ... up to shares. Used to cross-check. >
int sharesToCoverScan(int collateral, int shares, int price, int bp) {
if (!inRange(collateral, shares, price, bp)) { return 0 - 1; }
if (equity(collateral, shares, price) < 0) { return 0 - 1; }
int k = 0;
while (k < shares && !enoughAfterCover(collateral, shares, price, bp, k)) { k = k + 1; }
return k;
}
< Borrow cost drains collateral by shares * rate each day at a fixed price. >
< The first day d >= 0 on which the excess is negative: 0 when already due, >
< floor(excess / burn) + 1 otherwise. Returns -2 when nothing drains (burn >
< is 0), -3 when the day is beyond maxDays, and -1 for an input out of range. >
int daysToCall(int collateral, int shares, int price, int bp, int rate) {
if (!inRange(collateral, shares, price, bp)) { return 0 - 1; }
if (rate < 0 || rate > maxRate) { return 0 - 1; }
int x = excess(collateral, shares, price, bp);
if (x < 0) { return 0; }
int burn = shares * rate;
if (burn == 0) { return 0 - 2; }
int d = x / burn + 1;
if (d > maxDays) { return 0 - 3; }
return d;
}
< Reference: step one day at a time until the excess is negative. >
int daysToCallScan(int collateral, int shares, int price, int bp, int rate) {
if (!inRange(collateral, shares, price, bp)) { return 0 - 1; }
if (rate < 0 || rate > maxRate) { return 0 - 1; }
int burn = shares * rate;
int x = excess(collateral, shares, price, bp);
if (x >= 0 && burn == 0) { return 0 - 2; }
int d = 0;
while (x >= 0 && d <= maxDays) {
d = d + 1;
x = x - burn;
}
if (d > maxDays) { return 0 - 3; }
return d;
}
}