🤝 Contributing to Time series Additive Model (TAM)

⬅️ README | 📚 THEORY | 📘 DOCS GUIDE | 🆕 CHANGELOG

Thank you for your interest in contributing to TAM! We welcome contributions from the community, whether you are a mathematician adding a new effect or meta-model, or a software engineer optimizing our PyTorch tensor operations.

To ensure the framework remains mathematically rigorous and computationally stable, we ask all contributors to strictly follow the guidelines below.

1. Where to Start

  1. Check Existing Issues: Before starting to code, please check our [Issues tracker] to see if someone else is already working on the feature or bug.

  2. Open a New Issue: If you want to add a new Meta-Model or Effect, please open an issue first to discuss the mathematical validity and implementation strategy with the maintainers.

2. The “Mirror Architecture” (Documentation)

Because TAM serves two distinct audiences (mathematicians and software engineers), we enforce a strict Mirror Architecture for our documentation. You must separate mathematical proofs from Python engineering.

When you add a new feature, you must write a pair of Markdown files:

  • 🧠 math/ (The Brain): Explains why the formula is exact. Contains the theory, LaTeX equations ($$...$$), theorems, and academic citations {cite:p}`key`. Do not put code here.

  • 💻 architecture/ (The Hands): Explains how the Python script calculates the formula without crashing. Contains PyTorch implementation details, OOP structure, and VRAM management.

🏛️ Documentation Golden Rules

  • Read the full guide: Please read our detailed Documentation Generation Guide before writing documentation.

  • No Redundancy: The architecture/ files must never re-demonstrate the math. Link back to the math/ files.

  • Code Extraction: Do not hard-copy Python code into Markdown. Use the Sphinx {literalinclude} directive to pull code dynamically from the source files.

3. Coding Standards

Our core engine is built for industrial-grade performance on massive datasets. If you are modifying the Python source code in src/tam/:

  • OOM Safety: Ensure your PyTorch implementations strictly respect Out-Of-Memory (OOM) safety protocols. Matrix operations across the group dimension must support dynamic chunking (try/except memory routing).

  • Vectorization: Avoid standard Python for loops. Exploit N-dimensional broadcasting and PyTorch tensorization.

  • Docstrings: We use Google-style docstrings. Ensure your functions and classes are fully documented, as Sphinx uses autodoc and napoleon to generate the API reference automatically.

  • Type Hinting: Use strict Python type hints (typing) for all function arguments and return types.

  • No Math in Code Comments: Keep inline Python comments focused strictly on software engineering (e.g., tensor shapes # Shape: [B, T, D], VRAM allocation, PyTorch workarounds). Leave the mathematical proofs to the math/ Markdown files.

4. Submitting a Pull Request (PR)

  1. Fork the repository and create your branch from main.

  2. Implement your feature and ensure your code follows the coding standards.

  3. Write the documentation pair in the math/ and architecture/ folders.

  4. Compile the docs locally: Run build_docs.bat (Windows) or build_docs.sh (Linux/Mac) to ensure the HTML and PDFs compile perfectly without Sphinx or LaTeX warnings.

  5. Submit your PR: Provide a clear description of the problem solved, the mathematical approach taken, and the performance implications.

By contributing to TAM, you agree that your contributions will be licensed under the project’s LGPL license.