mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-25 05:48:06 +00:00
Update SVG badges and missing indicators report
- Updated class count in classes.svg from 938 to 1078. - Adjusted comments percentage in comments.svg from 33.06 to 33.02. - Revised average cyclomatic complexity in complexity.svg from 2.19 to 2.12. - Increased source files count in files.svg from 1099 to 1275. - Updated lines of code in loc.svg from 114549 to 129859. - Increased methods count in methods.svg from 12035 to 14066. - Updated public types count in public-api.svg from 1086 to 1225. - Revised missing indicators report with updated counts and categories, reflecting recent implementations and planned additions.
This commit is contained in:
Miha Kralj
@@ -0,0 +1,406 @@
|
||||
using System.Buffers;
|
||||
using System.Runtime.CompilerServices;
|
||||
using System.Runtime.InteropServices;
|
||||
|
||||
namespace QuanTAlib;
|
||||
|
||||
/// <summary>
|
||||
/// HARMEAN: Harmonic Mean over a rolling window
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Harmonic Mean is the reciprocal of the arithmetic mean of reciprocals:
|
||||
/// HM = n / Σ(1/xᵢ). It penalizes extreme values more strongly than the
|
||||
/// arithmetic or geometric mean, making it useful for averaging rates,
|
||||
/// ratios, and price/earnings multiples.
|
||||
///
|
||||
/// The running sum of reciprocals enables O(1) updates: add 1/new, subtract 1/old.
|
||||
/// Kahan-Babuška summation prevents floating-point drift in the reciprocal accumulator.
|
||||
/// Periodic resync (every 1000 ticks) guards against long-running drift.
|
||||
///
|
||||
/// Non-positive values are replaced with the last valid positive value, since
|
||||
/// 1/x is undefined for x = 0 and negative reciprocals break the mean.
|
||||
/// For price series (always positive), this substitution is rarely triggered.
|
||||
///
|
||||
/// Key Features:
|
||||
/// - O(1) time complexity per update via running sum of reciprocals
|
||||
/// - Kahan-Babuška compensated summation for numerical stability
|
||||
/// - Periodic resync every 1000 ticks to limit FP drift
|
||||
/// - NaN/Infinity/non-positive substitution with last valid value
|
||||
///
|
||||
/// IsHot:
|
||||
/// Becomes true when the buffer is full (period samples processed).
|
||||
/// </remarks>
|
||||
[SkipLocalsInit]
|
||||
public sealed class Harmean : AbstractBase
|
||||
{
|
||||
private readonly int _period;
|
||||
private readonly RingBuffer _buffer;
|
||||
private readonly TValuePublishedHandler _handler;
|
||||
private readonly ITValuePublisher? _source;
|
||||
private bool _disposed;
|
||||
|
||||
[StructLayout(LayoutKind.Auto)]
|
||||
private record struct State
|
||||
{
|
||||
public double SumReciprocal;
|
||||
public double C; // Kahan primary compensation
|
||||
public double Cc; // Kahan secondary compensation (Babuška)
|
||||
public double LastValidValue;
|
||||
public int TickCount;
|
||||
}
|
||||
|
||||
private State _s;
|
||||
private State _ps;
|
||||
|
||||
private const int ResyncInterval = 1000;
|
||||
|
||||
public Harmean(int period)
|
||||
{
|
||||
if (period <= 0)
|
||||
{
|
||||
throw new ArgumentException("Period must be greater than 0", nameof(period));
|
||||
}
|
||||
|
||||
_period = period;
|
||||
_buffer = new RingBuffer(period);
|
||||
Name = $"Harmean({period})";
|
||||
WarmupPeriod = period;
|
||||
_handler = Handle;
|
||||
}
|
||||
|
||||
public Harmean(ITValuePublisher source, int period) : this(period)
|
||||
{
|
||||
_source = source;
|
||||
source.Pub += _handler;
|
||||
}
|
||||
|
||||
public Harmean(TSeries source, int period) : this(period)
|
||||
{
|
||||
_source = source;
|
||||
source.Pub += _handler;
|
||||
Prime(source.Values);
|
||||
if (source.Count > 0)
|
||||
{
|
||||
Last = new TValue(source.LastTime, Last.Value);
|
||||
}
|
||||
_ps = _s;
|
||||
}
|
||||
|
||||
private void Handle(object? sender, in TValueEventArgs e) => Update(e.Value, e.IsNew);
|
||||
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
// Mode B: Streaming (Stateful)
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
public override bool IsHot => _buffer.IsFull;
|
||||
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
// Kahan-Babuška Core Operations (reciprocal domain)
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
private void KahanAdd(double x)
|
||||
{
|
||||
double y = x - _s.C;
|
||||
double t = _s.SumReciprocal + y;
|
||||
_s.C = (t - _s.SumReciprocal) - y;
|
||||
_s.SumReciprocal = t;
|
||||
|
||||
double z = _s.C - _s.Cc;
|
||||
double tt = _s.SumReciprocal + z;
|
||||
_s.Cc = (tt - _s.SumReciprocal) - z;
|
||||
_s.SumReciprocal = tt;
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
private void KahanSubtract(double x)
|
||||
{
|
||||
KahanAdd(-x);
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
private void RecalculateSumReciprocal()
|
||||
{
|
||||
_s.SumReciprocal = 0;
|
||||
_s.C = 0;
|
||||
_s.Cc = 0;
|
||||
|
||||
var span = _buffer.GetSpan();
|
||||
for (int i = 0; i < span.Length; i++)
|
||||
{
|
||||
KahanAdd(1.0 / span[i]);
|
||||
}
|
||||
}
|
||||
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
// Mode C: Priming (The Bridge)
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
public override void Prime(ReadOnlySpan<double> source, TimeSpan? step = null)
|
||||
{
|
||||
if (source.Length == 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
_buffer.Clear();
|
||||
_s = default;
|
||||
_ps = default;
|
||||
|
||||
int warmupLength = Math.Min(source.Length, WarmupPeriod);
|
||||
int startIndex = source.Length - warmupLength;
|
||||
|
||||
// Seed LastValidValue from prior context
|
||||
_s.LastValidValue = double.NaN;
|
||||
for (int i = startIndex - 1; i >= 0; i--)
|
||||
{
|
||||
if (double.IsFinite(source[i]) && source[i] > 0)
|
||||
{
|
||||
_s.LastValidValue = source[i];
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (double.IsNaN(_s.LastValidValue))
|
||||
{
|
||||
for (int i = startIndex; i < source.Length; i++)
|
||||
{
|
||||
if (double.IsFinite(source[i]) && source[i] > 0)
|
||||
{
|
||||
_s.LastValidValue = source[i];
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (int i = startIndex; i < source.Length; i++)
|
||||
{
|
||||
double val = GetValidValue(source[i]);
|
||||
_buffer.Add(val);
|
||||
KahanAdd(1.0 / val);
|
||||
}
|
||||
|
||||
double result = (_buffer.Count > 0 && _s.SumReciprocal > 1e-300)
|
||||
? _buffer.Count / _s.SumReciprocal
|
||||
: double.NaN;
|
||||
Last = new TValue(DateTime.MinValue, result);
|
||||
_ps = _s;
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
private double GetValidValue(double input)
|
||||
{
|
||||
if (double.IsFinite(input) && input > 0)
|
||||
{
|
||||
_s.LastValidValue = input;
|
||||
return input;
|
||||
}
|
||||
return _s.LastValidValue;
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public override TValue Update(TValue input, bool isNew = true)
|
||||
{
|
||||
if (isNew)
|
||||
{
|
||||
_ps = _s;
|
||||
|
||||
double val = GetValidValue(input.Value);
|
||||
double reciprocal = 1.0 / val;
|
||||
|
||||
if (_buffer.Count == _buffer.Capacity)
|
||||
{
|
||||
KahanSubtract(1.0 / _buffer.Oldest);
|
||||
}
|
||||
|
||||
_buffer.Add(val);
|
||||
KahanAdd(reciprocal);
|
||||
|
||||
_s.TickCount++;
|
||||
if (_buffer.IsFull && _s.TickCount >= ResyncInterval)
|
||||
{
|
||||
_s.TickCount = 0;
|
||||
RecalculateSumReciprocal();
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
_s = _ps;
|
||||
_buffer.Snapshot();
|
||||
_buffer.Restore();
|
||||
|
||||
double val = GetValidValue(input.Value);
|
||||
|
||||
if (_buffer.Count > 0)
|
||||
{
|
||||
_buffer.UpdateNewest(val);
|
||||
RecalculateSumReciprocal();
|
||||
}
|
||||
else
|
||||
{
|
||||
_buffer.Add(val);
|
||||
KahanAdd(1.0 / val);
|
||||
}
|
||||
}
|
||||
|
||||
double result = (_buffer.Count > 0 && _s.SumReciprocal > 1e-300)
|
||||
? _buffer.Count / _s.SumReciprocal
|
||||
: double.NaN;
|
||||
Last = new TValue(input.Time, result);
|
||||
PubEvent(Last, isNew);
|
||||
return Last;
|
||||
}
|
||||
|
||||
public override TSeries Update(TSeries source)
|
||||
{
|
||||
if (source.Count == 0)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
int len = source.Count;
|
||||
var t = new List<long>(len);
|
||||
var v = new List<double>(len);
|
||||
CollectionsMarshal.SetCount(t, len);
|
||||
CollectionsMarshal.SetCount(v, len);
|
||||
|
||||
var tSpan = CollectionsMarshal.AsSpan(t);
|
||||
var vSpan = CollectionsMarshal.AsSpan(v);
|
||||
|
||||
Batch(source.Values, vSpan, _period);
|
||||
source.Times.CopyTo(tSpan);
|
||||
|
||||
Prime(source.Values);
|
||||
|
||||
Last = new TValue(tSpan[len - 1], vSpan[len - 1]);
|
||||
return new TSeries(t, v);
|
||||
}
|
||||
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
// Mode A: Batch (Stateless)
|
||||
/////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
public static TSeries Batch(TSeries source, int period)
|
||||
{
|
||||
var h = new Harmean(period);
|
||||
return h.Update(source);
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public static void Batch(ReadOnlySpan<double> source, Span<double> output, int period)
|
||||
{
|
||||
if (source.Length != output.Length)
|
||||
{
|
||||
throw new ArgumentException("Source and output must have the same length", nameof(output));
|
||||
}
|
||||
if (period <= 0)
|
||||
{
|
||||
throw new ArgumentException("Period must be greater than 0", nameof(period));
|
||||
}
|
||||
|
||||
int len = source.Length;
|
||||
if (len == 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
// Use simple sliding-window reciprocal sum for batch
|
||||
double sumReciprocal = 0;
|
||||
double lastValid = double.NaN;
|
||||
int count = 0;
|
||||
|
||||
// Seed lastValid
|
||||
for (int k = 0; k < len; k++)
|
||||
{
|
||||
if (double.IsFinite(source[k]) && source[k] > 0)
|
||||
{
|
||||
lastValid = source[k];
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
const int StackallocThreshold = 256;
|
||||
double[]? rented = null;
|
||||
scoped Span<double> ring;
|
||||
if (period <= StackallocThreshold)
|
||||
{
|
||||
ring = stackalloc double[period];
|
||||
}
|
||||
else
|
||||
{
|
||||
rented = ArrayPool<double>.Shared.Rent(period);
|
||||
ring = rented.AsSpan(0, period);
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
int head = 0;
|
||||
ring.Fill(0);
|
||||
|
||||
for (int i = 0; i < len; i++)
|
||||
{
|
||||
double val = source[i];
|
||||
if (double.IsFinite(val) && val > 0)
|
||||
{
|
||||
lastValid = val;
|
||||
}
|
||||
else
|
||||
{
|
||||
val = lastValid;
|
||||
}
|
||||
|
||||
double reciprocal = 1.0 / val;
|
||||
|
||||
if (count == period)
|
||||
{
|
||||
sumReciprocal -= ring[head];
|
||||
}
|
||||
else
|
||||
{
|
||||
count++;
|
||||
}
|
||||
|
||||
ring[head] = reciprocal;
|
||||
sumReciprocal += reciprocal;
|
||||
head = (head + 1) % period;
|
||||
|
||||
output[i] = (sumReciprocal > 1e-300) ? count / sumReciprocal : double.NaN;
|
||||
}
|
||||
}
|
||||
finally
|
||||
{
|
||||
if (rented != null)
|
||||
{
|
||||
ArrayPool<double>.Shared.Return(rented);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public static (TSeries Results, Harmean Indicator) Calculate(TSeries source, int period)
|
||||
{
|
||||
var h = new Harmean(period);
|
||||
TSeries results = h.Update(source);
|
||||
return (results, h);
|
||||
}
|
||||
|
||||
public override void Reset()
|
||||
{
|
||||
_buffer.Clear();
|
||||
_s = default;
|
||||
_ps = default;
|
||||
Last = default;
|
||||
}
|
||||
|
||||
protected override void Dispose(bool disposing)
|
||||
{
|
||||
if (!_disposed)
|
||||
{
|
||||
if (disposing && _source != null)
|
||||
{
|
||||
_source.Pub -= _handler;
|
||||
}
|
||||
_disposed = true;
|
||||
}
|
||||
base.Dispose(disposing);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user