Docs theory code mapping

[sergioald]

Summary

Adds docs-only theory/code and validation mapping material.

Added

• docs/theory_code_mapping.md

  • Maps model concepts to implementation modules/functions.
  • Documents the main runtime call graph.
  • Clarifies default free-boundary and NumPy pathways.
  • Summarises output and testing maps.

• docs/validation_strategy.md

  • Summarises current validation philosophy.
  • Lists validated behaviours and known limitations.
  • Records recommended wording around periodic flow, optional Numba, and stability diagnostics.
  • Provides a validation roadmap and review checklist.

• README links to the new docs.

Validation

python -m pytest