nhsmm 0.0.3a0

Neural Hidden Semi-Markov Model (HSMM) implementation in PyTorch

NHSMM — (Neural) Hidden Semi-Markov Models

• Repository: NHSMM on GitHub
• Documentation: wiki
• Version: 0.0.3-alpha

---

⚠️ NHSMM is currently in alpha (v0.0.3-alpha) and provided as a proof-of-concept.
It will be enhanced for production, and the public API is subject to change prior to the first stable 1.0.0 release.

This document provides a self-contained guide to NHSMM, a modular PyTorch library that underpins the State Aware Engine (SAE). It is designed for developers, data scientists, and system integrators, enabling them to quickly understand, deploy, and extend the library across diverse application domains.

Highlights

• Combines Hidden Semi-Markov Models (HSMMs) with neural parameterization
• Supports contextual modulation of initial, transition, duration, and emission distributions
• Enables hierarchical and flexible model architectures for sequential data
• Fully PyTorch-compatible, GPU-ready, and extensible for multi-domain use

---

Overview

NHSMM provides a modular, time-aware framework for temporal sequence modeling and hidden-state inference using Hidden Semi-Markov Models (HSMMs). It explicitly models state durations and context-dependent transitions, making it suitable for non-stationary, real-world sequences.

NHSMM underpins the State Aware Engine (SAE) — a cross-domain platform for detecting hidden regimes and temporal patterns across finance, IoT, health, cybersecurity, robotics, and related domains.

The library is suitable both as a research framework and as a foundation for production-oriented systems, with a strong emphasis on modularity, extensibility, and accelerator-friendly execution.

Key deployment modes enabled by SAE & NHSMM (planned):

• Cloud-first SaaS — scalable, multi-tenant sequence analytics
• On-prem / Edge — low-latency, privacy-sensitive inference
• Accelerator-ready — GPU, TPU, and future hardware backends for high-throughput temporal modeling

---

🚀 Key Features

• Contextual HSMM — external covariates dynamically modulate initial, transition, duration, and emission distributions, enabling non-stationary and time-aware sequence modeling. Supports continuous or discrete context inputs.
• Duration Models — explicit discrete duration distributions per state, optionally context-modulated, to capture state dwell-times accurately. Supports both short- and long-term temporal dependencies.
• Emission Models — Gaussian, Student-t, or discrete outputs (e.g., Multinomial/Bernoulli), fully differentiable and context-aware, allowing neural adaptation to evolving observation patterns.
• Transition Models — learnable, covariate-aware transitions with gating and temperature scaling to control stochasticity and enforce smooth or sharp transitions. Supports low-rank factorization for large state spaces.
• Hybrid HSMM-HMM Inference — forward-backward and Viterbi algorithms adapted for neural-parameterized latent states, providing exact or approximate sequence likelihoods and most probable paths.
• Subclassable Distributions — Initial, Duration, Transition, and Emission modules inherit from PyTorch Distribution, allowing custom probabilistic modules or integration of specialized neural layers.
• EM-style Updates & Initialization — supports maximum likelihood, differentiable updates, and temperature annealing for stable and adaptive training of neural-HSMM parameters.
• Neural Context Encoders — optional CNN, LSTM, or hybrid encoders to inject time-varying covariates into emission, duration, and transition probabilities.
• GPU-Ready Implementation — fully batched operations for fast training and inference on modern accelerators (CUDA-ready).
• Multi-Domain Usage — flexible for finance (market regime detection), IoT (predictive maintenance), robotics (behavior monitoring), wearable health (activity and state detection), cybersecurity (anomaly detection), and other sequential applications.
• Extensible Architecture — modular foundation for SAE adapters, API integration, multi-domain extensions, and future research projects in sequence modeling.
• Robust Initialization & Adaptivity — supports spread or random initialization, learning rate adaptation, and state-wise parameter modulation for stable convergence across domains.
• Hybrid Update Modes — allows neural gradient-based updates and closed-form EM-style updates, optionally combined in alternating schemes for best performance.

---

📌 Milestones

Stage	Status	Notes
Proof of Concept	✅ Done	Alpha release (0.0.2-alpha)
Enhancement	⚠️ Todo	Improve performance, stability, and extend API
Testing	⚠️ Todo	Rigorous validation, benchmarking, and QA
Production Release	⚠️ Todo	Full 1.0.0 release with documentation and stable API

---

Support This Project

Development and research around NHSMM are supported via GitHub Sponsors, Patreon, Medium, and Open Collective.

See FUNDING.md for details on how to contribute and what support enables.

---

📦 Installation

From PyPI (now also available)

pip install nhsmm;

From Source (Recommended for Development)

git clone https://github.com/awa-si/NHSMM.git;

cd NHSMM;
pip install -e .;

---

🧩 Package Structure

nhsmm/
├── context.py
├── constants.py
├── constraints.py
├── convergence.py
├── data.py
├── seed.py
├── models/
│   ├── base.py
│   └── __init__.py
├── distributions/
│   ├── default.py
│   └── __init__.py
├── __version__.py
└── __init__.py

---

🧠 Usage Example — Market Regime Detection (HSMM)

Please also see: State Occupancy & Duration/Transition Diagnostics

This example demonstrates Hidden Semi-Markov regime detection on OHLCV-style time-series data using NHSMM.
The same pattern applies to IoT signals, health data, robotics telemetry, or cybersecurity logs.

---

1. Prepare Data

import torch
import numpy as np
from sklearn.preprocessing import StandardScaler

from nhsmm.models import HSMM
from nhsmm.context import CNN_LSTM_Encoder
from nhsmm.constants import DTYPE

# Synthetic example: [T, F] = time × features
T, F = 512, 5
X = np.random.randn(T, F)

# Scale features
X = StandardScaler().fit_transform(X)
X = torch.tensor(X, dtype=DTYPE)

2. Build Context Encoder (Optional but Recommended)

Context enables non-stationary transitions and durations.

encoder = CNN_LSTM_Encoder(
    n_features=F,
    cnn_channels=4,
    hidden_dim=64,
)

3. Initialize Neural HSMM

model = HSMM(
    encoder=encoder,
    n_states=3,              # e.g. range / bull / bear
    n_features=F,
    emission_type="gaussian",
    max_duration=30,
    seed=0,
)

4. Train with EM-Style Optimization

model.fit(
    X,
    n_init=3,
    max_iter=10,
    tol=1e-4,
    verbose=True,
)

5. Decode Hidden States (Viterbi) / Inspect

states = model.decode(X, algorithm="viterbi")

print("Decoded states shape:", states.shape)
print("Unique states:", torch.unique(states))

# Inspect Learned Durations
with torch.no_grad():
    durations = torch.exp(model.duration_module.log_matrix())
    durations = durations.mean(dim=(0, 1))  # [K, D]

for i, row in enumerate(durations):
    mean_dur = (torch.arange(1, len(row) + 1) * row).sum()
    print(f"State {i}: mean duration ≈ {mean_dur:.2f}")

# Log-Likelihood Scoring
log_likelihood = model.score(X)
print("Sequence log-likelihood:", log_likelihood.item())

---

🔍 Conceptual Flow Diagram

┌─────────────────────────────┐
│      External Input         │  ← covariates, features, embeddings
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Neural Initial State Module│  ← context-modulated initial probabilities π
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Neural Transition Module   │  ← context-gated, temperature-scaled transitions A
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Neural Duration Module     │  ← context-aware duration probabilities D
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│      Emission Module        │  ← context-modulated observation likelihoods
│   (Gaussian / Student-t / …)│
└─────────────┬───────────────┘
              │
              ▼
      ┌─────────────┐
      │ Posterior   │  ← gamma, xi, eta (inference)
      └─────────────┘
              ▲
              │
   ┌──────────┴──────────┐
   │ Backprop / EM Update │
   └─────────────────────┘

---

⚙️ Development

NHSMM is actively developed and contributions are welcome! Whether you want to report bugs, suggest features, or improve documentation, your input helps make the library stronger and more versatile.

For planned features and research directions, see the project roadmap in the GitHub issues and discussions.

# Fork or clone the repository
git clone https://github.com/awa-si/nhsmm.git
cd nhsmm

# Install in development mode with optional dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Code formatting & linting
black nhsmm
ruff check nhsmm

---

🌐 Multi-Domain Applicability

The State Aware Engine (SAE), powered by NHSMM, is designed for flexible, context-aware temporal modeling across diverse domains:

• Security & Cyber-Physical Systems — Detect hidden operational or network states, anomalies, and potential threats in real time. Supports log analysis, sensor fusion, and adaptive monitoring.
• Finance & Trading — Identify market regimes, model adaptive strategies, and forecast state transitions for portfolios, trading signals, or risk scenarios. Captures both short-term fluctuations and long-term trends.
• IoT & Industrial Systems — Monitor machines, sensors, and processes to predict regime changes, enabling predictive maintenance, fault detection, and operational optimization.
• Health & Wearables — Track activity, physiological signals, and state transitions for personalized health monitoring, anomaly detection, or chronic condition management. Supports multimodal time-series fusion.
• Robotics & Motion Analytics — Observe robotic behaviors, detect unexpected transitions, optimize task performance, and ensure safe human-robot interaction.
• Telecommunications & Network Analytics — Monitor network traffic patterns, detect latent congestion states, and predict temporal anomalies for automated response.
• Energy & Smart Grids — Track operational states of energy systems, detect load or failure regimes, and optimize resource allocation over time.
• Cross-Domain Research & AI Applications — Serve as a foundation for temporal sequence modeling, hybrid HSMM-HMM experiments, or research in neural probabilistic models.

---

🧾 License

This project is released under the Apache License 2.0 © 2024 AWA.SI.
For full license terms and conditions, please see the LICENSE file. If you use NHSMM in academic work, please cite the repository.

---