XML Documentation

lib/core/AbstractBarBase.cs

@@ -1,56 +1,76 @@
 namespace QuanTAlib;
 
 /// <summary>
-/// Provides a base implementation for financial indicators in the QuanTAlib library.
-/// This abstract class implements the iTValue interface and defines common properties
-/// and methods used by inheriting indicator types.
+/// Provides a base implementation for financial indicators that work with bar data in the QuanTAlib library.
 /// </summary>
-public abstract class AbstractBarBase : iTValue
-{
+/// <remarks>
+/// This abstract class implements the iTValue interface and defines common properties
+/// and methods used by inheriting indicator types. It handles the basic flow of
+/// receiving bar data, performing calculations, and publishing results.
+/// </remarks>
+public abstract class AbstractBarBase : iTValue {
     public DateTime Time { get; set; }
     public double Value { get; set; }
     public bool IsNew { get; set; }
     public bool IsHot { get; set; }
-
     public TBar Input { get; set; }
     public String Name { get; set; } = "";
     public int WarmupPeriod { get; set; }
-
-    public TValue Tick => new(Time, Value, IsNew, IsHot); // Stores the current value of indicator
-    public event ValueSignal Pub = delegate { }; // Publisher of generated values
-
-    protected int _index; //tracking the position of output
+    public TValue Tick => new(Time, Value, IsNew, IsHot);
+    public event ValueSignal Pub = delegate { };
+    protected int _index;
     protected double _lastValidValue;
-    // other _internal vars defined here
-
-    protected AbstractBarBase()
-    {  //add parameters into constructor
+    protected AbstractBarBase() {
+        // Add parameters into constructor if needed
     }
 
+    /// <summary>
+    /// Subscribes to bar data updates.
+    /// </summary>
+    /// <param name="source">The source of the bar data.</param>
+    /// <param name="args">The event arguments containing the bar data.</param>
     public void Sub(object source, in TBarEventArgs args) => Calc(args.Bar);
 
-    public virtual void Init()
-    {
+    /// <summary>
+    /// Initializes the indicator's state.
+    /// </summary>
+    public virtual void Init() {
         _index = 0;
         _lastValidValue = 0;
     }
 
-        public virtual TValue Calc(TBar input)
-    {
+    /// <summary>
+    /// Calculates the indicator value based on the input bar.
+    /// </summary>
+    /// <param name="input">The input bar data.</param>
+    /// <returns>A TValue containing the calculated result.</returns>
+    public virtual TValue Calc(TBar input) {
         Input = input;
-        if (double.IsNaN(input.Close) || double.IsInfinity(input.Close))
-        {
+        if (double.IsNaN(input.Close) || double.IsInfinity(input.Close)) {
             return Process(new TValue(Time: input.Time, Value: GetLastValid(), IsNew: input.IsNew, IsHot: true));
         }
         this.Value = Calculation();
         return Process(new TValue(Time: Input.Time, Value: this.Value, IsNew: Input.IsNew, IsHot: this.IsHot));
     }
 
-    protected virtual double GetLastValid()
-    {
+    /// <summary>
+    /// Retrieves the last valid calculated value.
+    /// </summary>
+    /// <returns>The last valid value of the indicator.</returns>
+    protected virtual double GetLastValid() {
         return this.Value;
     }
+
+    /// <summary>
+    /// Manages the state of the indicator based on whether a new bar is being processed.
+    /// </summary>
+    /// <param name="isNew">Indicates whether the current input is a new bar.</param>
     protected abstract void ManageState(bool isNew);
+
+    /// <summary>
+    /// Performs the actual calculation of the indicator value.
+    /// </summary>
+    /// <returns>The calculated indicator value.</returns>
     protected abstract double Calculation();
 
     /// <summary>
@@ -59,8 +79,7 @@ public abstract class AbstractBarBase : iTValue
     /// </summary>
     /// <param name="value">The calculated TValue to process.</param>
     /// <returns>The processed TValue.</returns>
-    protected virtual TValue Process(TValue value)
-    {
+    protected virtual TValue Process(TValue value) {
         this.Time = value.Time;
         this.Value = value.Value;
         this.IsNew = value.IsNew;

lib/core/abstractBase.cs

@@ -2,29 +2,29 @@ namespace QuanTAlib;
 
 /// <summary>
 /// Provides a base implementation for financial indicators in the QuanTAlib library.
-/// This abstract class implements the iTValue interface and defines common properties
-/// and methods used by inheriting indicator types.
 /// </summary>
+/// <remarks>
+/// This abstract class implements the iTValue interface and defines common properties
+/// and methods used by inheriting indicator types. It handles the basic flow of
+/// receiving data, performing calculations, and publishing results.
+/// </remarks>
 public abstract class AbstractBase : iTValue
 {
     public DateTime Time { get; set; }
     public double Value { get; set; }
     public bool IsNew { get; set; }
     public bool IsHot { get; set; }
-
     public TValue Input { get; set; }
     public String Name { get; set; } = "";
     public int WarmupPeriod { get; set; }
-
-    public TValue Tick => new(Time, Value, IsNew, IsHot); // Stores the current value of indicator
-    public event ValueSignal Pub = delegate { }; // Publisher of generated values
-
-    protected int _index; //tracking the position of output
+    public TValue Tick => new(Time, Value, IsNew, IsHot);
+    public event ValueSignal Pub = delegate { };
+    protected int _index;
     protected double _lastValidValue;
-    // other _internal vars defined here
 
     protected AbstractBase()
-    {  //add parameters into constructor
+    {
+        // Add parameters into constructor if needed
     }
 
     /// <summary>
@@ -34,6 +34,9 @@ public abstract class AbstractBase : iTValue
     /// <param name="args">The argument containing the new data point.</param>
     public void Sub(object source, in ValueEventArgs args) => Calc(args.Tick);
 
+    /// <summary>
+    /// Initializes the indicator's state.
+    /// </summary>
     public virtual void Init()
     {
         _index = 0;
@@ -41,11 +44,14 @@ public abstract class AbstractBase : iTValue
     }
 
     /// <summary>
-    /// Calculates the indicator value based on the input; calls specific Calculation() method
-    /// where implementation is
+    /// Calculates the indicator value based on the input.
     /// </summary>
     /// <param name="input">The input value for the calculation.</param>
     /// <returns>A TValue representing the calculated indicator value.</returns>
+    /// <remarks>
+    /// This method calls the specific Calculation() method where the actual implementation is.
+    /// If the input value is NaN or infinity, it returns the last valid value instead.
+    /// </remarks>
     public virtual TValue Calc(TValue input)
     {
         Input = input;
@@ -57,11 +63,25 @@ public abstract class AbstractBase : iTValue
         return Process(new TValue(Time: Input.Time, Value: this.Value, IsNew: Input.IsNew, IsHot: this.IsHot));
     }
 
+    /// <summary>
+    /// Retrieves the last valid calculated value.
+    /// </summary>
+    /// <returns>The last valid value of the indicator.</returns>
     protected virtual double GetLastValid()
     {
         return this.Value;
     }
+
+    /// <summary>
+    /// Manages the state of the indicator based on whether a new data point is being processed.
+    /// </summary>
+    /// <param name="isNew">Indicates whether the current input is a new data point.</param>
     protected abstract void ManageState(bool isNew);
+
+    /// <summary>
+    /// Performs the actual calculation of the indicator value.
+    /// </summary>
+    /// <returns>The calculated indicator value.</returns>
     protected abstract double Calculation();
 
     /// <summary>

lib/core/circularbuffer.cs

@@ -4,55 +4,72 @@ using System.Numerics;
 
 namespace QuanTAlib;
 
-public class CircularBuffer : IEnumerable<double>
-{
+/// <summary>
+/// Represents a circular buffer of double values with fixed capacity.
+/// </summary>
+/// <remarks>
+/// This class provides efficient operations for adding, accessing, and manipulating
+/// a fixed-size buffer of double values. It uses SIMD operations for improved performance
+/// on supported hardware.
+/// </remarks>
+public class CircularBuffer : IEnumerable<double> {
     private readonly double[] _buffer;
     private int _start = 0;
     private int _size = 0;
 
+    /// <summary>
+    /// Gets the maximum number of elements that can be contained in the buffer.
+    /// </summary>
     public int Capacity { get; }
+
+    /// <summary>
+    /// Gets the number of elements currently contained in the buffer.
+    /// </summary>
     public int Count => _size;
 
-    public CircularBuffer(int capacity)
-    {
+    /// <summary>
+    /// Initializes a new instance of the CircularBuffer class with the specified capacity.
+    /// </summary>
+    /// <param name="capacity">The maximum number of elements the buffer can hold.</param>
+    public CircularBuffer(int capacity) {
         Capacity = capacity;
         _buffer = GC.AllocateArray<double>(capacity, pinned: true);
     }
 
+    /// <summary>
+    /// Adds an item to the buffer.
+    /// </summary>
+    /// <param name="item">The item to add to the buffer.</param>
+    /// <param name="isNew">Indicates whether the item is a new value or an update to the last added value.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void Add(double item, bool isNew = true)
-    {
-        if (_size == 0 || isNew)
-        {
-            if (_size < Capacity)
-            {
+    public void Add(double item, bool isNew = true) {
+        if (_size == 0 || isNew) {
+            if (_size < Capacity) {
                 _buffer[(_start + _size) % Capacity] = item;
                 _size++;
-            }
-            else
-            {
+            } else {
                 _buffer[_start] = item;
                 _start = (_start + 1) % Capacity;
             }
-        }
-        else
-        {
+        } else {
             _buffer[(_start + _size - 1) % Capacity] = item;
         }
     }
 
-    public double this[Index index]
-    {
+    /// <summary>
+    /// Gets or sets the element at the specified index.
+    /// </summary>
+    /// <param name="index">The zero-based index of the element to get or set.</param>
+    /// <returns>The element at the specified index.</returns>
+    public double this[Index index] {
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        get
-        {
+        get {
             int actualIndex = index.IsFromEnd ? _size - index.Value : index.Value;
             actualIndex = Math.Clamp(actualIndex, 0, _size - 1);
             return _buffer[(_start + actualIndex) % Capacity];
         }
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        set
-        {
+        set {
             int actualIndex = index.IsFromEnd ? _size - index.Value : index.Value;
             actualIndex = Math.Clamp(actualIndex, 0, _size - 1);
             _buffer[(_start + actualIndex) % Capacity] = value;
@@ -60,54 +77,66 @@ public class CircularBuffer : IEnumerable<double>
     }
 
     [MethodImpl(MethodImplOptions.NoInlining)]
-    private static void ThrowArgumentOutOfRangeException()
-    {
+    private static void ThrowArgumentOutOfRangeException() {
         throw new ArgumentOutOfRangeException("index", "Index is out of range.");
     }
 
+    /// <summary>
+    /// Gets the newest (most recently added) element in the buffer.
+    /// </summary>
+    /// <returns>The newest element in the buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Newest()
-    {
+    public double Newest() {
         if (_size == 0)
             return 0;
         return _buffer[(_start + _size - 1) % Capacity];
     }
 
+    /// <summary>
+    /// Gets the oldest element in the buffer.
+    /// </summary>
+    /// <returns>The oldest element in the buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Oldest()
-    {
+    public double Oldest() {
         if (_size == 0)
             ThrowInvalidOperationException();
         return _buffer[_start];
     }
 
     [MethodImpl(MethodImplOptions.NoInlining)]
-    private static void ThrowInvalidOperationException()
-    {
+    private static void ThrowInvalidOperationException() {
         throw new InvalidOperationException("Buffer is empty.");
     }
 
+    /// <summary>
+    /// Returns an enumerator that iterates through the buffer.
+    /// </summary>
+    /// <returns>An enumerator for the buffer.</returns>
     public Enumerator GetEnumerator() => new(this);
     IEnumerator<double> IEnumerable<double>.GetEnumerator() => GetEnumerator();
     IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
-    public struct Enumerator : IEnumerator<double>
-    {
+    /// <summary>
+    /// Represents an enumerator for the CircularBuffer.
+    /// </summary>
+    public struct Enumerator : IEnumerator<double> {
         private readonly CircularBuffer _buffer;
         private int _index;
         private double _current;
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal Enumerator(CircularBuffer buffer)
-        {
+        internal Enumerator(CircularBuffer buffer) {
             _buffer = buffer;
             _index = -1;
             _current = default;
         }
 
+        /// <summary>
+        /// Advances the enumerator to the next element of the buffer.
+        /// </summary>
+        /// <returns>true if the enumerator was successfully advanced to the next element; false if the enumerator has passed the end of the collection.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public bool MoveNext()
-        {
+        public bool MoveNext() {
             if (_index + 1 >= _buffer._size)
                 return false;
 
@@ -116,92 +145,122 @@ public class CircularBuffer : IEnumerable<double>
             return true;
         }
 
+        /// <summary>
+        /// Gets the element in the buffer at the current position of the enumerator.
+        /// </summary>
         public double Current => _current;
         object IEnumerator.Current => Current;
 
-        public void Reset()
-        {
+        /// <summary>
+        /// Sets the enumerator to its initial position, which is before the first element in the buffer.
+        /// </summary>
+        public void Reset() {
             _index = -1;
             _current = default;
         }
 
+        /// <summary>
+        /// Disposes the enumerator.
+        /// </summary>
         public void Dispose() { }
     }
 
+    /// <summary>
+    /// Copies the elements of the buffer to an array, starting at a particular array index.
+    /// </summary>
+    /// <param name="destination">The one-dimensional array that is the destination of the elements copied from the buffer.</param>
+    /// <param name="destinationIndex">The zero-based index in array at which copying begins.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void CopyTo(double[] destination, int destinationIndex)
-    {
+    public void CopyTo(double[] destination, int destinationIndex) {
         if (_size == 0)
             return;
 
-        if (_start + _size <= Capacity)
-        {
+        if (_start + _size <= Capacity) {
             Array.Copy(_buffer, _start, destination, destinationIndex, _size);
-        }
-        else
-        {
+        } else {
             int firstPartLength = Capacity - _start;
             Array.Copy(_buffer, _start, destination, destinationIndex, firstPartLength);
             Array.Copy(_buffer, 0, destination, destinationIndex + firstPartLength, _size - firstPartLength);
         }
     }
 
+    /// <summary>
+    /// Returns a read-only span over the contents of the buffer.
+    /// </summary>
+    /// <returns>A read-only span over the buffer contents.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public ReadOnlySpan<double> GetSpan()
-    {
+    public ReadOnlySpan<double> GetSpan() {
         if (_size == 0)
             return ReadOnlySpan<double>.Empty;
 
-        if (_start + _size <= Capacity)
-        {
+        if (_start + _size <= Capacity) {
             return new ReadOnlySpan<double>(_buffer, _start, _size);
-        }
-        else
-        {
+        } else {
             return new ReadOnlySpan<double>(ToArray());
         }
     }
 
+    /// <summary>
+    /// Gets the internal buffer array.
+    /// </summary>
     public double[] InternalBuffer => _buffer;
 
+    /// <summary>
+    /// Returns a read-only span over the entire internal buffer.
+    /// </summary>
+    /// <returns>A read-only span over the entire internal buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public ReadOnlySpan<double> GetInternalSpan() => _buffer.AsSpan();
 
+    /// <summary>
+    /// Removes all elements from the buffer.
+    /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void Clear()
-    {
+    public void Clear() {
         Array.Clear(_buffer, 0, _buffer.Length);
         _start = 0;
         _size = 0;
     }
 
+    /// <summary>
+    /// Returns the maximum value in the buffer.
+    /// </summary>
+    /// <returns>The maximum value in the buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Max()
-    {
+    public double Max() {
         if (_size == 0)
             ThrowInvalidOperationException();
 
         return MaxSimd();
     }
 
+    /// <summary>
+    /// Returns the minimum value in the buffer.
+    /// </summary>
+    /// <returns>The minimum value in the buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Min()
-    {
+    public double Min() {
         if (_size == 0)
             ThrowInvalidOperationException();
 
         return MinSimd();
     }
 
+    /// <summary>
+    /// Computes the sum of all values in the buffer.
+    /// </summary>
+    /// <returns>The sum of all values in the buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Sum()
-    {
+    public double Sum() {
         return SumSimd();
     }
 
+    /// <summary>
+    /// Computes the average of all values in the buffer.
+    /// </summary>
+    /// <returns>The average of all values in the buffer.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Average()
-    {
+    public double Average() {
         if (_size == 0)
             ThrowInvalidOperationException();
 
@@ -209,26 +268,22 @@ public class CircularBuffer : IEnumerable<double>
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private double MaxSimd()
-    {
+    private double MaxSimd() {
         var span = GetSpan();
         var vectorSize = Vector<double>.Count;
         var maxVector = new Vector<double>(double.MinValue);
 
         int i = 0;
-        for (; i <= span.Length - vectorSize; i += vectorSize)
-        {
+        for (; i <= span.Length - vectorSize; i += vectorSize) {
             maxVector = Vector.Max(maxVector, new Vector<double>(span.Slice(i, vectorSize)));
         }
 
         double max = double.MinValue;
-        for (int j = 0; j < vectorSize; j++)
-        {
+        for (int j = 0; j < vectorSize; j++) {
             max = Math.Max(max, maxVector[j]);
         }
 
-        for (; i < span.Length; i++)
-        {
+        for (; i < span.Length; i++) {
             max = Math.Max(max, span[i]);
         }
 
@@ -236,26 +291,22 @@ public class CircularBuffer : IEnumerable<double>
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private double MinSimd()
-    {
+    private double MinSimd() {
         var span = GetSpan();
         var vectorSize = Vector<double>.Count;
         var minVector = new Vector<double>(double.MaxValue);
 
         int i = 0;
-        for (; i <= span.Length - vectorSize; i += vectorSize)
-        {
+        for (; i <= span.Length - vectorSize; i += vectorSize) {
             minVector = Vector.Min(minVector, new Vector<double>(span.Slice(i, vectorSize)));
         }
 
         double min = double.MaxValue;
-        for (int j = 0; j < vectorSize; j++)
-        {
+        for (int j = 0; j < vectorSize; j++) {
             min = Math.Min(min, minVector[j]);
         }
 
-        for (; i < span.Length; i++)
-        {
+        for (; i < span.Length; i++) {
             min = Math.Min(min, span[i]);
         }
 
@@ -263,45 +314,46 @@ public class CircularBuffer : IEnumerable<double>
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private double SumSimd()
-    {
+    private double SumSimd() {
         var span = GetSpan();
         var vectorSize = Vector<double>.Count;
         var sumVector = Vector<double>.Zero;
 
         int i = 0;
-        for (; i <= span.Length - vectorSize; i += vectorSize)
-        {
+        for (; i <= span.Length - vectorSize; i += vectorSize) {
             sumVector += new Vector<double>(span.Slice(i, vectorSize));
         }
 
         double sum = 0;
-        for (int j = 0; j < vectorSize; j++)
-        {
+        for (int j = 0; j < vectorSize; j++) {
             sum += sumVector[j];
         }
 
-        for (; i < span.Length; i++)
-        {
+        for (; i < span.Length; i++) {
             sum += span[i];
         }
 
         return sum;
     }
 
-    public double[] ToArray()
-    {
+    /// <summary>
+    /// Copies the buffer elements to a new array.
+    /// </summary>
+    /// <returns>An array containing copies of the buffer elements.</returns>
+    public double[] ToArray() {
         double[] array = new double[_size];
         CopyTo(array, 0);
         return array;
     }
 
-    public void ParallelOperation(Func<double[], int, int, double> operation)
-    {
+    /// <summary>
+    /// Performs a parallel operation on the buffer elements.
+    /// </summary>
+    /// <param name="operation">The operation to perform on each partition of the buffer.</param>
+    public void ParallelOperation(Func<double[], int, int, double> operation) {
         const int MinimumPartitionSize = 1024;
 
-        if (_size < MinimumPartitionSize)
-        {
+        if (_size < MinimumPartitionSize) {
             var span = GetSpan();
             var array = span.ToArray();
             operation(array, 0, array.Length);
@@ -311,8 +363,7 @@ public class CircularBuffer : IEnumerable<double>
         int partitionCount = Environment.ProcessorCount;
         int partitionSize = _size / partitionCount;
 
-        if (partitionSize < MinimumPartitionSize)
-        {
+        if (partitionSize < MinimumPartitionSize) {
             partitionCount = Math.Max(1, _size / MinimumPartitionSize);
             partitionSize = _size / partitionCount;
         }
@@ -320,13 +371,10 @@ public class CircularBuffer : IEnumerable<double>
         var buffer = ToArray();
         var results = new double[partitionCount];
 
-        Parallel.For(0, partitionCount, i =>
-        {
+        Parallel.For(0, partitionCount, i => {
             int start = i * partitionSize;
             int length = (i == partitionCount - 1) ? _size - start : partitionSize;
             results[i] = operation(buffer, start, length);
         });
-
     }
-
 }