# 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
- 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)
# Visualize results
som.plot_umatrix(figsize=(4,4))
```
Epoch: 1 | QE: 2.1372, TE: 2.6711
Epoch: 2 | QE: 1.9623, TE: 1.6694
Epoch: 3 | QE: 1.8921, TE: 2.2259
Epoch: 4 | QE: 1.8032, TE: 1.7251
Epoch: 5 | QE: 1.7636, TE: 2.0590
Epoch: 6 | QE: 1.7209, TE: 1.0017
Epoch: 7 | QE: 1.6793, TE: 1.8920
Epoch: 8 | QE: 1.5912, TE: 0.9460
Epoch: 9 | QE: 1.5495, TE: 1.0017
Epoch: 10 | QE: 1.4944, TE: 0.7234
Epoch: 11 | QE: 1.4378, TE: 0.3895
Epoch: 12 | QE: 1.3935, TE: 0.4452
Epoch: 13 | QE: 1.3453, TE: 0.2226
Epoch: 14 | QE: 1.3103, TE: 0.2782
Epoch: 15 | QE: 1.2762, TE: 0.5565
Epoch: 16 | QE: 1.2435, TE: 0.2226
Epoch: 17 | QE: 1.2154, TE: 0.1113
Epoch: 18 | QE: 1.1908, TE: 0.3339
Epoch: 19 | QE: 1.1702, TE: 0.2226
Epoch: 20 | QE: 1.1529, TE: 0.4452
## 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=20,
lr_scheduler=lr_scheduler,
sigma_scheduler=sigma_scheduler
)
# Visualize results
plt.figure(figsize=(12,4))
plt.subplot(121)
plt.plot(qe_errors)
plt.title('Quantization Error')
plt.xlabel('Epoch')
plt.subplot(122)
plt.plot(te_errors)
plt.title('Topographic Error')
plt.xlabel('Epoch')
som.plot_umatrix(figsize=(4,4))
plt.tight_layout();
```
Epoch: 1 | QE: 2.1752, TE: 2.8381
Epoch: 2 | QE: 2.0267, TE: 2.3929
Epoch: 3 | QE: 1.8967, TE: 1.7251
Epoch: 4 | QE: 1.8424, TE: 1.6694
Epoch: 5 | QE: 1.7378, TE: 0.3895
Epoch: 6 | QE: 1.6918, TE: 1.1130
Epoch: 7 | QE: 1.6636, TE: 1.6694
Epoch: 8 | QE: 1.6096, TE: 1.2243
Epoch: 9 | QE: 1.5562, TE: 0.7234
Epoch: 10 | QE: 1.4827, TE: 0.7234
Epoch: 11 | QE: 1.4276, TE: 0.4452
Epoch: 12 | QE: 1.3930, TE: 0.4452
Epoch: 13 | QE: 1.3489, TE: 0.6121
Epoch: 14 | QE: 1.3121, TE: 0.5565
Epoch: 15 | QE: 1.2779, TE: 0.2782
Epoch: 16 | QE: 1.2442, TE: 0.5008
Epoch: 17 | QE: 1.2142, TE: 0.5565
Epoch: 18 | QE: 1.1886, TE: 0.3895
Epoch: 19 | QE: 1.1671, TE: 0.6678
Epoch: 20 | QE: 1.1492, TE: 1.0017
## 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/86/9d/0b0dacaa40700f94e1990f110e9d8e8c9540e02a991ecd6ab2716ba57fe5/teuvo-0.0.1.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- 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)\n\n# Visualize results\nsom.plot_umatrix(figsize=(4,4))\n```\n\n Epoch: 1 | QE: 2.1372, TE: 2.6711\n Epoch: 2 | QE: 1.9623, TE: 1.6694\n Epoch: 3 | QE: 1.8921, TE: 2.2259\n Epoch: 4 | QE: 1.8032, TE: 1.7251\n Epoch: 5 | QE: 1.7636, TE: 2.0590\n Epoch: 6 | QE: 1.7209, TE: 1.0017\n Epoch: 7 | QE: 1.6793, TE: 1.8920\n Epoch: 8 | QE: 1.5912, TE: 0.9460\n Epoch: 9 | QE: 1.5495, TE: 1.0017\n Epoch: 10 | QE: 1.4944, TE: 0.7234\n Epoch: 11 | QE: 1.4378, TE: 0.3895\n Epoch: 12 | QE: 1.3935, TE: 0.4452\n Epoch: 13 | QE: 1.3453, TE: 0.2226\n Epoch: 14 | QE: 1.3103, TE: 0.2782\n Epoch: 15 | QE: 1.2762, TE: 0.5565\n Epoch: 16 | QE: 1.2435, TE: 0.2226\n Epoch: 17 | QE: 1.2154, TE: 0.1113\n Epoch: 18 | QE: 1.1908, TE: 0.3339\n Epoch: 19 | QE: 1.1702, TE: 0.2226\n Epoch: 20 | QE: 1.1529, TE: 0.4452\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=20,\n lr_scheduler=lr_scheduler,\n sigma_scheduler=sigma_scheduler\n)\n\n# Visualize results\nplt.figure(figsize=(12,4))\n\nplt.subplot(121)\nplt.plot(qe_errors)\nplt.title('Quantization Error')\nplt.xlabel('Epoch')\n\nplt.subplot(122)\nplt.plot(te_errors)\nplt.title('Topographic Error')\nplt.xlabel('Epoch')\n\nsom.plot_umatrix(figsize=(4,4))\nplt.tight_layout();\n```\n\n Epoch: 1 | QE: 2.1752, TE: 2.8381\n Epoch: 2 | QE: 2.0267, TE: 2.3929\n Epoch: 3 | QE: 1.8967, TE: 1.7251\n Epoch: 4 | QE: 1.8424, TE: 1.6694\n Epoch: 5 | QE: 1.7378, TE: 0.3895\n Epoch: 6 | QE: 1.6918, TE: 1.1130\n Epoch: 7 | QE: 1.6636, TE: 1.6694\n Epoch: 8 | QE: 1.6096, TE: 1.2243\n Epoch: 9 | QE: 1.5562, TE: 0.7234\n Epoch: 10 | QE: 1.4827, TE: 0.7234\n Epoch: 11 | QE: 1.4276, TE: 0.4452\n Epoch: 12 | QE: 1.3930, TE: 0.4452\n Epoch: 13 | QE: 1.3489, TE: 0.6121\n Epoch: 14 | QE: 1.3121, TE: 0.5565\n Epoch: 15 | QE: 1.2779, TE: 0.2782\n Epoch: 16 | QE: 1.2442, TE: 0.5008\n Epoch: 17 | QE: 1.2142, TE: 0.5565\n Epoch: 18 | QE: 1.1886, TE: 0.3895\n Epoch: 19 | QE: 1.1671, TE: 0.6678\n Epoch: 20 | QE: 1.1492, TE: 1.0017\n\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.1",
"project_urls": {
"Homepage": "https://github.com/franckalbinet/teuvo"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f0bb18892d3a63f8c2637baf1ac2d7d1764e81ec0eb58427360671cb3db3a829",
"md5": "c39bef842e1575d82812d4f1e976cfd3",
"sha256": "b483a63815be0757c0198d46ea3b0d5c60762e9f2ff2cc1661ad343b5389d642"
},
"downloads": -1,
"filename": "teuvo-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c39bef842e1575d82812d4f1e976cfd3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11721,
"upload_time": "2024-12-18T21:47:49",
"upload_time_iso_8601": "2024-12-18T21:47:49.196387Z",
"url": "https://files.pythonhosted.org/packages/f0/bb/18892d3a63f8c2637baf1ac2d7d1764e81ec0eb58427360671cb3db3a829/teuvo-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "869d0b0dacaa40700f94e1990f110e9d8e8c9540e02a991ecd6ab2716ba57fe5",
"md5": "9b44736924aa29220cda7de4d277d792",
"sha256": "1b05b4652340abdaf27aac203ee5eb3fdc21f2bf1c7a0ca4deb0d8570104c417"
},
"downloads": -1,
"filename": "teuvo-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9b44736924aa29220cda7de4d277d792",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 14716,
"upload_time": "2024-12-18T21:47:51",
"upload_time_iso_8601": "2024-12-18T21:47:51.376313Z",
"url": "https://files.pythonhosted.org/packages/86/9d/0b0dacaa40700f94e1990f110e9d8e8c9540e02a991ecd6ab2716ba57fe5/teuvo-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 21:47:51",
"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
