indicator-series

Series indicator development

File structure

• Implementation: src/{category}/{Indicator}/{Indicator}.StaticSeries.cs
• Test: tests/indicators/{category}/{Indicator}/{Indicator}.StaticSeries.Tests.cs
• Catalog: src/{category}/{Indicator}/{Indicator}.Catalog.cs
• Categories: a-d, e-k, m-r, s-z (alphabetical)

Performance optimization

Array allocation pattern (recommended for new implementations):

TResult[] results = new TResult[length];
// ... assign results[i] = new TResult(...);
return new List<TResult>(results);  // NOT results.ToList()

When to use: Indicators with predictable result counts show ~2x improvement (Issue #1259)

When NOT to use: Benchmark first. Some indicators (ADL) remain faster with List.Add()

Conversion strategy:

1. Benchmark existing List-based implementation
2. Convert to array pattern
3. Benchmark again
4. Revert if no improvement or regression

Required implementation

Beyond the .StaticSeries.cs file, ensure:

• Catalog registration: Create src/**/{Indicator}.Catalog.cs and register in Catalog.Listings.cs
• Unit tests: Create tests/indicators/**/{Indicator}.StaticSeries.Tests.cs
  • Inherit from StaticSeriesTestBase
  • Include [TestCategory("Regression")] for baseline validation
  • Verify against manually calculated reference values
• Performance benchmark: Add to #file:../../../tools/performance/Perf.Series.cs
• Public documentation: Update docs/indicators/{Indicator}.md
• Regression tests: Add to tests/indicators/**/{Indicator}.Regression.Tests.cs
• Migration guide: Update docs/migration.md for notable and breaking changes from v2

Precision testing patterns

• Store reference data separately: Create {Indicator}.Data.cs files with arrays of expected values at maximum precision
• Excel manual calculations: Export at highest precision available (~14 decimal places for default.csv values ~200)
• Baseline regression validation: Compare full dataset against reference arrays using Money10-Money12 precision
• Spot check assertions: Use Money4 for individual sample value readability (sanity checks, not proofs)
• Longer datasets: May require lower precision (e.g., Money10 for 15k quotes) due to accumulated floating-point error
• Document degradation: When precision must be lowered, explain why in test comments

Examples

• Simple single-value: src/s-z/Sma/Sma.StaticSeries.cs
• Exponential smoothing: src/e-k/Ema/Ema.StaticSeries.cs
• Complex multi-stage: src/a-d/Adx/Adx.StaticSeries.cs
• Multi-line results: src/a-d/Alligator/Alligator.StaticSeries.cs

See references/decision-tree.md for result interface selection guidance.

Constitutional constraints

• Series is truth: All other styles (BufferList, StreamHub) MUST match Series results exactly
• Verify against authoritative sources: NEVER trust other libraries—use reference publications only
• Algebraic stability: Prefer boundary detection over clamping
• Real-world testing: Synthetic boundary data may miss precision edge cases
• Fix formulas, not symptoms: When all styles fail identically, fix the core algorithm

NEVER modify formulas without verification against authoritative mathematical references. See src/AGENTS.md for formula protection rules.

Common pitfalls

• Off-by-one windows when calculating lookback or warmup periods
• Precision loss in chained calculations (favor double for performance)
• Performance regressions from unnecessary allocations or LINQ
• Documentation drift between code comments, XML docs, and published docs site
• Improper NaN handling (do not reject NaN inputs; guard against division by zero)

Last updated: January 25, 2026