Repository navigation
Size futures margin call reductions past a 100% target without reversing the position - #10201
Conversation
…imit A single-security position group whose security also has holdings in other groups, such as futures sharing contracts with a future option covered call, was sized by the security's buying power model, which applies the margin delta to all of the security's holdings. With little equity left the resulting target went past 1, which FutureMarginModel rejects, so the margin call threw instead of liquidating. Such groups are now sized like groups that aren't held: the fewest of their own lots whose margin covers the deficit. Adds futures margin call tests: long and short, alongside a stock, and sharing contracts with a future option strategy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Approving. The fix is correct and its evidence holds up. I set risk:high because it changes margin call sizing beyond futures, which a maintainer should confirm (below).
Reproduction and fix, checked locally
- I ran the new tests with the PR's test file against master's
DefaultMarginCallModel. BothGeneratesMarginCallOrdersForFuturesSharedWithAFutureOptionStrategycases throw the issue's exception (target provided is: 1.2024…/-1.2024…). The futures-alone and futures-with-AAPL cases pass on master, as the description says. All 35MarginCallModelTestscases pass with the change. - The new test's deficit is larger than the 9-contract group, so it only covers full liquidation. I also ran a partial case locally (same setup, more equity). A $20010 deficit generates
-4(+4short) and a $30010 deficit generates-6: the fewest contracts whose $6000 margin covers the deficit. Execution then scales them correctly after the combo order. The binary search path sizes shared futures correctly, becauseSecurityPositionGroupBuyingPowerModel.GetMaintenanceMarginuses the group's own position quantity, not the security's holdings (Common/Securities/Positions/SecurityPositionGroupBuyingPowerModel.cs:36-44). - The cause is right:
SecurityPositionGroupBuyingPowerModel.GetMaximumLotsForDeltaBuyingPowerpasses the group's delta toBuyingPowerModel.GetMaximumOrderQuantityForDeltaBuyingPower, which adds it to the margin of all the security's holdings (Common/Securities/BuyingPowerModel.cs:336-346). Sending shared single-security groups down the existing not-held path reuses code that is already there, with no new mechanism. - CI is green on this commit. The description reports an end-to-end run that failed before the change and liquidated fully with it.
For a maintainer to decide (the author asks this too)
The change also affects equities that share holdings with an option strategy group, such as a covered call plus extra shares. Their margin call orders are now sized exactly from the group's maintenance margin, not by SecurityMarginModel from all holdings and then capped. In the two existing tests that is one share fewer (-83 → -82, -51 → -50), and both still cover the deficit. Unshared stocks and futures keep the security model's more conservative sizing, so a shared group and an unshared group of the same security now liquidate slightly differently. That was already true for regrouped groups after open margin call orders. I see no principled way to scope this to futures without checking the security type, and the result is consistent with the existing not-held path. No regression algorithm's statistics changed. Still, this changes live liquidation sizes for equity option users beyond what #5604 asks for, so it's a maintainer's call.
Risk: risk:high. The change alters margin call order sizes, which touch money, for every single-security group whose security is shared with another position group, equities included. That behavior change goes beyond the issue and needs the maintainer decision above.
No other repository is affected: nothing outside Lean overrides DefaultMarginCallModel.GenerateMarginCallOrders.
There was a problem hiding this comment.
Requesting changes. The shared-futures exception is real and this fixes that reproducer, but the broader switch away from security-model sizing introduces an under-liquidation regression. The scope and regression share one cause, detailed inline.
Verified against master and this head
- All 35
MarginCallModelTestscases pass on the PR. Against master's production model, the two new shared-futures cases throw at targets approximately +1.2024 and -1.2024; the other four new futures cases pass. - I added three local regressions that process liquidation fills with nonzero commissions and assert nonnegative remaining margin. All three pass on master and fail on this head:
| Shared holding / initial deficit | Master liquidation / remaining margin | PR liquidation / remaining margin |
|---|---|---|
| SPY / $4100 | -83 shares / +$49 | -82 shares / -$1 |
| Long ES / $12000 | -3 contracts / +$5999 | -2 contracts / -$1 |
| Short ES / $12000 | +3 contracts / +$5999 | +2 contracts / -$1 |
These extend the rejected-combo scenario, so the separate security order must cover the deficit itself. SPY uses its default $1 commission; the futures cases use a $1 order fee and $6000 maintenance margin per contract. With the default 10% margin buffer, the next scan generates no orders despite the negative remaining margin.
- Tested end to end with January 6, 2020 data: enter 10 ES19M20 contracts and short one June 3200 call, then reduce portfolio value to $5000. Master stops with the leveraged-target exception (target approximately 1.3548). This head fills the covered-call liquidation (+1 call / -1 future) and the separate -9 futures, completing flat with zero margin used. This confirms the crash fix, not the partial-liquidation fee boundary above.
- CI is green: seven checks passed, one skipped.
Please narrow the correction to the affected futures path rather than changing existing equity sizing without a maintainer decision, preserve fee-aware liquidation sizing, and add filled-order coverage for the partial shared-futures and stock cases.
Risk: risk:high retained. The change alters liquidation quantities, including already-working non-futures cases, and the reproduced regression can leave an account below its margin requirement. No additional repository update was identified; the public contracts are unchanged.
Routing them to the lot search sized stocks shared with option strategies differently and left out liquidation fees. The futures margin model's guard is relaxed for reducing targets instead, in the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fills the stock order of the rejected covered call combo test with a fee, and adds a partial liquidation of futures shared with a rejected future option strategy, long and short, asserting the margin left after the fill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Changes since the last review:
One behavior change outside margin calls, described in the PR description: a leveraged futures target that reduces an already over-leveraged position, such as |
|
CI on
Report Generator Tests passed on its re-run, and the other check passed on the first run. Locally, the full suite with the CI filter passes on this commit ( |
There was a problem hiding this comment.
Requesting changes on bbdc30465. The previous fee-blind liquidation finding is fixed: DefaultMarginCallModel matches master, the stock expectations are restored, and the added filled-order cases cover the earlier regression. I will resolve that thread.
Remaining finding: keep the correction scoped to liquidation, or obtain a maintainer decision on the wider target-API change. The new guard also changes direct futures and future-option target requests. No maintainer has accepted that extra behavior, and the pre-fee comparison is not sufficient to guarantee that an accepted request only reduces the current position: I reproduced CalculateOrderQuantity returning a quantity that crosses through zero. Details are inline. The default margin-call path protects itself by capping the quantity and supplying the liquidation direction; direct target callers do not have that protection.
Verified
- Release affected tests (
MarginCallModelTests,FutureMarginBuyingPowerModelTests, andFuturesOptionsMarginModelTests): 113 passed, 0 failed. I did not rerun the full suite. - Tested end to end with January 6, 2020 ES futures and a short June 3200 call, entering 10 futures at 10:00 and reducing equity on the next minute. With $5000 equity, master's model stops with the leveraged-target exception (target approximately 1.0781). This head fills the combo and the separate -9 futures, ending flat with +$5829.83 margin remaining after fees.
- With $51000 equity, this head generates the combo plus -3 futures, then scales the separate order to -1 after the combo fills. It ends with 8 futures and +$1429.83 margin remaining after fees.
- A separate end-to-end sizing probe, after setting equity to exactly $2 and the futures fee to $2.50, holds 10 long ES with $69300 initial margin. Target 31185 represents $62370 of margin, below the current margin, so this head accepts it. Both the raw model and
CalculateOrderQuantityreturn -12, implying a final holding of -2, not a same-side reduction. Master's model rejects this target. No reversing order was submitted. - CI on this head: seven checks passed, one skipped.
Please keep the fix confined to the delta/liquidation use case. If the intended solution requires changing general target requests too, a maintainer should choose that wider scope before it proceeds; that path also needs evidence that fee-adjusted results cannot reverse the position.
Risk: risk:high retained. The change reaches user-facing futures/future-option target sizing beyond the reported margin-call failure, and the newly accepted path can return an opposite-side position. No additional repository update was identified; no signatures changed.
Target requests, such as SetHoldings, reject leveraged targets again as on master. FutureMarginModel overrides the delta request instead: a delta that only reduces the holdings, as a margin call's does, is sized past a 100% target, and the result is capped so that fees with a portfolio value near zero never size the order past the holdings or against them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Changes since the last review (7004d1f):
The PR description is updated to match. |
There was a problem hiding this comment.
Approving this head (7004d1f). It resolves what was left open on the last two heads: the fix no longer reaches target requests, and the new path can't reverse a position. I set risk:low and removed risk:high (why below).
What changed since my last review
FutureMarginModel.GetMaximumOrderQuantityForTargetBuyingPower is back to master, so SetHoldings/CalculateOrderQuantity still reject leveraged targets. A new GetMaximumOrderQuantityForDeltaBuyingPower override handles one case itself: a delta whose target margin is past the portfolio value, on the holdings' side, and no larger than their current margin. It sizes that case with the base target sizing (fees included) and caps the result at the holdings, on the reducing side. Every other delta goes to the base implementation.
Verified
- Only cases that threw on master change. The new branch runs only when
TotalPortfolioValue != 0and|targetBuyingPower| > |TotalPortfolioValue|. In exactly those cases master's delta path passes a target past ±1 to the futures guard, which throws. Every delta that works today goes to the base implementation unchanged. - Only the margin call is affected. The delta API's only caller is
DefaultMarginCallModel, throughSecurityPositionGroupBuyingPowerModel.GetMaximumLotsForDeltaBuyingPower. For a future that no other group shares, the target the margin call sends is at most the portfolio value, so it stays on the base path. Only futures shared with an option strategy group reach the new branch. - Tests. Release build:
MarginCallModelTests,FutureMarginBuyingPowerModelTestsandFuturesOptionsMarginModelTests, 117 passed. - The cap is tested. With the cap removed locally,
GetMaximumOrderQuantityForDeltaBuyingPower_ReducesLeveragedHoldingsWithoutReversingThemfails on both sides (12against10held). - Edge cases. I ran a local scratch test, not pushed, through
GetMarginCallOrders: 10 ES long and short, sharing one contract with a short option, and a $2.50 futures fee. With equity of -$3000, $2, $30000 and $53990, it generates the combo plus∓9,∓9,∓6and∓2for the other contracts. Each order reduces the position and none exceeds the group's 9 contracts. No exceptions with negative or near-zero equity. - The description reports end-to-end backtests on this head. Master stops with the issue's exception. With the change, the full liquidation completes flat, and the partial one keeps 8 contracts with positive margin remaining after fees.
- CI: all checks pass on this head (one skipped).
Risk: risk:low. The change is one override in one file and easy to revert. It adds no API members and only touches the margin call path. Every case it changes crashed the algorithm on master, and every path that works today runs as before. The evidence: tests that fail without the fix and without the cap, green CI, and end-to-end runs. My earlier risk:high was for the change to target requests (SetHoldings), which is gone from this head.
The other reviewer's open thread, on scoping to liquidation and on reversal, is addressed by this head. Only they can resolve it.
No other repository needs an update: nothing outside Lean overrides FutureMarginModel, and only Lean's margin call model calls the delta API.
There was a problem hiding this comment.
Approving 7004d1f3e. This resolves my remaining finding: the correction is confined to delta sizing, and its fee-adjusted result cannot reverse the holdings.
Checked since my last review
GetMaximumOrderQuantityForTargetBuyingPowermatches master again. Direct futures and future-option target requests retain the leveraged-target exception.DefaultMarginCallModelalso remains unchanged from master, preserving stock sizing.- The new branch handles only same-side, non-increasing margin targets beyond the absolute portfolio value. Those requests previously reached the futures leveraged-target exception. Other deltas use the existing base path. The new path retains fee-aware sizing, then limits the result to the reducing direction and the quantity held; the margin-call model additionally caps it to the position group's quantity.
- Release affected tests: 117 passed, 0 failed, covering
MarginCallModelTests,FutureMarginBuyingPowerModelTests, andFuturesOptionsMarginModelTests. I did not rerun the full suite. - Tested end to end with January 6, 2020 ES futures and a short June 3200 call. After entering ten futures and reducing equity to $5000, the combo and separate -9 futures filled, finishing flat with +$5829.83 remaining margin after fees. At $51000 equity, the generated separate -3 order was scaled to -1 after the combo filled, leaving eight futures and +$1429.83 remaining margin immediately after liquidation; the backtest completed successfully.
- End-to-end sizing probes with exactly $2 equity and a $2.50 futures fee, long and short: the delta requests returned -10 / +10, never beyond the ten contracts held.
CalculateOrderQuantityrejected the leveraged target on both sides. No reversing order was submitted. - CI: seven checks passed, one skipped on this head.
Risk: risk:low retained. The previous wider target-API behavior is removed. This is a small, reversible correction to requests that otherwise threw, with regression coverage, green CI, and verified end-to-end outcomes. No additional repository update was identified.
I will resolve my earlier scope/reversal thread; no blocking findings remain.
Description
As asked on the issue, this adds futures margin call coverage to
MarginCallModelTests. Futures held alone, long and short, and futures alongside a stock don't reproduce the issue: the target the margin call sends reaches exactly ±1 at most.The issue does reproduce when a future's contracts are split between position groups, such as 10 ES contracts where 1 covers a short future option call (a covered call group) and the other 9 form their own group.
GenerateMarginCallOrderscomputes a delta for the 9-contract group's margin, andSecurityPositionGroupBuyingPowerModelpasses it to the security's buying power model, which adds it to all 10 contracts' margin. With little equity left the target is(margin of the contracts in the other group + margin kept) / TotalPortfolioValue, which can be past 1 (or very negative when the portfolio value is negative).FutureMarginModelthen throwsFutures do not allow specifying a leveraged target...and the algorithm stops instead of liquidating. Stocks in the same situation are sized bySecurityMarginModel, which has no such guard, and the margin call caps the result at the group's own quantity.Fix in
FutureMarginModel, scoped to delta requests, which the margin call uses:GetMaximumOrderQuantityForDeltaBuyingPoweris overridden. A delta whose target margin is beyond the portfolio value, on the same side as the holdings and no larger than their current margin, only reduces the position. Such a delta is sized past a 100% target.SetHoldings,CalculateOrderQuantity) are unchanged and still reject leveraged targets.Shared futures in a margin call are now sized like shared stocks: fee-aware by the security's buying power model, then capped at the group's quantity.
DefaultMarginCallModelis unchanged from master. Future options get the same override, since their margin model derives fromFutureMarginModel.Maintainer decisions
None yet. Earlier versions of this pull request were reworked after review:
SetHoldings, and with fees and a near-zero portfolio value it could size a reversing order.The fix is now confined to delta requests.
Related Issue
Closes #5604
How Has This Been Tested?
New tests (ES: $6000 maintenance / $6600 initial margin per contract):
GeneratesMarginCallOrdersForFutures, long and short: 10 contracts against a $30000 portfolio, 6 liquidated. This passes on master too.GeneratesMarginCallOrdersForFuturesAlongsideAnotherSecurity, long and short, plus 100 AAPL shares (the loser). Generated: futures∓5and AAPL-100; executed: AAPL-100, then futures scaled to∓4. This passes on master too.GeneratesMarginCallOrdersForFuturesSharedWithAFutureOptionStrategy: 10 long ES with a short call, and 10 short ES with a short put, with $4990 of equity. On master both throw (target provided is: 1.2024.../-1.2024...). Now they generate the strategy combo (option+1/ future∓1) and∓9for the other contracts.LiquidatesFuturesSharedWithARejectedFutureOptionStrategyForTheDeficitAndFees, long call and short put: a $12000 deficit with combo orders rejected, so the futures order covers it alone. It generates∓3. After the fill with a $1 fee, margin remaining is not negative.LiquidatesAStockGroupSharingTheUnderlyingOfARejectedComboOrdernow also fills its-83stock order with a $1 fee and asserts margin remaining is not negative. Its expectation is unchanged from master.GetMaximumOrderQuantityForDeltaBuyingPower_AllowsReducingLeveragedTarget.GetMaximumOrderQuantityForTargetBuyingPower_ThrowsForLeveragedTargetReducingTheHoldings, long and short: a target request of ±1.1, below the current margin, still throws, as on master. The existingThrowsForInvalidTargetcases still throw.GetMaximumOrderQuantityForDeltaBuyingPower_ReducesLeveragedHoldingsWithoutReversingThem, long and short: 10 contracts, a $2 portfolio value and a $2.50 fee. A reducing delta gives a reducing order of at most 10 contracts. Without the cap it sells 12, which would reverse the position.Full test suite, Release build, with the CI filter:
Passed: 39833, Skipped: 100, Failed: 0.Tested end to end with backtests on 2020-01-06 holding 10 ES19M20 contracts long and 1 ES 3200 call short, with equity then reduced:
Futures do not allow specifying a leveraged target.... With the change, the margin call sends the combo (call+1/ ES-1) and ES-9, all fill, and the backtest completes with no holdings and $4979.83 of margin remaining.-3. After the combo fills, the futures order is scaled to-1, and margin remaining is +$579.83 after fees. The backtest completes holding 8 contracts.