{"id":29538706,"url":"https://github.com/duster-amigos/hmm_cpp","last_synced_at":"2025-10-09T00:37:44.520Z","repository":{"id":304240942,"uuid":"1018207102","full_name":"duster-amigos/hmm_cpp","owner":"duster-amigos","description":"Complete C++ implementation of Hidden Markov Models with modern C++17 and Eigen","archived":false,"fork":false,"pushed_at":"2025-07-11T20:03:28.000Z","size":156,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-05T09:26:03.168Z","etag":null,"topics":["cpp","cpp17","eigen","hidden-markov-models","hmm","machine-learning"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/duster-amigos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T19:50:48.000Z","updated_at":"2025-07-11T20:02:12.000Z","dependencies_parsed_at":"2025-07-13T02:46:26.688Z","dependency_job_id":null,"html_url":"https://github.com/duster-amigos/hmm_cpp","commit_stats":null,"previous_names":["duster-amigos/hmm_cpp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/duster-amigos/hmm_cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duster-amigos%2Fhmm_cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duster-amigos%2Fhmm_cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duster-amigos%2Fhmm_cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duster-amigos%2Fhmm_cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duster-amigos","download_url":"https://codeload.github.com/duster-amigos/hmm_cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duster-amigos%2Fhmm_cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000639,"owners_count":26082879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","cpp17","eigen","hidden-markov-models","hmm","machine-learning"],"created_at":"2025-07-17T05:10:06.550Z","updated_at":"2025-10-09T00:37:44.499Z","avatar_url":"https://github.com/duster-amigos.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hmm_cpp - Complete Hidden Markov Model Library\n\nA complete C++ implementation of the Python hmmlearn library, featuring modern C++17, Eigen for linear algebra, and comprehensive HMM algorithms.\n\n## Overview\n\nThis library provides a complete implementation of Hidden Markov Models (HMMs) with various emission models:\n\n- **GaussianHMM**: HMM with Gaussian emission distributions\n- **MultinomialHMM**: HMM with discrete/multinomial emissions  \n- **GMMHMM**: HMM with Gaussian Mixture Model emissions\n- **GaussianMixture**: Standalone Gaussian Mixture Models\n\n## Architecture\n\n```\nhmm_c++/\n├── include/                     # Header files\n│   ├── types.hpp                # Common type definitions\n│   ├── hmm/                     # HMM class headers\n│   │   ├── base_hmm.hpp         # Base HMM class\n│   │   ├── gaussian_hmm.hpp     # Gaussian HMM\n│   │   ├── multinomial_hmm.hpp  # Multinomial HMM\n│   │   └── gmm_hmm.hpp          # GMM HMM\n│   ├── models/                  # Model headers\n│   │   └── gaussian_mixture.hpp # Gaussian Mixture Model\n│   └── algorithms/              # Algorithm headers\n│       ├── baum_welch.hpp       # EM training algorithm\n│       ├── viterbi.hpp          # Viterbi algorithm\n│       └── forward_backward.hpp # Forward-Backward algorithm\n├── src/                         # Source files\n│   ├── hmm/                     # HMM implementations\n│   │   ├── base_hmm.cpp         # Base HMM implementation\n│   │   ├── gaussian_hmm.cpp     # Gaussian HMM implementation\n│   │   ├── multinomial_hmm.cpp  # Multinomial HMM implementation\n│   │   └── gmm_hmm.cpp          # GMM HMM implementation\n│   ├── models/                  # Model implementations\n│   │   └── gaussian_mixture.cpp # Gaussian Mixture implementation\n│   └── algorithms/              # Algorithm implementations\n│       ├── baum_welch.cpp       # Baum-Welch implementation\n│       ├── viterbi.cpp          # Viterbi implementation\n│       └── forward_backward.cpp # Forward-Backward implementation\n├── examples/                    # Usage examples\n├── tests/                       # Test files\n└── CMakeLists.txt               # CMake build configuration\n```\n\n## Features\n\n### Core HMM Classes\n- **BaseHMM**: Abstract base class with common HMM functionality\n- **GaussianHMM**: HMM with multivariate Gaussian emissions\n- **MultinomialHMM**: HMM with discrete emissions\n- **GMMHMM**: HMM with Gaussian Mixture Model emissions\n\n### Algorithms\n- **Baum-Welch**: Expectation-Maximization training algorithm\n- **Viterbi**: Most likely hidden state sequence\n- **Forward-Backward**: State probabilities and likelihood computation\n\n### Models\n- **GaussianMixture**: Standalone Gaussian Mixture Models\n- Support for different covariance types (Full, Diagonal, Spherical)\n\n### Modern C++ Features\n- C++17 standard compliance\n- Smart pointers for memory management\n- RAII principles\n- Exception safety\n- Template metaprogramming\n- STL containers and algorithms\n\n## Quick Start\n\n### Prerequisites\n- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)\n- Eigen3 library\n- CMake 3.10+ (optional, for build system)\n\n### Installation\n\n1. **Install Eigen3**:\n   ```bash\n   # macOS\n   brew install eigen\n   \n   # Ubuntu/Debian\n   sudo apt-get install libeigen3-dev\n   \n   # Windows (vcpkg)\n   vcpkg install eigen3\n   ```\n\n2. **Clone the repository**:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd hmm_c++\n   ```\n\n3. **Build the library**:\n   ```bash\n   # Using CMake (recommended)\n   mkdir build \u0026\u0026 cd build\n   cmake ..\n   make -j4\n   \n   # Or compile manually\n   g++ -std=c++17 -I/usr/local/include -O2 src/*.cpp -leigen3 -o hmm_test\n   ```\n\n### Basic Usage\n\n```cpp\n#include \"include/hmm/gaussian_hmm.hpp\"\n#include \u003ciostream\u003e\n\nusing namespace hmmlearn_cpp;\n\nint main() {\n    // Create a Gaussian HMM with 3 states and 2 features\n    GaussianHMM hmm(3, 2, CovarianceType::FULL);\n    \n    // Generate or load your data\n    Matrix X(1000, 2); // Your data here\n    \n    // Train the HMM\n    TrainingParams params;\n    params.max_iter = 100;\n    params.tol = 1e-4;\n    \n    TrainingResult result = hmm.fit(X, {}, params);\n    \n    // Make predictions\n    IntVector states = hmm.predict(X);\n    Matrix state_probs = hmm.predict_proba(X);\n    \n    // Generate samples\n    Matrix samples = hmm.sample(100);\n    \n    std::cout \u003c\u003c \"Training converged: \" \u003c\u003c result.converged \u003c\u003c std::endl;\n    std::cout \u003c\u003c \"Final log-likelihood: \" \u003c\u003c result.final_log_likelihood \u003c\u003c std::endl;\n    \n    return 0;\n}\n```\n\n## API Reference\n\n### GaussianHMM\n\n```cpp\nclass GaussianHMM : public BaseHMM {\npublic:\n    // Constructor\n    GaussianHMM(int n_components, int n_features, \n                CovarianceType covariance_type = CovarianceType::FULL,\n                unsigned int random_state = 42);\n    \n    // Training\n    TrainingResult fit(const Matrix\u0026 X, const std::vector\u003cint\u003e\u0026 lengths, \n                      const TrainingParams\u0026 params);\n    \n    // Prediction\n    IntVector predict(const Matrix\u0026 X) const;\n    Matrix predict_proba(const Matrix\u0026 X) const;\n    \n    // Sampling\n    Matrix sample(int n_samples) const;\n    \n    // Scoring\n    Scalar score(const Matrix\u0026 X) const;\n    \n    // Parameter access\n    Vector get_startprob() const;\n    Matrix get_transmat() const;\n    Matrix get_means() const;\n    std::vector\u003cMatrix\u003e get_covariances() const;\n};\n```\n\n### MultinomialHMM\n\n```cpp\nclass MultinomialHMM : public BaseHMM {\npublic:\n    // Constructor\n    MultinomialHMM(int n_components, int n_features, \n                   unsigned int random_state = 42);\n    \n    // Same interface as GaussianHMM\n    // Emission parameters are discrete probability distributions\n};\n```\n\n### GMMHMM\n\n```cpp\nclass GMMHMM : public BaseHMM {\npublic:\n    // Constructor\n    GMMHMM(int n_components, int n_features, int n_mix,\n           CovarianceType covariance_type = CovarianceType::FULL,\n           unsigned int random_state = 42);\n    \n    // Additional method to extract GMMs\n    std::vector\u003cGaussianMixture\u003e get_gmms() const;\n};\n```\n\n### GaussianMixture\n\n```cpp\nclass GaussianMixture {\npublic:\n    // Constructor\n    GaussianMixture(int n_components, int n_features,\n                    CovarianceType covariance_type = CovarianceType::FULL);\n    \n    // Training\n    void fit(const Matrix\u0026 X);\n    \n    // Prediction\n    Matrix predict_proba(const Matrix\u0026 X) const;\n    IntVector predict(const Matrix\u0026 X) const;\n    \n    // Sampling\n    Matrix sample(int n_samples) const;\n    \n    // Scoring\n    Scalar score(const Matrix\u0026 X) const;\n    Matrix score_samples(const Matrix\u0026 X) const;\n};\n```\n\n## Configuration\n\n### Training Parameters\n\n```cpp\nstruct TrainingParams {\n    int max_iter = 100;           // Maximum iterations\n    Scalar tol = 1e-4;           // Convergence tolerance\n    bool verbose = false;         // Verbose output\n    unsigned int random_state = 42; // Random seed\n};\n```\n\n### Covariance Types\n\n```cpp\nenum class CovarianceType {\n    FULL,      // Full covariance matrices\n    DIAGONAL,  // Diagonal covariance matrices\n    SPHERICAL  // Spherical covariance matrices\n};\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Basic structure test (no Eigen required)\ng++ -std=c++17 test_basic_structure.cpp -o test_basic_structure\n./test_basic_structure\n\n# Complete library test (requires Eigen)\ng++ -std=c++17 -I/usr/local/include test_complete_library.cpp src/*.cpp -leigen3 -o test_complete_library\n./test_complete_library\n```\n\n## Performance\n\nThe library is optimized for performance:\n\n- **Eigen Integration**: Leverages Eigen's highly optimized linear algebra\n- **Memory Efficiency**: Smart pointers and RAII for automatic memory management\n- **Algorithmic Optimizations**: Efficient implementations of Baum-Welch, Viterbi, and Forward-Backward\n- **SIMD Support**: Eigen provides SIMD optimizations where available\n\n## Safety Features\n\n- **Exception Safety**: All operations are exception-safe\n- **Input Validation**: Comprehensive parameter validation\n- **Memory Safety**: Smart pointers prevent memory leaks\n- **Thread Safety**: Const methods are thread-safe\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Inspired by the Python hmmlearn library\n- Built with Eigen for efficient linear algebra\n- Uses modern C++ best practices\n\n## Support\n\nFor questions, issues, or contributions, please open an issue on GitHub.\nYou can drop a mail to duster.amigos05@gmail.com if needed.\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduster-amigos%2Fhmm_cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduster-amigos%2Fhmm_cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduster-amigos%2Fhmm_cpp/lists"}