{"id":23375748,"url":"https://github.com/franckalbinet/teuvo","last_synced_at":"2026-02-09T06:05:33.995Z","repository":{"id":268777555,"uuid":"904573100","full_name":"franckalbinet/teuvo","owner":"franckalbinet","description":"Self-Organising Map implemented as Literate Programming","archived":false,"fork":false,"pushed_at":"2025-01-19T16:18:21.000Z","size":2982,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-25T01:42:58.603Z","etag":null,"topics":["data-visualization","dimensionality-reduction","neural-network"],"latest_commit_sha":null,"homepage":"https://fr.anckalbi.net/teuvo/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/franckalbinet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-17T06:40:25.000Z","updated_at":"2025-01-19T16:17:22.000Z","dependencies_parsed_at":"2024-12-18T21:34:05.267Z","dependency_job_id":"091f482d-ed19-4b7b-ba44-8b0011573d16","html_url":"https://github.com/franckalbinet/teuvo","commit_stats":null,"previous_names":["franckalbinet/teuvo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/franckalbinet/teuvo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franckalbinet%2Fteuvo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franckalbinet%2Fteuvo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franckalbinet%2Fteuvo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franckalbinet%2Fteuvo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/franckalbinet","download_url":"https://codeload.github.com/franckalbinet/teuvo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franckalbinet%2Fteuvo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262361543,"owners_count":23299081,"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","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":["data-visualization","dimensionality-reduction","neural-network"],"created_at":"2024-12-21T17:18:12.539Z","updated_at":"2026-02-09T06:05:33.925Z","avatar_url":"https://github.com/franckalbinet.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Teuvo\n\n\n\u003c!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! --\u003e\n\n## Design Philosophy\n\nDeveloped through the innovative **“SolveIt”** tool and methodology\ncurrently featured at [Answer.ai](https://www.answer.ai), this Python\npackage embodies a transformative approach to problem-solving. Rather\nthan treating AI as a mysterious black box that simply produces answers,\nit leverages **AI as an illuminating tool that deepens our understanding\nof problems and guides us toward solutions**.\n\nAt its core, the package draws inspiration from George Pólya’s seminal\n“How to Solve It” framework. What makes this implementation unique is\nits radical commitment to transparency and literate programming - the\nentire development process is meticulously documented in this [**“How\nwas it created?” notebook**](workflow/how-was-it-created.ipynb), serving\nas both a comprehensive guide and a testament to the step-by-step\nproblem-solving methodology.\n\nThe package’s **source code emerges naturally from this foundational\nnotebook**, carefully refactoring the core functionality that was\nthoughtfully developed through deliberate, incremental steps. This\napproach ensures that every component is not only well-documented but\nalso deeply understood.\n\n## Features\n\n- Multiple initialization methods:\n  - Random initialization\n  - PCA-based initialization (for faster convergence)\n- Flexible training options:\n  - Customizable learning rate schedules\n  - Adjustable neighborhood functions\n  - Quantization and Topographic Errors monitoring plots during\n    training:\n\n![](./img/som-training-in-action.gif)\n\n- Comprehensive quality metrics:\n  - Quantization Error\n  - Topographic Error\n- Rich visualization tools:\n  - U-Matrix visualization\n  - Hit histograms and Component planes (coming soon)\n\n## Installation\n\n``` bash\npip install teuvo\n```\n\n## Quick Start\n\n``` python\nfrom teuvo.core import SOM\nimport numpy as np\nfrom sklearn.datasets import load_digits\n\n# Load and normalize MNIST data\nX, y = load_digits(return_X_y=True)\nX_norm = (X - np.mean(X, axis=-1, keepdims=True))/X.max()\n\n# Create and train SOM\nsom = SOM(grid_sz=(20,20), input_dim=64, init='pca')\nsom.fit(X_norm, n_epochs=20, verbose=True)\n\n# Visualize results\nsom.plot_umatrix(figsize=(4,4))\n```\n\n    \u003cdiv style=\"font-family: monospace; margin: 10px\"\u003e\n        \u003ch4\u003eTraining Progress\u003c/h4\u003e\n        \u0026#10;\n\n|       |        |        |\n|:------|-------:|-------:|\n| Epoch |     QE |     TE |\n| 1     | 2.0001 | 2.0590 |\n| 2     | 1.9462 | 4.7301 |\n| 3     | 1.8539 | 0.6121 |\n| 4     | 1.8458 | 1.5582 |\n| 5     | 1.7964 | 1.8364 |\n| 6     | 1.7228 | 0.7791 |\n| 7     | 1.6385 | 0.4452 |\n| 8     | 1.5939 | 0.3339 |\n| 9     | 1.5624 | 0.3339 |\n| 10    | 1.4959 | 0.5565 |\n| 11    | 1.4390 | 0.6121 |\n| 12    | 1.3935 | 0.6678 |\n| 13    | 1.3539 | 0.6678 |\n| 14    | 1.3116 | 0.8904 |\n| 15    | 1.2758 | 1.0017 |\n| 16    | 1.2444 | 0.7234 |\n| 17    | 1.2162 | 0.7234 |\n| 18    | 1.1915 | 0.7234 |\n| 19    | 1.1701 | 0.8347 |\n| 20    | 1.1523 | 0.6678 |\n\n    \u003c/div\u003e\n    \u0026#10;\n\n![](index_files/figure-commonmark/cell-2-output-2.png)\n\n\u003cstyle\u003e\n    /* Turns off some styling */\n    progress {\n        /* gets rid of default border in Firefox and Opera. */\n        border: none;\n        /* Needs to be in here for Safari polyfill so background images work as expected. */\n        background-size: auto;\n    }\n    progress:not([value]), progress:not([value])::-webkit-progress-bar {\n        background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);\n    }\n    .progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {\n        background: #F44336;\n    }\n\u003c/style\u003e\n\n![](index_files/figure-commonmark/cell-2-output-5.png)\n\n## Detailed Example: MNIST Digit Classification\n\n``` python\nfrom teuvo.core import SOM, Scheduler\nimport numpy as np\nfrom sklearn.datasets import load_digits\nimport matplotlib.pyplot as plt\n\n# Load and preprocess data\nX, y = load_digits(return_X_y=True)\nX_norm = (X - np.mean(X, axis=-1, keepdims=True))/X.max()\n\n# Initialize SOM\nsom = SOM(\n    grid_sz=(20,20),\n    input_dim=64,\n    init='pca'  # Use PCA initialization\n)\n\n# Create custom schedulers\nlr_scheduler = Scheduler(start_val=1.0, end_val=0.01, \n                         step_size=200, n_samples=len(X), n_epochs=20)\nsigma_scheduler = Scheduler(start_val=10.0, end_val=1.0, \n                            step_size=200, n_samples=len(X), n_epochs=20)\n\n# Train\nweights, qe_errors, te_errors = som.fit(\n    X_norm,\n    n_epochs=15,\n    lr_scheduler=lr_scheduler,\n    sigma_scheduler=sigma_scheduler\n)\n```\n\n    \u003cdiv style=\"font-family: monospace; margin: 10px\"\u003e\n        \u003ch4\u003eTraining Progress\u003c/h4\u003e\n        \u0026#10;\n\n|       |        |        |\n|:------|-------:|-------:|\n| Epoch |     QE |     TE |\n| 1     | 1.9399 | 1.3912 |\n| 2     | 2.0015 | 1.6694 |\n| 3     | 1.9254 | 2.7824 |\n| 4     | 1.7919 | 0.6121 |\n| 5     | 1.7639 | 1.1686 |\n| 6     | 1.7188 | 0.7791 |\n| 7     | 1.6138 | 0.6121 |\n| 8     | 1.5829 | 0.4452 |\n| 9     | 1.5376 | 0.2782 |\n| 10    | 1.4790 | 0.5008 |\n| 11    | 1.4333 | 0.3339 |\n| 12    | 1.3924 | 0.3895 |\n| 13    | 1.3472 | 1.0017 |\n| 14    | 1.3150 | 0.2782 |\n| 15    | 1.2801 | 0.3895 |\n\n    \u003c/div\u003e\n    \u0026#10;\n\n![](index_files/figure-commonmark/cell-3-output-2.png)\n\n\u003cstyle\u003e\n    /* Turns off some styling */\n    progress {\n        /* gets rid of default border in Firefox and Opera. */\n        border: none;\n        /* Needs to be in here for Safari polyfill so background images work as expected. */\n        background-size: auto;\n    }\n    progress:not([value]), progress:not([value])::-webkit-progress-bar {\n        background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);\n    }\n    .progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {\n        background: #F44336;\n    }\n\u003c/style\u003e\n\n``` python\nsom.plot_umatrix(figsize=(4,4))\n```\n\n![](index_files/figure-commonmark/cell-4-output-1.png)\n\n## Contributing\n\nWe welcome contributions! Please see our contributing guidelines for\ndetails.\n\n## References\n\n- Kohonen, T. (1982). Self-organized formation of topologically correct\n  feature maps\n- Kohonen, T. (2013). Essentials of the self-organizing map\n- Polya, G. (1945). How to Solve It\n\n## License\n\nApache 2.0\n\n## Acknowledgments\n\nNamed in honor of Teuvo Kohonen, who introduced the Self-Organizing Map\nalgorithm.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranckalbinet%2Fteuvo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffranckalbinet%2Fteuvo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranckalbinet%2Fteuvo/lists"}