refactor: Performance tuning (stream + incr experiments)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -23,7 +23,7 @@ body:
       render: csharp
       placeholder: |
         // example (put your own code here)
-        IEnumerable<EmaResult> results = quotes.GetEma(14);
+        IReadOnlyList<EmaResult> results = quotes.GetEma(14);
     validations:
       required: false
   - type: textarea

.github/workflows/test-performance.yml

@@ -47,7 +47,7 @@ jobs:
         run: dotnet run -c Release
 
       - name: Save test results
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: test-summaries
           path: tests/performance/BenchmarkDotNet.Artifacts/results
@@ -62,3 +62,9 @@ jobs:
 
           echo "## Stream indicators (with Quote caching)" >> $GITHUB_STEP_SUMMARY
           cat Performance.StreamIndicators-report-github.md >> $GITHUB_STEP_SUMMARY
+
+          echo "## Incremental indicators (with buffer)" >> $GITHUB_STEP_SUMMARY
+          cat Performance.Incrementals-report-github.md >> $GITHUB_STEP_SUMMARY
+
+          echo "## Utilities" >> $GITHUB_STEP_SUMMARY
+          cat Performance.Utility-report-github.md >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -111,12 +111,13 @@ $tf/
 # Guidance Automation Toolkit
 *.gpState
 
-# ReSharper is a .NET coding add-in
+# ReSharper IDE extension
 _ReSharper*/
 *.[Rr]e[Ss]harper
 *.DotSettings.user
+*.DotSettings
 
-# JustCode is a .NET coding add-in
+# JustCode IDE extension
 .JustCode
 
 # TeamCity is a build add-in
@@ -218,7 +219,7 @@ ClientBin/
 *.publishsettings
 orleans.codegen.cs
 
-# Including strong name files can present a security risk 
+# Including strong name files can present a security risk
 # (https://github.com/github/gitignore/pull/2483#issue-259490424)
 #*.snk
 
@@ -314,7 +315,7 @@ __pycache__/
 # OpenCover UI analysis results
 OpenCover/
 
-# Azure Stream Analytics local run output 
+# Azure Stream Analytics local run output
 ASALocalRun/
 
 # MSBuild Binary and Structured Log
@@ -323,11 +324,11 @@ ASALocalRun/
 # NVidia Nsight GPU debugger configuration file
 *.nvuser
 
-# MFractors (Xamarin productivity tool) working folder 
+# MFractors (Xamarin productivity tool) working folder
 .mfractor/
 
 # Jekyll site
 _site/
 
 # zip artifacts
-.DS_Store
+.DS_Store

docs/_data/aliases.yml

@@ -59,23 +59,23 @@
   type: price-characteristic
 
 - title: HL2
-  permalink: /indicators/BasicQuote/
+  permalink: /indicators/quotepart/
   type: price-transform
 
 - title: HLC3
-  permalink: /indicators/BasicQuote/
+  permalink: /indicators/quotepart/
   type: price-transform
 
 - title: OC2
-  permalink: /indicators/BasicQuote/
+  permalink: /indicators/quotepart/
   type: price-transform
 
 - title: OHL3
-  permalink: /indicators/BasicQuote/
+  permalink: /indicators/quotepart/
   type: price-transform
 
 - title: OHLC4
-  permalink: /indicators/BasicQuote/
+  permalink: /indicators/quotepart/
   type: price-transform
 
 - title: Price Channels

docs/_indicators/AtrStop.md

@@ -57,11 +57,11 @@ IReadOnlyList<AtrStopResult>
 
 **`Timestamp`** _`DateTime`_ - date from evaluated `TQuote`
 
-**`AtrStop`** _`decimal`_ - ATR Trailing Stop line contains both Upper and Lower segments
+**`AtrStop`** _`double`_ - ATR Trailing Stop line contains both Upper and Lower segments
 
-**`BuyStop`** _`decimal`_ - Upper band only (green)
+**`BuyStop`** _`double`_ - Upper band only (green)
 
-**`SellStop`** _`decimal`_ - Lower band only (red)
+**`SellStop`** _`double`_ - Lower band only (red)
 
 **`Atr`** _`double`_ - Average True Range
 

docs/_indicators/Beta.md

@@ -22,7 +22,7 @@ IReadOnlyList<BetaResult> results = quotesEval
 
 ## Parameters
 
-**`quotesMarket`** _`IEnumerable<TQuote>`_ - [Historical quotes]({{site.baseurl}}/guide/#historical-quotes) market data should be at any consistent frequency (day, hour, minute, etc).  This `market` quotes will be used to establish the baseline.
+**`quotesMarket`** _`IReadOnlyList<TQuote>`_ - [Historical quotes]({{site.baseurl}}/guide/#historical-quotes) market data should be at any consistent frequency (day, hour, minute, etc).  This `market` quotes will be used to establish the baseline.
 
 **`lookbackPeriods`** _`int`_ - Number of periods (`N`) in the lookback window.  Must be greater than 0 to calculate; however we suggest a larger period for statistically appropriate sample size and especially when using Beta +/-.
 

docs/_indicators/Correlation.md

@@ -30,7 +30,7 @@ IReadOnlyList<CorrResult> results =
 
 You must have at least `N` periods for both versions of `quotes` to cover the warmup periods.  Mismatch histories will produce a `InvalidQuotesException`.  Historical price quotes should have a consistent frequency (day, hour, minute, etc).
 
-`quotesA` is an `IEnumerable<TQuote>` collection of historical price quotes.  It should have a consistent frequency (day, hour, minute, etc).  See [the Guide]({{site.baseurl}}/guide/#historical-quotes) for more information.
+`quotesA` is an `IReadOnlyList<TQuote>` collection of historical price quotes.  It should have a consistent frequency (day, hour, minute, etc).  See [the Guide]({{site.baseurl}}/guide/#historical-quotes) for more information.
 
 ## Response
 

docs/_indicators/Use.md → docs/_indicators/QuotePart.md

@@ -1,19 +1,26 @@
 ---
-title: Basic quote transform
+title: Quote parts and basic transforms
 description: Basic quote transforms (e.g. HL2, OHL3, etc.) and isolation of individual price quote candle parts from a full OHLCV quote.
-permalink: /indicators/Use/
+permalink: /indicators/quotepart/
+redirect-from:
+  - /indicators/Use/
+  - /indicators/BasicQuote/
 type: price-transform
 layout: indicator
 ---
 
 # {{ page.title }}
 
-Returns a reusable (chainable) basic quote transform (e.g. HL2, OHL3, etc.) by isolating a single value or calculated value from the full OHLCV quote candle parts.
+Returns a reusable (chainable) basic quote transform (e.g. HL2, OHL3, etc.) by isolating a single component part value or calculated value from the full OHLCV quote candle parts.
 
 ```csharp
 // C# usage syntax
 IReadOnlyList<QuotePart> results =
   quotes.Use(candlePart);
+
+// alternate syntax
+IReadOnlyList<QuotePart> results =
+  quotes.GetQuotePart(candlePart);
 ```
 
 ## Parameters

docs/examples/CustomIndicators/AtrWma.cs

@@ -18,7 +18,7 @@ public static class CustomIndicators
 {
     // Custom ATR WMA calculation
     public static IReadOnlyList<AtrWmaResult> GetAtrWma<TQuote>(
-        this IEnumerable<TQuote> quotes,
+        this IReadOnlyList<TQuote> quotes,
         int lookbackPeriods)
         where TQuote : IQuote
     {

docs/pages/guide.md

@@ -43,7 +43,7 @@ Most indicators require that you provide historical quote data and additional co
 
 You must get historical quotes from your own market data provider.  For clarification, the `GetQuotesFromFeed()` method shown in the example below **is not part of this library**, but rather an example to represent your own acquisition of historical quotes.
 
-Historical price data can be provided as a `List`, `IEnumerable`, or `ICollection` of the `Quote` class ([see below](#historical-quotes)); however, it can also be supplied as a generic [custom TQuote type](#using-custom-quote-classes) if you prefer to use your own quote model.
+Historical price data can be provided as a `List`, `IReadOnlyList`, or `ICollection` of the `Quote` class ([see below](#historical-quotes)); however, it can also be supplied as a generic [custom TQuote type](#using-custom-quote-classes) if you prefer to use your own quote model.
 
 For additional configuration parameters, default values are provided when there is an industry standard.  You can, of course, override these and provide your own values.
 
@@ -57,7 +57,7 @@ using Skender.Stock.Indicators;
 [..]
 
 // fetch historical quotes from your feed (your method)
-IEnumerable<Quote> quotes = GetQuotesFromFeed("MSFT");
+IReadOnlyList<Quote> quotes = GetQuotesFromFeed("MSFT");
 
 // calculate 20-period SMA
 IReadOnlyList<SmaResult> results = quotes
@@ -89,7 +89,7 @@ More examples available:
 
 ## Historical quotes
 
-You must provide historical price quotes to the library in the standard OHLCV `IEnumerable<Quote>` or a compatible `List` or `ICollection` format.  It should have a consistent period frequency (day, hour, minute, etc).  See [using custom quote classes](#using-custom-quote-classes) if you prefer to use your own quote class.
+You must provide historical price quotes to the library in the standard OHLCV `IReadOnlyList<Quote>` or a compatible `List` or `ICollection` format.  It should have a consistent period frequency (day, hour, minute, etc).  See [using custom quote classes](#using-custom-quote-classes) if you prefer to use your own quote class.
 
 | name | type | notes
 | -- |-- |--
@@ -194,10 +194,10 @@ public class MyCustomQuote : IQuote
 ```csharp
 // USAGE
 // fetch historical quotes from your favorite feed
-IEnumerable<MyCustomQuote> myQuotes = GetQuotesFromFeed("MSFT");
+IReadOnlyList<MyCustomQuote> myQuotes = GetQuotesFromFeed("MSFT");
 
 // example: get 20-period simple moving average
-IEnumerable<SmaResult> results = myQuotes.GetSma(20);
+IReadOnlyList<SmaResult> results = myQuotes.GetSma(20);
 ```
 
 #### Using custom quote property names
@@ -247,7 +247,7 @@ Example:
 
 ```csharp
 // fetch historical quotes from your feed (your method)
-IEnumerable<Quote> quotes = GetQuotesFromFeed("SPY");
+IReadOnlyList<Quote> quotes = GetQuotesFromFeed("SPY");
 
 // calculate RSI of OBV
 IReadOnlyList<RsiResult> results

docs/pages/utilities.md

@@ -30,23 +30,23 @@ var results = quotes
 
 ### Sort quotes
 
-`quotes.ToSortedCollection()` sorts any collection of `TQuote` or `ISeries` and returns it as a `Collection` sorted by ascending `Timestamp`.  You do not need to sort quotes before using library indicators; however, if you are creating [custom indicators]({{site.baseurl}}/custom-indicators/#content) it's important to analyze `quotes` in a proper sequence.
+`quotes.ToSortedList()` sorts any collection of `TQuote` or `ISeries` and returns it as a `IReadOnlyList` sorted by ascending `Timestamp`.  You **do need to sort quotes** before using library indicators.
 
 ### Resize quote history
 
 `quotes.Aggregate(newSize)` is a tool to convert quotes to larger bar sizes.  For example if you have minute bar sizes in `quotes`, but want to convert it to hourly or daily.
 
 ```csharp
 // aggregate into larger bars
-IEnumerable<Quote> dayBarQuotes =
+IReadOnlyList<Quote> dayBarQuotes =
   minuteBarQuotes.Aggregate(PeriodSize.Day);
 ```
 
 An alternate version of this utility is provided where you can use any native `TimeSpan` value that is greater than `TimeSpan.Zero`.
 
 ```csharp
 // alternate usage with TimeSpan
-IEnumerable<Quote> dayBarQuotes =
+IReadOnlyList<Quote> dayBarQuotes =
   minuteBarQuotes.Aggregate(TimeSpan timeSpan);
 ```
 
@@ -87,7 +87,7 @@ IReadOnlyList<CandleProperties> candles = quotes.ToCandles();
 
 ```csharp
 // advanced validation
-IEnumerable<Quote> validatedQuotes = quotes.Validate();
+IReadOnlyList<Quote> validatedQuotes = quotes.Validate();
 
 // and can be used inline with chaining
 var results = quotes
@@ -148,7 +148,7 @@ See [individual indicator pages]({{site.baseurl}}/indicators/#content) for infor
 
 ### Sort results
 
-`results.ToSortedCollection()` sorts any collection of indicator results and returns it as a `Collection` sorted by ascending `Timestamp`.  Results from the library indicators are already sorted, so you'd only potentially need this if you're creating [custom indicators]({{site.baseurl}}/custom-indicators/#content).
+`results.ToSortedList()` sorts any collection of indicator results and returns it as a `IReadOnlyList` sorted by ascending `Timestamp`.  Results from the library indicators are already sorted, so you'd only potentially need this if you're creating [custom indicators]({{site.baseurl}}/custom-indicators/#content).
 
 ## Utilities for numerical analysis
 

src/_common/BinarySettings.cs

@@ -0,0 +1,110 @@
+namespace Skender.Stock.Indicators;
+
+/// <summary>
+/// Binary on/off switches for high performance access
+/// to behaviors and characteristics.
+/// </summary>
+/// <remarks>
+/// Initializes a new instance of the <see cref="BinarySettings"/> struct.
+/// The Mask parameter is optional and defaults to 0b11111111 where all bits
+/// pass through to "combinor" sets.
+///
+/// Example of accessing a specific bit:
+/// <code>
+/// BinarySettings settings = new(0b00000001); // bit 0 is set to 1
+/// bool isBit0Set = settings[0]; // true
+/// bool isBit1Set = settings[1]; // false
+/// </code>
+///
+/// Example of re/setting a specific bit:
+/// <code>
+/// BinarySettings settings = new(0);
+/// settings = settings with { [0] = true  }; // set bit 0 to true
+/// settings = settings with { [1] = false }; // set bit 1 to false
+/// </code>
+/// </remarks>
+/// <param name="settings">
+/// Binary settings.
+/// Default is 0b00000000 (binary literal of 0).
+/// </param>
+/// <param name="mask">
+/// Mask for settings inheritence.
+/// Default is 0b11111111 (binary literal of 255).
+/// </param>
+public readonly struct BinarySettings(
+    byte settings,
+    byte mask = 0b11111111) : IEquatable<BinarySettings>
+{
+    public byte Settings { get; } = settings;
+    public byte Mask { get; } = mask;
+
+    // use default settings (none) and mask
+    // important: this explicit parameterless ctor required for struct
+    public BinarySettings() : this(settings: 0b00000000) { }
+
+    /// <summary>
+    /// Gets the value of the bit at the specified index.
+    /// </summary>
+    /// <param name="index">The index of the bit to get.</param>
+    /// <returns>True if the bit is set; otherwise, false.</returns>
+    public bool this[short index]
+        => (Settings & (1 << index)) != 0;
+
+    /// <summary>
+    /// Combines the current settings with another <see cref="BinarySettings"/> instance
+    /// using a bitwise OR operation, excluding the bits masked by the parent settings.
+    /// </summary>
+    /// <param name="parentSettings">The parent <see cref="BinarySettings"/> instance to combine with.</param>
+    /// <returns>
+    /// A new <see cref="BinarySettings"/> instance with combined settings.
+    /// Notably, it does not modify the current read-only instance.
+    /// </returns>
+    ///
+    /// <remarks>
+    /// The mask is used to determine which bits from the parent settings should be excluded
+    /// during the combination. By default, the mask is set to 0b11111111, meaning all bits
+    /// are included. If a different mask is provided, the corresponding bits in the parent
+    /// settings will be excluded based on the mask.
+    /// <para>
+    /// In other words, the mask you provide on instantiation will determine which bits are
+    /// genetic material passed on to the "combinor" child settings. The child settings will inherit the
+    /// bits from the parent settings that the parent decides to pass along.
+    /// </para>
+    ///
+    /// Usage example (default mask):
+    /// <code>
+    /// BinarySettings srcSettings = new(0b01101001);
+    /// BinarySettings defSettings = new(0b00000010);
+    /// BinarySettings newSettings = defSettings.Combine(srcSettings);  // result: 0b01101011
+    /// </code>
+    /// Using a custom mask:
+    /// <code>
+    /// BinarySettings customMaskSettings = new(0b01101001, 0b11111110);  // do not pass 0th bit value
+    /// BinarySettings newSettingsWithCustomMask = defSettings.Combine(customMaskSettings);  // result: 0b01101010
+    /// </code>
+    /// </remarks>
+    public BinarySettings Combine(BinarySettings parentSettings)
+    {
+        // add parent bits according to their mask template
+        byte maskedParentSettings = (byte)(parentSettings.Settings & parentSettings.Mask);
+
+        // combine the settings
+        return new BinarySettings((byte)(Settings | maskedParentSettings), parentSettings.Mask);
+    }
+
+    public override bool Equals(object? obj)
+        => obj is BinarySettings other && Equals(other);
+
+    public bool Equals(BinarySettings other)
+        => Settings == other.Settings && Mask == other.Mask;
+
+    public override int GetHashCode()
+        => HashCode.Combine(Settings, Mask);
+
+    public static bool operator ==(BinarySettings left, BinarySettings right)
+        => left.Equals(right);
+
+    public static bool operator !=(BinarySettings left, BinarySettings right)
+        => !(left == right);
+}
+