https://github.com/duster-amigos/hmm_cpp
Complete C++ implementation of Hidden Markov Models with modern C++17 and Eigen
https://github.com/duster-amigos/hmm_cpp
cpp cpp17 eigen hidden-markov-models hmm machine-learning
Last synced: 2 days ago
JSON representation
Complete C++ implementation of Hidden Markov Models with modern C++17 and Eigen
- Host: GitHub
- URL: https://github.com/duster-amigos/hmm_cpp
- Owner: duster-amigos
- License: mit
- Created: 2025-07-11T19:50:48.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-07-11T20:03:28.000Z (3 months ago)
- Last Synced: 2025-09-05T09:26:03.168Z (about 1 month ago)
- Topics: cpp, cpp17, eigen, hidden-markov-models, hmm, machine-learning
- Language: C++
- Homepage:
- Size: 152 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# hmm_cpp - Complete Hidden Markov Model Library
A complete C++ implementation of the Python hmmlearn library, featuring modern C++17, Eigen for linear algebra, and comprehensive HMM algorithms.
## Overview
This library provides a complete implementation of Hidden Markov Models (HMMs) with various emission models:
- **GaussianHMM**: HMM with Gaussian emission distributions
- **MultinomialHMM**: HMM with discrete/multinomial emissions
- **GMMHMM**: HMM with Gaussian Mixture Model emissions
- **GaussianMixture**: Standalone Gaussian Mixture Models
## Architecture
```
hmm_c++/
├── include/ # Header files
│ ├── types.hpp # Common type definitions
│ ├── hmm/ # HMM class headers
│ │ ├── base_hmm.hpp # Base HMM class
│ │ ├── gaussian_hmm.hpp # Gaussian HMM
│ │ ├── multinomial_hmm.hpp # Multinomial HMM
│ │ └── gmm_hmm.hpp # GMM HMM
│ ├── models/ # Model headers
│ │ └── gaussian_mixture.hpp # Gaussian Mixture Model
│ └── algorithms/ # Algorithm headers
│ ├── baum_welch.hpp # EM training algorithm
│ ├── viterbi.hpp # Viterbi algorithm
│ └── forward_backward.hpp # Forward-Backward algorithm
├── src/ # Source files
│ ├── hmm/ # HMM implementations
│ │ ├── base_hmm.cpp # Base HMM implementation
│ │ ├── gaussian_hmm.cpp # Gaussian HMM implementation
│ │ ├── multinomial_hmm.cpp # Multinomial HMM implementation
│ │ └── gmm_hmm.cpp # GMM HMM implementation
│ ├── models/ # Model implementations
│ │ └── gaussian_mixture.cpp # Gaussian Mixture implementation
│ └── algorithms/ # Algorithm implementations
│ ├── baum_welch.cpp # Baum-Welch implementation
│ ├── viterbi.cpp # Viterbi implementation
│ └── forward_backward.cpp # Forward-Backward implementation
├── examples/ # Usage examples
├── tests/ # Test files
└── CMakeLists.txt # CMake build configuration
```
## Features
### Core HMM Classes
- **BaseHMM**: Abstract base class with common HMM functionality
- **GaussianHMM**: HMM with multivariate Gaussian emissions
- **MultinomialHMM**: HMM with discrete emissions
- **GMMHMM**: HMM with Gaussian Mixture Model emissions
### Algorithms
- **Baum-Welch**: Expectation-Maximization training algorithm
- **Viterbi**: Most likely hidden state sequence
- **Forward-Backward**: State probabilities and likelihood computation
### Models
- **GaussianMixture**: Standalone Gaussian Mixture Models
- Support for different covariance types (Full, Diagonal, Spherical)
### Modern C++ Features
- C++17 standard compliance
- Smart pointers for memory management
- RAII principles
- Exception safety
- Template metaprogramming
- STL containers and algorithms
## Quick Start
### Prerequisites
- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
- Eigen3 library
- CMake 3.10+ (optional, for build system)
### Installation
1. **Install Eigen3**:
```bash
# macOS
brew install eigen
# Ubuntu/Debian
sudo apt-get install libeigen3-dev
# Windows (vcpkg)
vcpkg install eigen3
```
2. **Clone the repository**:
```bash
git clone
cd hmm_c++
```
3. **Build the library**:
```bash
# Using CMake (recommended)
mkdir build && cd build
cmake ..
make -j4
# Or compile manually
g++ -std=c++17 -I/usr/local/include -O2 src/*.cpp -leigen3 -o hmm_test
```
### Basic Usage
```cpp
#include "include/hmm/gaussian_hmm.hpp"
#include
using namespace hmmlearn_cpp;
int main() {
// Create a Gaussian HMM with 3 states and 2 features
GaussianHMM hmm(3, 2, CovarianceType::FULL);
// Generate or load your data
Matrix X(1000, 2); // Your data here
// Train the HMM
TrainingParams params;
params.max_iter = 100;
params.tol = 1e-4;
TrainingResult result = hmm.fit(X, {}, params);
// Make predictions
IntVector states = hmm.predict(X);
Matrix state_probs = hmm.predict_proba(X);
// Generate samples
Matrix samples = hmm.sample(100);
std::cout << "Training converged: " << result.converged << std::endl;
std::cout << "Final log-likelihood: " << result.final_log_likelihood << std::endl;
return 0;
}
```
## API Reference
### GaussianHMM
```cpp
class GaussianHMM : public BaseHMM {
public:
// Constructor
GaussianHMM(int n_components, int n_features,
CovarianceType covariance_type = CovarianceType::FULL,
unsigned int random_state = 42);
// Training
TrainingResult fit(const Matrix& X, const std::vector& lengths,
const TrainingParams& params);
// Prediction
IntVector predict(const Matrix& X) const;
Matrix predict_proba(const Matrix& X) const;
// Sampling
Matrix sample(int n_samples) const;
// Scoring
Scalar score(const Matrix& X) const;
// Parameter access
Vector get_startprob() const;
Matrix get_transmat() const;
Matrix get_means() const;
std::vector get_covariances() const;
};
```
### MultinomialHMM
```cpp
class MultinomialHMM : public BaseHMM {
public:
// Constructor
MultinomialHMM(int n_components, int n_features,
unsigned int random_state = 42);
// Same interface as GaussianHMM
// Emission parameters are discrete probability distributions
};
```
### GMMHMM
```cpp
class GMMHMM : public BaseHMM {
public:
// Constructor
GMMHMM(int n_components, int n_features, int n_mix,
CovarianceType covariance_type = CovarianceType::FULL,
unsigned int random_state = 42);
// Additional method to extract GMMs
std::vector get_gmms() const;
};
```
### GaussianMixture
```cpp
class GaussianMixture {
public:
// Constructor
GaussianMixture(int n_components, int n_features,
CovarianceType covariance_type = CovarianceType::FULL);
// Training
void fit(const Matrix& X);
// Prediction
Matrix predict_proba(const Matrix& X) const;
IntVector predict(const Matrix& X) const;
// Sampling
Matrix sample(int n_samples) const;
// Scoring
Scalar score(const Matrix& X) const;
Matrix score_samples(const Matrix& X) const;
};
```
## Configuration
### Training Parameters
```cpp
struct TrainingParams {
int max_iter = 100; // Maximum iterations
Scalar tol = 1e-4; // Convergence tolerance
bool verbose = false; // Verbose output
unsigned int random_state = 42; // Random seed
};
```
### Covariance Types
```cpp
enum class CovarianceType {
FULL, // Full covariance matrices
DIAGONAL, // Diagonal covariance matrices
SPHERICAL // Spherical covariance matrices
};
```
## Testing
Run the comprehensive test suite:
```bash
# Basic structure test (no Eigen required)
g++ -std=c++17 test_basic_structure.cpp -o test_basic_structure
./test_basic_structure
# Complete library test (requires Eigen)
g++ -std=c++17 -I/usr/local/include test_complete_library.cpp src/*.cpp -leigen3 -o test_complete_library
./test_complete_library
```
## Performance
The library is optimized for performance:
- **Eigen Integration**: Leverages Eigen's highly optimized linear algebra
- **Memory Efficiency**: Smart pointers and RAII for automatic memory management
- **Algorithmic Optimizations**: Efficient implementations of Baum-Welch, Viterbi, and Forward-Backward
- **SIMD Support**: Eigen provides SIMD optimizations where available
## Safety Features
- **Exception Safety**: All operations are exception-safe
- **Input Validation**: Comprehensive parameter validation
- **Memory Safety**: Smart pointers prevent memory leaks
- **Thread Safety**: Const methods are thread-safe
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Inspired by the Python hmmlearn library
- Built with Eigen for efficient linear algebra
- Uses modern C++ best practices
## Support
For questions, issues, or contributions, please open an issue on GitHub.
You can drop a mail to duster.amigos05@gmail.com if needed.
---