Overview

ark-alliance-core-math provides validated mathematical and statistical tools for quantitative analysis. All modules follow Clean Architecture principles with Result<T> return types from ark-alliance-core.

Installation

npm install ark-alliance-core-math ark-alliance-core

Note: ark-alliance-core is a peer dependency and must be installed.

Module Navigation

1. Primitives & Foundations

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Primitives | Mathematical primitives | Complex, toComplexArray, toRealArray | 📖 README |

2. Statistics

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Descriptive | Basic statistics | MathOperations (mean, variance, stdDev, correlation) | 📖 README | | Regression | Linear regression | LinearRegression, RegressionResult | 📖 README | | Stationarity | Time series stationarity | StationarityTester, VarianceRatioTest | 📖 README |

3. Indicators & Technical Analysis

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Moving Averages | SMA, EMA calculators | SMACalculator, EMACalculator, EMAResult | 📖 README | | Trend Analysis | Hurst exponent (R/S, DFA) | HurstExponentCalculator, HurstMethod, HurstResult | 📖 README |

4. Volatility & Risk

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Volatility | GARCH modeling | GARCHModel, GARCHParams, GARCHForecast | 📖 README | | Risk Metrics | Performance metrics | RiskMetrics, ComprehensiveMetrics, Trade | 📖 README | | Regime Detection | Market state classification | RegimeDetector, MarketRegime, RegimeIndicators | 📖 README |

5. Signal Processing

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | FFT (Fourier) | Frequency analysis | FFT, forward(), inverse() | 📖 README | | DCT | Discrete cosine transform | DCT, dct(), idct() | 📖 README | | Wavelets | Multi-resolution analysis | HaarDWT, decompose(), reconstruct() | 📖 README |

6. Time Series

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Time Series | ARIMA, Kalman filtering | difference, acf, pacf, ScalarKalman | 📖 README |

7. Sequences & Optimization

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Fibonacci | Sequences & golden ratio | fibonacci, goldenSectionMinimize, GOLDEN_RATIO | 📖 README |

8. Machine Learning

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Positional Encodings | Transformer encodings | generatePositionalEncoding, applyRoPE | 📖 README |

9. Linear Algebra

| Module | Description | Key Exports | Documentation | |--------|-------------|-------------|---------------| | Linear Algebra | Matrix operations | MatrixOperations, LinearEquationSolver, DecompositionHelper | 📖 README |

Application Services

| Service | Description | |---------|-------------| | ForecastEngineService | Unified analysis pipeline orchestrating stationarity, autocorrelation, Hurst, GARCH, and regime detection |

Architecture

graph TB
    subgraph "Application Layer"
        FES[ForecastEngineService]
    end
    
    subgraph "Domain Layer"
        subgraph "Statistics"
            DESC[Descriptive]
            REG[Regression]
            STAT[Stationarity]
        end
        
        subgraph "Indicators"
            MA[Moving Averages]
            HE[Hurst Exponent]
        end
        
        subgraph "Volatility & Risk"
            GM[GARCH]
            RM[Risk Metrics]
            RD[Regime]
        end
        
        subgraph "Signal Processing"
            FFT[FFT]
            DCT[DCT]
            DWT[Wavelets]
        end
        
        subgraph "Time Series"
            ARIMA[Differencing]
            KF[Kalman Filter]
        end
        
        subgraph "Foundations"
            PRIM[Primitives - Complex]
            LA[Linear Algebra]
            SEQ[Fibonacci]
        end
    end
    
    FES --> STAT
    FES --> HE
    FES --> GM
    FES --> RM
    FES --> RD
    
    FFT --> PRIM
    HE --> DESC
    GM --> DESC

Quick Start Examples

1. Descriptive Statistics

import { MathOperations } from '@ark.alliance/core-math';

const ops = new MathOperations();
const data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

const stats = ops.describe(data);
console.log(`Mean: ${stats.data.mean}`);           // 5.5
console.log(`StdDev: ${stats.data.standardDeviation}`); // 3.03

2. Complex Numbers (for FFT)

import { Complex } from '@ark.alliance/core-math';

const z1 = new Complex(3, 4);  // 3 + 4i
console.log(z1.abs());         // 5 (magnitude)

const z2 = Complex.expi(Math.PI / 4);  // e^(iπ/4)
const product = z1.mul(z2);

3. Hurst Exponent

import { HurstExponentCalculator, HurstMethod } from '@ark.alliance/core-math';

const calculator = new HurstExponentCalculator();
const result = calculator.calculate(prices, { method: HurstMethod.DFA });

if (result.isSuccess) {
    console.log(`H = ${result.data.exponent}`);
    console.log(`Behavior: ${result.data.interpretation.behavior}`);
}

4. Moving Averages

import { EMACalculator, SMACalculator } from '@ark.alliance/core-math';

const ema = new EMACalculator();
const result = ema.calculate(prices, 20);  // 20-period EMA
console.log(`EMA: ${result.data.value}`);

5. GARCH Volatility

import { GARCHModel } from '@ark.alliance/core-math';

const model = new GARCHModel();
const params = model.estimateParameters(returns);
const forecast = model.forecast(params.data, 5);

6. FFT

import { FFT } from '@ark.alliance/core-math';

const fft = new FFT();
const signal = [1, 0, -1, 0, 1, 0, -1, 0];
const spectrum = fft.forward(signal);
// Result<Complex[]> in frequency domain

7. Fibonacci & Golden Section

import { fibonacci, goldenSectionMinimize } from '@ark.alliance/core-math';

const F100 = fibonacci(100n);
// F100.data = 354224848179261915075n

const min = goldenSectionMinimize(x => (x - 2) ** 2, 0, 5);
// min.data = { x: 2.0, fx: 0.0 }

8. ForecastEngineService (Full Pipeline)

import { ForecastEngineService } from '@ark.alliance/core-math';

const engine = new ForecastEngineService({ serviceName: 'Analysis' });
await engine.startAsync();

const result = await engine.analyze(prices);
if (result.isSuccess) {
    console.log(`Hurst: ${result.data.hurst?.exponent}`);
    console.log(`Regime: ${result.data.regime?.type}`);
    console.log(`Stationary: ${result.data.stationarity?.isStationary}`);
}

await engine.stopAsync();

Key Takeaways

1. Transform prices to returns before regression analysis
2. Test for autocorrelation - DW < 1.5 inflates R²
3. Use Hurst for trend/mean-reversion detection
4. Adapt to market regime - strategies fail in wrong regime
5. Use risk-adjusted metrics - accuracy alone is insufficient

Development

Building from Source

# Clone repository
git clone https://github.com/M2H-Machine-to-Human-Race/Ark.Alliance.Core.git
cd Ark.Alliance.Core

# Build Core first (peer dependency)
cd Ark.Alliance.TypeScript.Core
npm install
npm run build

# Build Math library
cd ../Ark.Alliance.TypeScript.Core.Math
npm install
npm run build

Running Tests

cd Ark.Alliance.TypeScript.Core.Math.Test
npm install
npm test

References

| Topic | Source | |-------|--------| | Hurst Exponent | Wikipedia | | GARCH | Investopedia | | FFT | Wikipedia | | Kalman Filter | kalmanfilter.net | | Golden Ratio | OEIS A000045 |

License

MIT License - see LICENSE for details.