Modernize packaging, add a test suite, fix four methodology defects (v0.3.0)

[andremsouza]

Restructures the package and corrects four methodology defects found while reviewing #2.

Numerical results differ from 0.2.0. Every change is in the CHANGELOG with the
passage of Kohonen (2013) it follows. To reproduce figures made with an earlier version, pin
python-som==0.2.0.

Methodology defects fixed

Each was reproduced by running the library, and each has a regression test carrying its measured
numbers.

Defect	Measured before	After
Batch training zeroed models with no data in their neighbourhood (Eq. 8)	282 of 900 models wiped in one step	0
Linear init used eigenvalues where it needed eigenvectors (§4.3)	rank 1, every model a constant vector	rank 2, spans the PC plane
sequential ignored n_iteration	30 steps for a requested 500	honours the request
random sampling changed character with the iteration count	permutation below len(data), i.i.d. above	uniformly i.i.d. (Robbins–Monro, §4.1)
Auto map-size used the raw eigenvalue ratio (§3.5)	Iris x=20 → y=6	√(λ₁/λ₂) → y=11
σ could decay to zero (§4.2)	division by zero with linear_decay	floored at min_neighborhood_radius
Constructing a SOM reseeded NumPy's global RNG	host program affected	per-instance Generator

Performance

• Batch training ~30× faster: 1.89 s → 0.06 s on a 20×20 map, 150 samples, 5 iterations. A test
  asserts the contracted form matches the literal double loop of Eq. (8) to 1e-12.
• distance_matrix no longer builds an (x,y,x,y) tensor to produce x*y numbers. 800 MB → 80 KB
  on a 100×100 map, bit-identical on flat and toroidal grids.

Structure and tooling

• src/ layout split into _som, _neighborhood, _decay, _distance, with py.typed. Public
  imports are unchanged and the pre-0.3.0 private names still resolve.
• 190 tests at 100% coverage where there were none, including property-based tests over generated
  grids, radii and centres.
• ruff at select = ["ALL"], mypy --strict, pre-commit, CI across Python 3.10–3.13 that builds the
  wheel and imports it from a clean environment, docs site, and releases through PyPI trusted
  publishing.
• requires-python corrected to >=3.10, which is what PEP 604 annotations in runtime positions
  actually require. The declared >=3.9 could never import.

Verification

ruff check           All checks passed
ruff format --check  25 files already formatted
mypy --strict        no issues in 16 source files
pytest               190 passed, 100% coverage
mkdocs --strict      0 warnings
twine check          both artifacts PASSED
examples/iris.py     runs, map shape (20, 11), qe 0.0903

Notes for review

• The bubble neighbourhood is Chebyshev, not Euclidean, so it is not isotropic. The test
  shipped in 0.2.0 asserted that it was, and passed only because no counterexample exists on a
  21×21 grid at σ=3 — the smallest is at radius √50, needing σ≥5. Behaviour is unchanged and
  follows Vrieze's appendix pseudo-code; it is now documented and correctly tested.
• learning_rate is still unvalidated. α=5 diverges. Left alone here because rejecting
  previously-accepted values belongs in its own change; queued for 0.4.0.
• SOM has 14 instance attributes and a 13-argument constructor. A frozen SOMConfig is planned for
  0.4.0; PLR0913/PLR0917 are ignored at config level with that justification.

Once CI is green this gets tagged v0.3.0 immediately, so master never claims an unpublished version.