# Teuvo
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
## Design Philosophy
Developed through the innovative **“SolveIt”** tool and methodology
currently featured at [Answer.ai](https://www.answer.ai), this Python
package embodies a transformative approach to problem-solving. Rather
than treating AI as a mysterious black box that simply produces answers,
it leverages **AI as an illuminating tool that deepens our understanding
of problems and guides us toward solutions**.
At its core, the package draws inspiration from George Pólya’s seminal
“How to Solve It” framework. What makes this implementation unique is
its radical commitment to transparency and literate programming - the
entire development process is meticulously documented in this [**“How
was it created?” notebook**](workflow/how-was-it-created.ipynb), serving
as both a comprehensive guide and a testament to the step-by-step
problem-solving methodology.
The package’s **source code emerges naturally from this foundational
notebook**, carefully refactoring the core functionality that was
thoughtfully developed through deliberate, incremental steps. This
approach ensures that every component is not only well-documented but
also deeply understood.
## Features
- Multiple initialization methods:
- Random initialization
- PCA-based initialization (for faster convergence)
- Flexible training options:
- Customizable learning rate schedules
- Adjustable neighborhood functions
- Quantization and Topographic Errors monitoring plots during
training:
- Comprehensive quality metrics:
- Quantization Error
- Topographic Error
- Rich visualization tools:
- U-Matrix visualization
- Hit histograms and Component planes (coming soon)
## Installation
``` bash
pip install teuvo
```
## Quick Start
``` python
from teuvo.core import SOM
import numpy as np
from sklearn.datasets import load_digits
# Load and normalize MNIST data
X, y = load_digits(return_X_y=True)
X_norm = (X - np.mean(X, axis=-1, keepdims=True))/X.max()
# Create and train SOM
som = SOM(grid_sz=(20,20), input_dim=64, init='pca')
som.fit(X_norm, n_epochs=20, verbose=True)
# Visualize results
som.plot_umatrix(figsize=(4,4))
```
<div style="font-family: monospace; margin: 10px">
<h4>Training Progress</h4>
| | | |
|:------|-------:|-------:|
| Epoch | QE | TE |
| 1 | 2.0001 | 2.0590 |
| 2 | 1.9462 | 4.7301 |
| 3 | 1.8539 | 0.6121 |
| 4 | 1.8458 | 1.5582 |
| 5 | 1.7964 | 1.8364 |
| 6 | 1.7228 | 0.7791 |
| 7 | 1.6385 | 0.4452 |
| 8 | 1.5939 | 0.3339 |
| 9 | 1.5624 | 0.3339 |
| 10 | 1.4959 | 0.5565 |
| 11 | 1.4390 | 0.6121 |
| 12 | 1.3935 | 0.6678 |
| 13 | 1.3539 | 0.6678 |
| 14 | 1.3116 | 0.8904 |
| 15 | 1.2758 | 1.0017 |
| 16 | 1.2444 | 0.7234 |
| 17 | 1.2162 | 0.7234 |
| 18 | 1.1915 | 0.7234 |
| 19 | 1.1701 | 0.8347 |
| 20 | 1.1523 | 0.6678 |
</div>
<style>
/* Turns off some styling */
progress {
/* gets rid of default border in Firefox and Opera. */
border: none;
/* Needs to be in here for Safari polyfill so background images work as expected. */
background-size: auto;
}
progress:not([value]), progress:not([value])::-webkit-progress-bar {
background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);
}
.progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {
background: #F44336;
}
</style>
## Detailed Example: MNIST Digit Classification
``` python
from teuvo.core import SOM, Scheduler
import numpy as np
from sklearn.datasets import load_digits
import matplotlib.pyplot as plt
# Load and preprocess data
X, y = load_digits(return_X_y=True)
X_norm = (X - np.mean(X, axis=-1, keepdims=True))/X.max()
# Initialize SOM
som = SOM(
grid_sz=(20,20),
input_dim=64,
init='pca' # Use PCA initialization
)
# Create custom schedulers
lr_scheduler = Scheduler(start_val=1.0, end_val=0.01,
step_size=200, n_samples=len(X), n_epochs=20)
sigma_scheduler = Scheduler(start_val=10.0, end_val=1.0,
step_size=200, n_samples=len(X), n_epochs=20)
# Train
weights, qe_errors, te_errors = som.fit(
X_norm,
n_epochs=15,
lr_scheduler=lr_scheduler,
sigma_scheduler=sigma_scheduler
)
```
<div style="font-family: monospace; margin: 10px">
<h4>Training Progress</h4>
| | | |
|:------|-------:|-------:|
| Epoch | QE | TE |
| 1 | 1.9399 | 1.3912 |
| 2 | 2.0015 | 1.6694 |
| 3 | 1.9254 | 2.7824 |
| 4 | 1.7919 | 0.6121 |
| 5 | 1.7639 | 1.1686 |
| 6 | 1.7188 | 0.7791 |
| 7 | 1.6138 | 0.6121 |
| 8 | 1.5829 | 0.4452 |
| 9 | 1.5376 | 0.2782 |
| 10 | 1.4790 | 0.5008 |
| 11 | 1.4333 | 0.3339 |
| 12 | 1.3924 | 0.3895 |
| 13 | 1.3472 | 1.0017 |
| 14 | 1.3150 | 0.2782 |
| 15 | 1.2801 | 0.3895 |
</div>
<style>
/* Turns off some styling */
progress {
/* gets rid of default border in Firefox and Opera. */
border: none;
/* Needs to be in here for Safari polyfill so background images work as expected. */
background-size: auto;
}
progress:not([value]), progress:not([value])::-webkit-progress-bar {
background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);
}
.progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {
background: #F44336;
}
</style>
``` python
som.plot_umatrix(figsize=(4,4))
```
## Contributing
We welcome contributions! Please see our contributing guidelines for
details.
## References
- Kohonen, T. (1982). Self-organized formation of topologically correct
feature maps
- Kohonen, T. (2013). Essentials of the self-organizing map
- Polya, G. (1945). How to Solve It
## License
Apache 2.0
## Acknowledgments
Named in honor of Teuvo Kohonen, who introduced the Self-Organizing Map
algorithm.
Raw data
{
"_id": null,
"home_page": "https://github.com/franckalbinet/teuvo",
"name": "teuvo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Franck Albinet",
"author_email": "franckalbinet@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b4/a3/22f4fa56e6c87c4b70f708c04241a7ea4b56b176a671977c0de757b49929/teuvo-0.0.2.tar.gz",
"platform": null,
"description": "# Teuvo\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n## Design Philosophy\n\nDeveloped through the innovative **\u201cSolveIt\u201d** 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\u00f3lya\u2019s seminal\n\u201cHow to Solve It\u201d framework. What makes this implementation unique is\nits radical commitment to transparency and literate programming - the\nentire development process is meticulously documented in this [**\u201cHow\nwas it created?\u201d 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\u2019s **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\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 <div style=\"font-family: monospace; margin: 10px\">\n <h4>Training Progress</h4>\n \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 </div>\n \n\n\n\n<style>\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</style>\n\n\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 <div style=\"font-family: monospace; margin: 10px\">\n <h4>Training Progress</h4>\n \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 </div>\n \n\n\n\n<style>\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</style>\n\n``` python\nsom.plot_umatrix(figsize=(4,4))\n```\n\n\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",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Self-Organzing Map",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/franckalbinet/teuvo"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e244b7d30b435012d4642d50a03edf52fc48cb5ec844ff63527b079ecab9cb83",
"md5": "bde374f331afc6d249d84e511161f13b",
"sha256": "1baf1f31c1c40613b9736c366c7707d40a88e9dcf2091fd80e0d3f94daacb604"
},
"downloads": -1,
"filename": "teuvo-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bde374f331afc6d249d84e511161f13b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12957,
"upload_time": "2025-01-20T10:14:59",
"upload_time_iso_8601": "2025-01-20T10:14:59.829954Z",
"url": "https://files.pythonhosted.org/packages/e2/44/b7d30b435012d4642d50a03edf52fc48cb5ec844ff63527b079ecab9cb83/teuvo-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b4a322f4fa56e6c87c4b70f708c04241a7ea4b56b176a671977c0de757b49929",
"md5": "3db33e8630d5cb68a3018d3f26581d55",
"sha256": "6023aee9a65adeae581c17f996a5d1b82079297cf0367f3fdb6567ee82c8b3ae"
},
"downloads": -1,
"filename": "teuvo-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "3db33e8630d5cb68a3018d3f26581d55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16107,
"upload_time": "2025-01-20T10:15:01",
"upload_time_iso_8601": "2025-01-20T10:15:01.793097Z",
"url": "https://files.pythonhosted.org/packages/b4/a3/22f4fa56e6c87c4b70f708c04241a7ea4b56b176a671977c0de757b49929/teuvo-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-20 10:15:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "franckalbinet",
"github_project": "teuvo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "teuvo"
}
JSON
