Add margin-aware option strategy match selection

Algorithm.CSharp/OptionEquityOverlappingBullCallSpreadsRegressionAlgorithm.cs

@@ -0,0 +1,142 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+using System;
+using System.Linq;
+using QuantConnect.Data;
+using QuantConnect.Data.Market;
+using System.Collections.Generic;
+using QuantConnect.Securities.Option;
+using QuantConnect.Securities.Positions;
+using QuantConnect.Securities.Option.StrategyMatcher;
+
+namespace QuantConnect.Algorithm.CSharp
+{
+    /// <summary>
+    /// Regression algorithm asserting that a book of two overlapping bull call debit spreads, with interleaved
+    /// strikes and the same expiration, is grouped as two margin-free bull call spreads. The greedy leg-count
+    /// descending matching used to carve this book into a bull call ladder plus an unmatched long, charging
+    /// naked call margin for the ladder's uncovered short leg on a fully covered, defined-risk book
+    /// </summary>
+    public class OptionEquityOverlappingBullCallSpreadsRegressionAlgorithm : OptionEquityBaseStrategyRegressionAlgorithm
+    {
+        /// <summary>
+        /// OnData event is the primary entry point for your algorithm. Each new data point will be pumped in here.
+        /// </summary>
+        /// <param name="slice">Slice object keyed by symbol containing the stock data</param>
+        public override void OnData(Slice slice)
+        {
+            if (!Portfolio.Invested)
+            {
+                OptionChain chain;
+                if (IsMarketOpen(_optionSymbol) && slice.OptionChains.TryGetValue(_optionSymbol, out chain))
+                {
+                    var callContracts = chain
+                        .Where(contract => contract.Right == OptionRight.Call);
+                    var expiry = callContracts.Min(x => x.Expiry);
+                    var contracts = callContracts.Where(x => x.Expiry == expiry)
+                        .DistinctBy(x => x.Strike)
+                        .OrderBy(x => x.Strike)
+                        .ToList();
+                    if (contracts.Count < 4) return;
+
+                    var initialMargin = Portfolio.MarginRemaining;
+
+                    // first debit spread: long the lowest strike, short the third lowest
+                    MarketOrder(contracts[0].Symbol, 1);
+                    MarketOrder(contracts[2].Symbol, -1);
+
+                    AssertOptionStrategyIsPresent(OptionStrategyDefinitions.BullCallSpread.Name, 1);
+
+                    // second debit spread, its strikes interleaved with the first: long the second lowest, short the fourth lowest
+                    MarketOrder(contracts[1].Symbol, 1);
+                    MarketOrder(contracts[3].Symbol, -1);
+                    var freeMarginPostTrade = Portfolio.MarginRemaining;
+
+                    // every short call is covered by a long call at a lower strike: the book must resolve into two
+                    // margin-free bull call spreads, not a bull call ladder charging naked call margin plus an orphan long
+                    var bullCallSpreadsCount = Portfolio.Positions.Groups.Count(group =>
+                        group.BuyingPowerModel is OptionStrategyPositionGroupBuyingPowerModel
+                        && group.BuyingPowerModel.ToString() == OptionStrategyDefinitions.BullCallSpread.Name);
+                    if (bullCallSpreadsCount != 2)
+                    {
+                        throw new RegressionTestException($"Expected two Bull Call Spread groups, found {bullCallSpreadsCount}: " +
+                            string.Join(", ", Portfolio.Positions.Groups.Select(group => group.BuyingPowerModel.ToString())));
+                    }
+
+                    var expectedMarginUsage = 0m;
+                    if (expectedMarginUsage != Portfolio.TotalMarginUsed)
+                    {
+                        throw new RegressionTestException($"Unexpected margin used!: {Portfolio.TotalMarginUsed}");
+                    }
+
+                    // we paid the ask and value using the assets price
+                    var priceSpreadDifference = GetPriceSpreadDifference(contracts[0].Symbol, contracts[1].Symbol,
+                        contracts[2].Symbol, contracts[3].Symbol);
+                    if (initialMargin != (freeMarginPostTrade + expectedMarginUsage + _paidFees - priceSpreadDifference))
+                    {
+                        throw new RegressionTestException("Unexpected margin remaining!");
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Data Points count of all timeslices of algorithm
+        /// </summary>
+        public override long DataPoints => 15023;
+
+        /// <summary>
+        /// Data Points count of the algorithm history
+        /// </summary>
+        public override int AlgorithmHistoryDataPoints => 0;
+
+        /// <summary>
+        /// This is used by the regression test system to indicate what the expected statistics are from running the algorithm
+        /// </summary>
+        public override Dictionary<string, string> ExpectedStatistics => new Dictionary<string, string>
+        {
+            {"Total Orders", "4"},
+            {"Average Win", "0%"},
+            {"Average Loss", "0%"},
+            {"Compounding Annual Return", "0%"},
+            {"Drawdown", "0%"},
+            {"Expectancy", "0"},
+            {"Start Equity", "200000"},
+            {"End Equity", "199756"},
+            {"Net Profit", "0%"},
+            {"Sharpe Ratio", "0"},
+            {"Sortino Ratio", "0"},
+            {"Probabilistic Sharpe Ratio", "0%"},
+            {"Loss Rate", "0%"},
+            {"Win Rate", "0%"},
+            {"Profit-Loss Ratio", "0"},
+            {"Alpha", "0"},
+            {"Beta", "0"},
+            {"Annual Standard Deviation", "0"},
+            {"Annual Variance", "0"},
+            {"Information Ratio", "0"},
+            {"Tracking Error", "0"},
+            {"Treynor Ratio", "0"},
+            {"Total Fees", "$4.00"},
+            {"Estimated Strategy Capacity", "$65000.00"},
+            {"Lowest Capacity Asset", "GOOCV W78ZERHAT67A|GOOCV VP83T1ZUHROL"},
+            {"Portfolio Turnover", "2.85%"},
+            {"Drawdown Recovery", "0"},
+            {"OrderListHash", "4f2d6ca65efe107133bf6baff5fe5512"}
+        };
+    }
+}

Common/Securities/Option/StrategyMatcher/IOptionStrategyMatchObjectiveFunction.cs

@@ -21,9 +21,9 @@ namespace QuantConnect.Securities.Option.StrategyMatcher
     public interface IOptionStrategyMatchObjectiveFunction
     {
         /// <summary>
-        /// Evaluates the objective function for the provided match solution. Solution with the highest score will be selected
-        /// as the solution. NOTE: This part of the match has not been implemented as of 2020-11-06 as it's only evaluating the
-        /// first solution match (MatchOnce).
+        /// Evaluates the objective function for the provided match solution. The solution with the highest score will be
+        /// selected as the solution. By convention, solutions that can't be improved upon score zero, the maximum, which
+        /// allows the matcher to skip evaluating additional candidate solutions.
         /// </summary>
         decimal ComputeScore(OptionPositionCollection input, OptionStrategyMatch match, OptionPositionCollection unmatched);
     }

Common/Securities/Option/StrategyMatcher/OptionStrategyMatcher.cs

@@ -13,6 +13,7 @@
  * limitations under the License.
 */
 
+using System;
 using System.Collections.Generic;
 
 namespace QuantConnect.Securities.Option.StrategyMatcher
@@ -37,24 +38,53 @@ public OptionStrategyMatcher(OptionStrategyMatcherOptions options)
             Options = options;
         }
 
-        // TODO : Implement matching multiple permutations and using the objective function to select the best solution
-
         /// <summary>
         /// Using the definitions provided in <see cref="Options"/>, attempts to match all <paramref name="positions"/>.
         /// The resulting <see cref="OptionStrategyMatch"/> presents a single, valid solution for matching as many positions
-        /// as possible.
+        /// as possible. A fixed set of candidate solutions is evaluated and the one scoring highest against the configured
+        /// <see cref="OptionStrategyMatcherOptions.ObjectiveFunction"/> is selected, so short positions are grouped into
+        /// covered strategies instead of being charged naked option margin whenever the positions allow it.
+        /// On equal scores, the solution produced by the configured definition enumeration order is preserved.
         /// </summary>
         public OptionStrategyMatch MatchOnce(OptionPositionCollection positions)
         {
-            // these definitions are enumerated according to the configured IOptionStrategyDefinitionEnumerator
+            // the first candidate solution greedily matches definitions in the configured enumeration order, by
+            // default descending by leg count so more complex definitions get matching priority. it's evaluated
+            // first so that whenever the objective function scores another candidate equally this one is preserved
+            var bestMatch = Match(Options.Definitions, positions, out var unmatched);
+            var bestScore = Options.ObjectiveFunction.ComputeScore(positions, bestMatch, unmatched);
+            if (bestScore >= 0
+                // the bound below reads the score as a negated quantity of uncovered short contracts, which only the
+                // default objective function itself guarantees. any other one, including a derived function free to
+                // score by different rules, always gets to evaluate both candidates
+                || Options.ObjectiveFunction.GetType() == typeof(UncoveredShortQuantityOptionStrategyMatchObjectiveFunction)
+                    && -bestScore <= GetMinimumUncoveredQuantity(positions))
+            {
+                // by convention solutions that can't be improved upon score zero, see IOptionStrategyMatchObjectiveFunction.
+                // matching again is also pointless once the first solution leaves no more short contracts uncovered than
+                // the positions themselves can possibly cover, which is the case for a book of naked shorts, for a book
+                // holding fewer longs than shorts, and generally whenever the first solution is already optimal
+                return bestMatch;
+            }
+
+            // the second candidate deprioritizes definitions leaving a short leg uncovered within the strategy
+            // (naked calls/puts, ladders, short backspreads/straddles/strangles), so short positions are matched
+            // into covered strategies whenever another grouping of the same positions allows it. this avoids
+            // greedily carving, for instance, two overlapping bull call spreads into a bull call ladder, whose
+            // uncovered short leg is charged naked option margin, plus an unmatched long contract
+            var candidateMatch = Match(Options.CoveredShortsFirstDefinitions, positions, out unmatched);
+            var candidateScore = Options.ObjectiveFunction.ComputeScore(positions, candidateMatch, unmatched);
+
+            return candidateScore > bestScore ? candidateMatch : bestMatch;
+        }
 
+        private OptionStrategyMatch Match(IEnumerable<OptionStrategyDefinition> definitions, OptionPositionCollection positions,
+            out OptionPositionCollection unmatched)
+        {
             var strategies = new List<OptionStrategy>();
-            foreach (var definition in Options.Definitions)
+            foreach (var definition in definitions)
             {
                 // simplest implementation here is to match one at a time, updating positions in between
-                // a better implementation would be to evaluate all possible matches and make decisions
-                // prioritizing positions that would require more margin if not matched
-
                 OptionStrategyDefinitionMatch match;
                 while (definition.TryMatchOnce(Options, positions, out match))
                 {
@@ -68,7 +98,39 @@ public OptionStrategyMatch MatchOnce(OptionPositionCollection positions)
                 }
             }
 
+            unmatched = positions;
             return new OptionStrategyMatch(strategies);
         }
+
+        /// <summary>
+        /// Determines the smallest quantity of short contracts any grouping of these positions can leave uncovered.
+        /// A long contract covers at most its own quantity of shorts of the same right, and so does an underlying lot,
+        /// which bounds how much a different grouping could possibly improve on the solution already found
+        /// </summary>
+        private static decimal GetMinimumUncoveredQuantity(OptionPositionCollection positions)
+        {
+            var calls = 0m;
+            var puts = 0m;
+            foreach (var position in positions)
+            {
+                if (position.IsUnderlying)
+                {
+                    continue;
+                }
+
+                if (position.Right == OptionRight.Call)
+                {
+                    calls += position.Quantity;
+                }
+                else
+                {
+                    puts += position.Quantity;
+                }
+            }
+
+            // long underlying lots cover short calls, short underlying lots cover short puts
+            return Math.Max(0, -calls - Math.Max(0, positions.UnderlyingQuantity))
+                + Math.Max(0, -puts - Math.Max(0, -positions.UnderlyingQuantity));
+        }
     }
 }

Common/Securities/Option/StrategyMatcher/OptionStrategyMatcherOptions.cs

@@ -23,14 +23,15 @@ namespace QuantConnect.Securities.Option.StrategyMatcher
     /// Defines options that influence how the matcher operates.
     /// </summary>
     /// <remarks>
-    /// Many properties in this type are not implemented in the matcher but are provided to document
-    /// the types of things that can be added to the matcher in the future as necessary. Some of the
+    /// Some properties in this type are not implemented in the matcher but are provided to document the
+    /// types of things that can be added to it in the future as necessary. <see cref="MaximumDuration"/>
+    /// and <see cref="MaximumSolutionCount"/> are not consulted anywhere: the matcher evaluates a fixed
+    /// set of candidate solutions, which keeps its result independent of how long matching takes. Further
     /// features contemplated in this class would require updating the various matching/filtering/slicing
-    /// functions to accept these options, or a particular property. This is the case for the enumerators
-    /// which would be used to prioritize which positions to try and match first. A great implementation
-    /// of the <see cref="IOptionPositionCollectionEnumerator"/> would be to yield positions with the
-    /// highest margin requirements first. At time of writing, the goal is to achieve a workable rev0,
-    /// and we can later improve the efficiency/optimization of the matching process.
+    /// functions to accept these options, or a particular property. This is the case for the position
+    /// enumerator, which would be used to prioritize which positions to try and match first: a great
+    /// implementation of the <see cref="IOptionPositionCollectionEnumerator"/> would be to yield positions
+    /// with the highest margin requirements first.
     /// </remarks>
     public class OptionStrategyMatcherOptions
     {
@@ -54,14 +55,26 @@ public class OptionStrategyMatcherOptions
         /// <summary>
         /// The definitions to be used for matching.
         /// </summary>
+        /// <remarks>
+        /// The configured <see cref="IOptionStrategyDefinitionEnumerator"/> is consulted once and its output is
+        /// cached, so an enumerator yielding a different order on each call has only its first order honored
+        /// </remarks>
         public IEnumerable<OptionStrategyDefinition> Definitions
-            => _definitionEnumerator.Enumerate(_definitions);
+            => _enumeratedDefinitions ??= _definitionEnumerator.Enumerate(_definitions).ToList();
+
+        /// <summary>
+        /// The definitions to be used for matching, deprioritizing those leaving a short option leg uncovered
+        /// </summary>
+        public IEnumerable<OptionStrategyDefinition> CoveredShortsFirstDefinitions
+            => _coveredShortsFirstDefinitions ??= Definitions.OrderBy(HasUncoveredShortLeg).ToList();
 
         /// <summary>
         /// Objective function used to compare different match solutions for a given set of positions/definitions
         /// </summary>
         public IOptionStrategyMatchObjectiveFunction ObjectiveFunction { get; }
 
+        private List<OptionStrategyDefinition> _enumeratedDefinitions;
+        private List<OptionStrategyDefinition> _coveredShortsFirstDefinitions;
         private readonly IReadOnlyList<OptionStrategyDefinition> _definitions;
         private readonly IOptionPositionCollectionEnumerator _positionEnumerator;
         private readonly IOptionStrategyDefinitionEnumerator _definitionEnumerator;
@@ -93,7 +106,9 @@ public OptionStrategyMatcherOptions(
 
             if (objectiveFunction == null)
             {
-                objectiveFunction = new UnmatchedPositionCountOptionStrategyMatchObjectiveFunction();
+                // by default we prefer solutions minimizing the uncovered short option quantity,
+                // a proxy for the margin required to hold the resulting position groups
+                objectiveFunction = new UncoveredShortQuantityOptionStrategyMatchObjectiveFunction();
             }
 
             if (positionEnumerator == null)
@@ -120,6 +135,31 @@ public int GetMaximumLegMatches(int legIndex)
             return MaximumCountPerLeg[legIndex];
         }
 
+        /// <summary>
+        /// Determines whether the definition, matched at the unit level, leaves a short option leg which isn't
+        /// covered by long legs of the same right or by the underlying lots the definition requires. Only ever
+        /// evaluated while building <see cref="CoveredShortsFirstDefinitions"/>, which is cached
+        /// </summary>
+        private static bool HasUncoveredShortLeg(OptionStrategyDefinition definition)
+        {
+            var netCalls = 0;
+            var netPuts = 0;
+            foreach (var leg in definition.Legs)
+            {
+                if (leg.Right == OptionRight.Call)
+                {
+                    netCalls += leg.Quantity;
+                }
+                else
+                {
+                    netPuts += leg.Quantity;
+                }
+            }
+
+            // long underlying lots cover short calls, short underlying lots cover short puts
+            return -netCalls > Math.Max(0, definition.UnderlyingLots) || -netPuts > Math.Max(0, -definition.UnderlyingLots);
+        }
+
         /// <summary>
         /// Enumerates the specified <paramref name="positions"/> according to the configured
         /// <see cref="IOptionPositionCollectionEnumerator"/>