Add arithmetic operators to numeric MultiPeriodField classes (#9571)

* Add arithmetic operators to numeric MultiPeriodField classes

Implement +, -, *, / and % operators on the numeric MultiPeriodField
and MultiPeriodFieldLong base classes so fundamental fields can be
combined arithmetically. Operators act on each field's default-period
Value and return decimal, consistent with the existing implicit decimal
conversion. Includes unit tests covering field-to-field and
field-to-scalar arithmetic for both base classes.

* Add cross-type operators between double and long backed fields

Support arithmetic between the double-backed MultiPeriodField and the
long-backed MultiPeriodFieldLong by adding the mixed-type operator
overloads (both orderings) for +, -, *, / and %. Includes a unit test
covering double/long arithmetic in both directions.

Author: jhonabreul

Common/Data/Fundamental/MultiPeriodField.cs

@@ -191,6 +191,83 @@ public static implicit operator decimal(MultiPeriodField instance)
         {
             return (decimal)instance.Value;
         }
+
+#pragma warning disable CA2225 // Operator overloads have named alternates
+        /// <summary>
+        /// Adds the default values of two fields
+        /// </summary>
+        public static decimal operator +(MultiPeriodField left, MultiPeriodField right) => (decimal)left.Value + (decimal)right.Value;
+
+        /// <summary>
+        /// Subtracts the right field's default value from the left field's default value
+        /// </summary>
+        public static decimal operator -(MultiPeriodField left, MultiPeriodField right) => (decimal)left.Value - (decimal)right.Value;
+
+        /// <summary>
+        /// Multiplies the default values of two fields
+        /// </summary>
+        public static decimal operator *(MultiPeriodField left, MultiPeriodField right) => (decimal)left.Value * (decimal)right.Value;
+
+        /// <summary>
+        /// Divides the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator /(MultiPeriodField left, MultiPeriodField right) => (decimal)left.Value / (decimal)right.Value;
+
+        /// <summary>
+        /// Computes the remainder of dividing the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator %(MultiPeriodField left, MultiPeriodField right) => (decimal)left.Value % (decimal)right.Value;
+
+        /// <summary>
+        /// Adds the default values of a double and a long backed field
+        /// </summary>
+        public static decimal operator +(MultiPeriodField left, MultiPeriodFieldLong right) => (decimal)left.Value + right.Value;
+
+        /// <summary>
+        /// Adds the default values of a long and a double backed field
+        /// </summary>
+        public static decimal operator +(MultiPeriodFieldLong left, MultiPeriodField right) => left.Value + (decimal)right.Value;
+
+        /// <summary>
+        /// Subtracts the right field's default value from the left field's default value
+        /// </summary>
+        public static decimal operator -(MultiPeriodField left, MultiPeriodFieldLong right) => (decimal)left.Value - right.Value;
+
+        /// <summary>
+        /// Subtracts the right field's default value from the left field's default value
+        /// </summary>
+        public static decimal operator -(MultiPeriodFieldLong left, MultiPeriodField right) => left.Value - (decimal)right.Value;
+
+        /// <summary>
+        /// Multiplies the default values of a double and a long backed field
+        /// </summary>
+        public static decimal operator *(MultiPeriodField left, MultiPeriodFieldLong right) => (decimal)left.Value * right.Value;
+
+        /// <summary>
+        /// Multiplies the default values of a long and a double backed field
+        /// </summary>
+        public static decimal operator *(MultiPeriodFieldLong left, MultiPeriodField right) => left.Value * (decimal)right.Value;
+
+        /// <summary>
+        /// Divides the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator /(MultiPeriodField left, MultiPeriodFieldLong right) => (decimal)left.Value / right.Value;
+
+        /// <summary>
+        /// Divides the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator /(MultiPeriodFieldLong left, MultiPeriodField right) => left.Value / (decimal)right.Value;
+
+        /// <summary>
+        /// Computes the remainder of dividing the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator %(MultiPeriodField left, MultiPeriodFieldLong right) => (decimal)left.Value % right.Value;
+
+        /// <summary>
+        /// Computes the remainder of dividing the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator %(MultiPeriodFieldLong left, MultiPeriodField right) => left.Value % (decimal)right.Value;
+#pragma warning restore CA2225 // Operator overloads have named alternates
     }
 
     /// <summary>
@@ -221,5 +298,32 @@ public static implicit operator decimal(MultiPeriodFieldLong instance)
         {
             return (decimal)instance.Value;
         }
+
+#pragma warning disable CA2225 // Operator overloads have named alternates
+        /// <summary>
+        /// Adds the default values of two fields
+        /// </summary>
+        public static decimal operator +(MultiPeriodFieldLong left, MultiPeriodFieldLong right) => (decimal)left.Value + right.Value;
+
+        /// <summary>
+        /// Subtracts the right field's default value from the left field's default value
+        /// </summary>
+        public static decimal operator -(MultiPeriodFieldLong left, MultiPeriodFieldLong right) => (decimal)left.Value - right.Value;
+
+        /// <summary>
+        /// Multiplies the default values of two fields
+        /// </summary>
+        public static decimal operator *(MultiPeriodFieldLong left, MultiPeriodFieldLong right) => (decimal)left.Value * right.Value;
+
+        /// <summary>
+        /// Divides the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator /(MultiPeriodFieldLong left, MultiPeriodFieldLong right) => (decimal)left.Value / right.Value;
+
+        /// <summary>
+        /// Computes the remainder of dividing the left field's default value by the right field's default value
+        /// </summary>
+        public static decimal operator %(MultiPeriodFieldLong left, MultiPeriodFieldLong right) => (decimal)left.Value % right.Value;
+#pragma warning restore CA2225 // Operator overloads have named alternates
     }
 }

Tests/Common/Data/Fundamental/MultiPeriodFieldTests.cs

@@ -109,6 +109,86 @@ public void EmptyStoreToString()
             Assert.AreEqual("", field.ToString());
         }
 
+        [Test]
+        public void ArithmeticOperatorsBetweenDoubleFields()
+        {
+            var left = new TestMultiPeriodField();
+            left.OneYear = 10;
+            var right = new TestMultiPeriodField();
+            right.OneYear = 4;
+
+            Assert.AreEqual(14m, left + right);
+            Assert.AreEqual(6m, left - right);
+            Assert.AreEqual(40m, left * right);
+            Assert.AreEqual(2.5m, left / right);
+            Assert.AreEqual(2m, left % right);
+        }
+
+        [Test]
+        public void ArithmeticOperatorsBetweenLongFields()
+        {
+            var left = new TestMultiPeriodFieldLong();
+            left.OneYear = 10;
+            var right = new TestMultiPeriodFieldLong();
+            right.OneYear = 4;
+
+            Assert.AreEqual(14m, left + right);
+            Assert.AreEqual(6m, left - right);
+            Assert.AreEqual(40m, left * right);
+            Assert.AreEqual(2.5m, left / right);
+            Assert.AreEqual(2m, left % right);
+        }
+
+        [Test]
+        public void ArithmeticOperatorsBetweenDoubleAndLongFields()
+        {
+            var doubleField = new TestMultiPeriodField();
+            doubleField.OneYear = 10;
+            var longField = new TestMultiPeriodFieldLong();
+            longField.OneYear = 4;
+
+            // double on the left, long on the right
+            Assert.AreEqual(14m, doubleField + longField);
+            Assert.AreEqual(6m, doubleField - longField);
+            Assert.AreEqual(40m, doubleField * longField);
+            Assert.AreEqual(2.5m, doubleField / longField);
+            Assert.AreEqual(2m, doubleField % longField);
+
+            // long on the left, double on the right
+            Assert.AreEqual(14m, longField + doubleField);
+            Assert.AreEqual(-6m, longField - doubleField);
+            Assert.AreEqual(40m, longField * doubleField);
+            Assert.AreEqual(0.4m, longField / doubleField);
+            Assert.AreEqual(4m, longField % doubleField);
+        }
+
+        [Test]
+        public void ArithmeticOperatorsWithScalar()
+        {
+            var field = new TestMultiPeriodField();
+            field.OneYear = 10;
+
+            // field implicitly converts to decimal, the built-in decimal operators apply
+            Assert.AreEqual(13m, field + 3m);
+            Assert.AreEqual(7m, field - 3m);
+            Assert.AreEqual(30m, field * 3m);
+            Assert.AreEqual(5m, field / 2m);
+            Assert.AreEqual(1m, field % 3m);
+        }
+
+        [Test]
+        public void ArithmeticOperatorsUseDefaultPeriodValue()
+        {
+            // No default period value available, falls back to first available period (3M = 1)
+            var left = new TestMultiPeriodField();
+            left.ThreeMonths = 1;
+            var right = new TestMultiPeriodField();
+            right.ThreeMonths = 1;
+
+            Assert.IsFalse(left.HasValue);
+            Assert.AreEqual(2m, left + right);
+        }
+
         private class TestMultiPeriodField : MultiPeriodField
         {
             protected override string DefaultPeriod => "OneYear";
@@ -161,5 +241,52 @@ public override IReadOnlyDictionary<string, double> GetPeriodValues()
                 return result;
             }
         }
+
+        private class TestMultiPeriodFieldLong : MultiPeriodFieldLong
+        {
+            protected override string DefaultPeriod => "OneYear";
+
+            public long ThreeMonths { get; set; } = NoValue;
+            public long OneYear { get; set; } = NoValue;
+            public override bool HasValue => !BaseFundamentalDataProvider.IsNone(typeof(long), OneYear);
+            public override long Value
+            {
+                get
+                {
+                    var defaultValue = OneYear;
+                    if (!BaseFundamentalDataProvider.IsNone(typeof(long), defaultValue))
+                    {
+                        return defaultValue;
+                    }
+                    return base.Value;
+                }
+            }
+
+            public override long GetPeriodValue(string period)
+            {
+                switch (period)
+                {
+                    case QuantConnect.Data.Fundamental.Period.ThreeMonths:
+                        return ThreeMonths;
+                    case QuantConnect.Data.Fundamental.Period.OneYear:
+                        return OneYear;
+                    default:
+                        return NoValue;
+                }
+            }
+
+            public override IReadOnlyDictionary<string, long> GetPeriodValues()
+            {
+                var result = new Dictionary<string, long>();
+                foreach (var kvp in new[] { new Tuple<string, long>("1Y", OneYear), new Tuple<string, long>("3M", ThreeMonths) })
+                {
+                    if (!BaseFundamentalDataProvider.IsNone(typeof(long), kvp.Item2))
+                    {
+                        result[kvp.Item1] = kvp.Item2;
+                    }
+                }
+                return result;
+            }
+        }
     }
 }