# 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:

![](./img/som-training-in-action.gif)

- 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>
        &#10;

|       |        |        |
|:------|-------:|-------:|
| 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>
    &#10;

![](index_files/figure-commonmark/cell-2-output-2.png)

<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>

![](index_files/figure-commonmark/cell-2-output-5.png)

## 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>
        &#10;

|       |        |        |
|:------|-------:|-------:|
| 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>
    &#10;

![](index_files/figure-commonmark/cell-3-output-2.png)

<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))
```

![](index_files/figure-commonmark/cell-4-output-1.png)

## 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.
