Skip to content
35 changes: 35 additions & 0 deletions Common/Securities/Future/FutureMarginModel.cs
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,41 @@ public override GetMaximumOrderQuantityResult GetMaximumOrderQuantityForTargetBu
return base.GetMaximumOrderQuantityForTargetBuyingPower(parameters);
}

/// <summary>
/// Get the maximum market order quantity to obtain a delta in the buying power used by a security.
/// The deltas sign defines the position side to apply it to, positive long, negative short.
/// </summary>
/// <param name="parameters">An object containing the portfolio, the security and the delta buying power</param>
/// <returns>Returns the maximum allowed market order quantity and if zero, also the reason</returns>
/// <remarks>Used by the margin call model to reduce the position by a delta percent.</remarks>
public override GetMaximumOrderQuantityResult GetMaximumOrderQuantityForDeltaBuyingPower(
GetMaximumOrderQuantityForDeltaBuyingPowerParameters parameters)
{
var holdingsQuantity = parameters.Security.Holdings.Quantity;
var usedBuyingPower = GetReservedBuyingPowerForPosition(new ReservedBuyingPowerForPositionParameters(parameters.Security))
.AbsoluteUsedBuyingPower;
var targetBuyingPower = Math.Sign(holdingsQuantity) * usedBuyingPower + parameters.DeltaBuyingPower;
var totalPortfolioValue = parameters.Portfolio.TotalPortfolioValue;

// a delta that only reduces the holdings, such as a margin call's, targets more margin than the portfolio value when the
// holdings already use more than it, which isn't a leveraged target
if (totalPortfolioValue == 0 || Math.Abs(targetBuyingPower) <= Math.Abs(totalPortfolioValue)
|| Math.Sign(targetBuyingPower) != Math.Sign(holdingsQuantity) || Math.Abs(targetBuyingPower) > usedBuyingPower)
{
return base.GetMaximumOrderQuantityForDeltaBuyingPower(parameters);
}

var result = base.GetMaximumOrderQuantityForTargetBuyingPower(new GetMaximumOrderQuantityForTargetBuyingPowerParameters(
parameters.Portfolio, parameters.Security, targetBuyingPower / totalPortfolioValue,
parameters.MinimumOrderMarginPortfolioPercentage, parameters.SilenceNonErrorReasons));

// fees can size the order past the holdings, or against the reduction, when the portfolio value is close to zero
var reducedQuantity = Math.Sign(result.Quantity) == -Math.Sign(holdingsQuantity)
? Math.Min(Math.Abs(result.Quantity), Math.Abs(holdingsQuantity))
: 0;
return new GetMaximumOrderQuantityResult(-Math.Sign(holdingsQuantity) * reducedQuantity, result.Reason, result.IsError);
}

/// <summary>
/// Gets the total margin required to execute the specified order in units of the account currency including fees
/// </summary>
Expand Down
86 changes: 86 additions & 0 deletions Tests/Common/Securities/FutureMarginBuyingPowerModelTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
using QuantConnect.Data.Market;
using QuantConnect.Logging;
using QuantConnect.Orders;
using QuantConnect.Orders.Fees;
using QuantConnect.Securities;
using QuantConnect.Securities.Future;
using QuantConnect.Securities.Option;
Expand Down Expand Up @@ -496,6 +497,91 @@ public void GetMaximumOrderQuantityForTargetBuyingPower_ThrowsForInvalidTarget(d
0)));
}

[Test]
public void GetMaximumOrderQuantityForDeltaBuyingPower_AllowsReducingLeveragedTarget()
{
var algorithm = new QCAlgorithm();
algorithm.SetFinishedWarmingUp();
algorithm.SubscriptionManager.SetDataManager(new DataManagerStub(algorithm));

var ticker = QuantConnect.Securities.Futures.Financials.EuroDollar;
var futureSecurity = algorithm.AddFuture(ticker);
Update(futureSecurity, 100, algorithm);

algorithm.Portfolio.SetCash(1000);
futureSecurity.Holdings.SetHoldings(100, 10);
algorithm.Portfolio.InvalidateTotalPortfolioValue();

var usedBuyingPower = futureSecurity.BuyingPowerModel.GetReservedBuyingPowerForPosition(
new ReservedBuyingPowerForPositionParameters(futureSecurity)).AbsoluteUsedBuyingPower;
var totalPortfolioValue = algorithm.Portfolio.TotalPortfolioValue;
var targetBuyingPower = 1.1m * totalPortfolioValue;
var deltaBuyingPower = targetBuyingPower - usedBuyingPower;

Assert.Greater(Math.Abs(usedBuyingPower / totalPortfolioValue), 1m);
Assert.Less(deltaBuyingPower, 0m);

Assert.DoesNotThrow(() =>
{
var result = futureSecurity.BuyingPowerModel.GetMaximumOrderQuantityForDeltaBuyingPower(
new GetMaximumOrderQuantityForDeltaBuyingPowerParameters(
algorithm.Portfolio,
futureSecurity,
deltaBuyingPower,
0
));
Assert.Less(result.Quantity, 0m);
});
}

[TestCase(10)]
[TestCase(-10)]
public void GetMaximumOrderQuantityForTargetBuyingPower_ThrowsForLeveragedTargetReducingTheHoldings(int quantity)
{
var algorithm = new QCAlgorithm();
algorithm.SetFinishedWarmingUp();
algorithm.SubscriptionManager.SetDataManager(new DataManagerStub(algorithm));
var futureSecurity = algorithm.AddFuture(QuantConnect.Securities.Futures.Financials.EuroDollar);
Update(futureSecurity, 100, algorithm);
algorithm.Portfolio.SetCash(1000);
futureSecurity.Holdings.SetHoldings(100, quantity);
algorithm.Portfolio.InvalidateTotalPortfolioValue();

// only margin call deltas reduce the holdings past a leveraged target, target requests keep rejecting it
var target = Math.Sign(quantity) * 1.1m;
Assert.Less(1.1m * algorithm.Portfolio.TotalPortfolioValue, futureSecurity.BuyingPowerModel.GetReservedBuyingPowerForPosition(
new ReservedBuyingPowerForPositionParameters(futureSecurity)).AbsoluteUsedBuyingPower);
Assert.Throws<InvalidOperationException>(() => futureSecurity.BuyingPowerModel.GetMaximumOrderQuantityForTargetBuyingPower(
new GetMaximumOrderQuantityForTargetBuyingPowerParameters(algorithm.Portfolio, futureSecurity, target, 0)));
}

[TestCase(10)]
[TestCase(-10)]
public void GetMaximumOrderQuantityForDeltaBuyingPower_ReducesLeveragedHoldingsWithoutReversingThem(int quantity)
{
var algorithm = new QCAlgorithm();
algorithm.SetFinishedWarmingUp();
algorithm.SubscriptionManager.SetDataManager(new DataManagerStub(algorithm));
var futureSecurity = algorithm.AddFuture(QuantConnect.Securities.Futures.Financials.EuroDollar);
futureSecurity.FeeModel = new ConstantFeeModel(2.5m);
Update(futureSecurity, 100, algorithm);
futureSecurity.Holdings.SetHoldings(100, quantity);

// a $2 portfolio value, less than an order's fee, which sizes a fee adjusted target past the holdings
algorithm.Portfolio.CashBook[Currencies.USD].AddAmount(2 - algorithm.Portfolio.TotalPortfolioValue);
algorithm.Portfolio.InvalidateTotalPortfolioValue();
Assert.AreEqual(2, algorithm.Portfolio.TotalPortfolioValue);

var usedBuyingPower = futureSecurity.BuyingPowerModel.GetReservedBuyingPowerForPosition(
new ReservedBuyingPowerForPositionParameters(futureSecurity)).AbsoluteUsedBuyingPower;
var result = futureSecurity.BuyingPowerModel.GetMaximumOrderQuantityForDeltaBuyingPower(
new GetMaximumOrderQuantityForDeltaBuyingPowerParameters(algorithm.Portfolio, futureSecurity,
-Math.Sign(quantity) * usedBuyingPower * 0.1m, 0));

Assert.AreEqual(-Math.Sign(quantity), Math.Sign(result.Quantity));
Assert.LessOrEqual(Math.Abs(result.Quantity), Math.Abs(quantity));
}

[TestCase(1)]
[TestCase(0.5)]
[TestCase(-1)]
Expand Down
149 changes: 149 additions & 0 deletions Tests/Common/Securities/MarginCallModelTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
using QuantConnect.Orders.Fees;
using QuantConnect.Orders.Fills;
using QuantConnect.Securities;
using QuantConnect.Securities.Future;
using QuantConnect.Securities.Option;
using QuantConnect.Securities.Positions;

Expand Down Expand Up @@ -842,6 +843,12 @@ public void LiquidatesAStockGroupSharingTheUnderlyingOfARejectedComboOrder()
Assert.IsNull(tickets[2].SubmitRequest.GroupOrderManager);
Assert.AreEqual(-83, tickets[2].Quantity);
Assert.IsTrue(tickets[2].Status.IsOpen());

// the fill and its $1 fee leave the account within its margin requirement
var order = Order.CreateOrder(tickets[2].SubmitRequest);
portfolio.ProcessFills(new List<OrderEvent> { new OrderEvent(order, DateTime.UtcNow, new OrderFee(new CashAmount(1, Currencies.USD)))
{ FillPrice = 100m, FillQuantity = order.Quantity, Status = OrderStatus.Filled } });
Assert.GreaterOrEqual(portfolio.MarginRemaining, 0);
}

[Test]
Expand Down Expand Up @@ -948,6 +955,100 @@ public void LiquidatesMultiLotPositionGroupsOnceWithTheirHeldQuantities()
Assert.AreEqual(0, portfolio.MarginCallModel.GetMarginCallOrders(out _).Count);
}

[TestCase(10)]
[TestCase(-10)]
public void GeneratesMarginCallOrdersForFutures(int quantity)
{
var orderProcessor = new FakeOrderProcessor();
// $60000 maintenance margin against a $30000 portfolio: the $30000 the futures keep is a target of the whole
// portfolio value, which holds the 4 contracts whose $6600 initial margin each fits in it
var portfolio = GetFuturesPortfolio(orderProcessor, 30000, quantity);
Assert.AreEqual(60000, portfolio.TotalMarginUsed);
Assert.AreEqual(30000, portfolio.TotalPortfolioValue);

var marginCallOrders = portfolio.MarginCallModel.GetMarginCallOrders(out var issueMarginCallWarning);
Assert.IsTrue(issueMarginCallWarning);
Assert.AreEqual(1, marginCallOrders.Count);
Assert.AreEqual(Symbols.Future_ESZ18_Dec2018, marginCallOrders[0].Symbol);
Assert.AreEqual(-Math.Sign(quantity) * 6, marginCallOrders[0].Quantity);

var orders = ExecuteMarginCall(portfolio, orderProcessor, marginCallOrders);
Assert.AreEqual(-Math.Sign(quantity) * 6, orders.Single().Quantity);
}

[TestCase(10)]
[TestCase(-10)]
public void GeneratesMarginCallOrdersForFuturesAlongsideAnotherSecurity(int quantity)
{
var orderProcessor = new FakeOrderProcessor();
var portfolio = GetFuturesPortfolio(orderProcessor, 30000, quantity);

// 100 AAPL shares at $100 with 2x leverage, bought at $120 so they're the loser and liquidated first
var stock = GetSecurity(Symbols.AAPL, portfolio.CashBook);
portfolio.Securities.Add(stock);
stock.SetLeverage(2);
stock.SetMarketPrice(new Tick(DateTime.Now, Symbols.AAPL, 100m, 100m));
stock.Holdings.SetHoldings(120m, 100);
portfolio.InvalidateTotalPortfolioValue();
Assert.AreEqual(65000, portfolio.TotalMarginUsed);
Assert.AreEqual(40000, portfolio.TotalPortfolioValue);

// the $25000 deficit: the futures keep $35000 of their $60000 margin, 5 contracts at $6600 initial margin each,
// and the stock none of its $5000
var marginCallOrders = portfolio.MarginCallModel.GetMarginCallOrders(out _);
Assert.AreEqual(2, marginCallOrders.Count);
Assert.AreEqual(-Math.Sign(quantity) * 5, marginCallOrders.Single(request => request.Symbol == Symbols.Future_ESZ18_Dec2018).Quantity);
Assert.AreEqual(-100, marginCallOrders.Single(request => request.Symbol == Symbols.AAPL).Quantity);

// the stock order releases $5000, the futures one is scaled down to the 4 contracts whose $6000 maintenance margin each
// covers the $20000 left
var orders = ExecuteMarginCall(portfolio, orderProcessor, marginCallOrders);
Assert.AreEqual(2, orders.Count);
Assert.AreEqual(-100, orders[0].Quantity);
Assert.AreEqual(-Math.Sign(quantity) * 4, orders[1].Quantity);
}

[TestCase(10, OptionRight.Call)]
[TestCase(-10, OptionRight.Put)]
public void GeneratesMarginCallOrdersForFuturesSharedWithAFutureOptionStrategy(int quantity, OptionRight right)
{
var orderProcessor = new FakeOrderProcessor();
var portfolio = GetSharedFuturesPortfolio(orderProcessor, 5000, quantity, right);
Assert.AreEqual(4990, portfolio.TotalPortfolioValue);

// the strategy's margin and the $54000 of the futures group leave a deficit larger than the latter, which is liquidated
// entirely
var marginCallOrders = portfolio.MarginCallModel.GetMarginCallOrders(out _);
Assert.AreEqual(3, marginCallOrders.Count);
Assert.AreEqual(-Math.Sign(quantity) * 9, marginCallOrders.Single(request => request.GroupOrderManager == null).Quantity);
Assert.AreEqual(-Math.Sign(quantity), marginCallOrders.Single(request => request.Symbol == Symbols.Future_ESZ18_Dec2018
&& request.GroupOrderManager != null).Quantity);
Assert.AreEqual(1, marginCallOrders.Single(request => request.Symbol.SecurityType == SecurityType.FutureOption).Quantity);
}

[TestCase(10, OptionRight.Call)]
[TestCase(-10, OptionRight.Put)]
public void LiquidatesFuturesSharedWithARejectedFutureOptionStrategyForTheDeficitAndFees(int quantity, OptionRight right)
{
// the brokerage rejects combo orders, so the futures group's order has to cover the deficit by itself
var orderProcessor = new FakeOrderProcessor { RejectsOrder = requests => requests[0].OrderType == OrderType.ComboMarket };
var portfolio = GetSharedFuturesPortfolio(orderProcessor, 0, quantity, right);
portfolio.CashBook[Currencies.USD].AddAmount(portfolio.TotalMarginUsed - 12000 - portfolio.TotalPortfolioValue);
portfolio.InvalidateTotalPortfolioValue();
Assert.AreEqual(12000, portfolio.TotalMarginUsed - portfolio.TotalPortfolioValue);

var tickets = portfolio.MarginCallModel.ExecuteMarginCall(portfolio.MarginCallModel.GetMarginCallOrders(out _));
Assert.AreEqual(3, tickets.Count);
var futuresTicket = tickets.Single(ticket => ticket.SubmitRequest.GroupOrderManager == null);
Assert.AreEqual(-Math.Sign(quantity) * 3, futuresTicket.Quantity);

// the fill and its $1 fee leave the account within its margin requirement
var order = Order.CreateOrder(futuresTicket.SubmitRequest);
portfolio.ProcessFills(new List<OrderEvent> { new OrderEvent(order, DateTime.UtcNow, new OrderFee(new CashAmount(1, Currencies.USD)))
{ FillPrice = 2900m, FillQuantity = order.Quantity, Status = OrderStatus.Filled } });
Assert.GreaterOrEqual(portfolio.MarginRemaining, 0);
}

public enum OpenOrderKind
{
MarginCall,
Expand Down Expand Up @@ -989,6 +1090,54 @@ private SecurityPortfolioManager GetStocksPortfolio(IOrderProcessor orderProcess
return portfolio;
}

private SecurityPortfolioManager GetFuturesPortfolio(IOrderProcessor orderProcessor, decimal cash, int quantity)
{
var portfolio = GetPortfolio(orderProcessor, 0);
portfolio.MarginCallModel = new DefaultMarginCallModel(portfolio, null);
portfolio.Transactions.MarketOrderFillTimeout = TimeSpan.Zero;

// the ES maintenance margin is $6000 per contract on this date
var time = new DateTime(2018, 10, 1);
var future = new Future(
SecurityExchangeHours.AlwaysOpen(TimeZones.NewYork),
new SubscriptionDataConfig(typeof(TradeBar), Symbols.Future_ESZ18_Dec2018, Resolution.Minute, TimeZones.NewYork,
TimeZones.NewYork, true, false, false),
new Cash(Currencies.USD, 0, 1m),
new OptionSymbolProperties(SymbolProperties.GetDefault(Currencies.USD)),
portfolio.CashBook,
RegisteredSecurityDataTypesProvider.Null);
future.FeeModel = new ConstantFeeModel(0);
portfolio.Securities.Add(future);
future.SetMarketPrice(new Tick(time, future.Symbol, 2900m, 2900m));
future.Holdings.SetHoldings(2900m, quantity);
portfolio.CashBook[Currencies.USD].SetAmount(cash);
portfolio.InvalidateTotalPortfolioValue();

return portfolio;
}

/// <summary>
/// Gets a futures portfolio where one of the futures covers a short future option, so the others are a group of their own
/// </summary>
private SecurityPortfolioManager GetSharedFuturesPortfolio(IOrderProcessor orderProcessor, decimal cash, int quantity,
OptionRight right)
{
var portfolio = GetFuturesPortfolio(orderProcessor, cash, quantity);
var future = portfolio.Securities[Symbols.Future_ESZ18_Dec2018];
var optionSymbol = Symbol.CreateOption(future.Symbol, Market.CME, OptionStyle.American, right, 2900m, new DateTime(2018, 12, 21));
var option = new QuantConnect.Securities.FutureOption.FutureOption(optionSymbol, SecurityExchangeHours.AlwaysOpen(TimeZones.NewYork),
new Cash(Currencies.USD, 0, 1m), new OptionSymbolProperties(SymbolProperties.GetDefault(Currencies.USD)), portfolio.CashBook,
RegisteredSecurityDataTypesProvider.Null, new SecurityCache(), future);
option.FeeModel = new ConstantFeeModel(0);
portfolio.Securities.Add(option);
option.SetMarketPrice(new Tick(new DateTime(2018, 10, 1), optionSymbol, 10m, 10m));
option.Holdings.SetHoldings(10m, -1);
portfolio.InvalidateTotalPortfolioValue();
Assert.AreEqual(2, portfolio.Positions.Groups.Count);

return portfolio;
}

private SecurityPortfolioManager GetSpyPortfolio(IOrderProcessor orderProcessor, decimal cash, int callQuantity)
{
var portfolio = GetPortfolio(orderProcessor, 0);
Expand Down
Loading