ark-alliance-core-math

Mathematics, Statistics, Forecasting & Time Series Analysis Library

---

Overview

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

---

Installation

``bash
npm install ark-alliance-core-math ark-alliance-core
`

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

---

Module Navigation

$3

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

---

$3

| 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

| 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 |

---

$3

| 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 |

---

$3

| 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 |

---

$3

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

---

$3

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

---

$3

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

---

$3

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

---

$3

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

---

Architecture

`mermaid
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

$3

`typescript
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
`

$3

`typescript
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

`typescript
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});
}
`

$3

`typescript
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});
`

$3

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

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

$3

`typescript
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 in frequency domain
`

$3

`typescript
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 }
`

$3

`typescript
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

$3

`bash


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
`

$3

`bash
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.

---

_{M2H.IO (c) 2025 - Ark.Alliance Eco system - Armand Richelet-Kleinberg}