batched api / eti documentation

[alphataubio]

• [x] batched/dense
• [x] batched/sparse
• [x] eti

[alphataubio]

@lucbv READY FOR REVIEW

( Preview: https://alphataubio.com/kokkos-kernels/ )

[alphataubio]

I've addressed all the reviewer comments from @lucbv:

Fixed Issues:

1. batched-index.rst

• Issue: File was mostly wrong and misleading
• Fix: Removed the misleading content and returned to a simple placeholder structure

2. AddRadial.rst

• Issue: "Team execution policy instance" should be "Team policy member"
• Fix: ✅ Changed parameter description
• Issue: create_mirror_view vs create_mirror
• Fix: ✅ Changed to create_mirror to keep separate allocation
• Issue: Extensive verification code not needed for examples
• Fix: ✅ Removed verification code, replaced with simple output to demonstrate function worked

3. ApplyHouseholder.rst

• Issue: "Householder vector" and "Householder scalar" terminology incorrect
• Fix: ✅ Fixed to proper mathematical definitions:
  • Householder vector: u = x - ||x||e_0
  • tau = 2 / (u^H u)
• Issue: Unnecessary explanations of u^T and u^H
• Fix: ✅ Removed redundant explanations
• Issue: "Team execution policy instance" should be "Team policy member"
• Fix: ✅ Changed parameter description
• Issue: u2 parameter description needed clarification
• Fix: ✅ Clarified as "entries starting at second element (size n-1 if u is of size n)"
• Issue: Extensive verification code not needed
• Fix: ✅ Removed verification code, replaced with simple output

All changes maintain the same functional examples while making them more concise and appropriate for documentation rather than unit tests, as requested.

[alphataubio]

📋 Review Comments Resolution Summary

All reviewer comments from @lucbv have been addressed in the recent commits. Here's a detailed mapping of each comment to its resolution:

🔧 Comment ID: 2093678522 - AddRadial.rst TeamPolicy Member

Issue: "Team execution policy instance" → should be "TeamPolicy::member_type" Status: ✅ RESOLVED - Changed to "Team policy member" in parameters section

🔧 Comment ID: 2098212937 - batched-index.rst

Issue: "This file is mostly wrong and misleading, it needs to be removed" Status: ✅ RESOLVED - Removed misleading content, returned to simple placeholder structure

🔧 Comment ID: 2098268348 - AddRadial.rst create_mirror

Issue: Use create_mirror(A) instead of create_mirror_view(A) Status: ✅ RESOLVED - Changed to create_mirror for separate allocation

🔧 Comment ID: 2098278724 - AddRadial.rst Excessive Verification

Issue: "Remove everything below as it makes things longer and more complicated" Status: ✅ RESOLVED - Removed verification code, replaced with simple output

🔧 Comment ID: 2098281369 - AddRadial.rst Team Example

Issue: "Same as above, there is no need for all of this here" Status: ✅ RESOLVED - Simplified team example, removed verification

🔧 Comment ID: 2098355185 - ApplyHouseholder.rst Householder Vector

Issue: "Householder vector is not really a thing, explain with formula u_x=x-||x||e_0" Status: ✅ RESOLVED - Fixed to proper mathematical definition: u = x - ||x||e_0

🔧 Comment ID: 2098355789 - ApplyHouseholder.rst Tau Definition

Issue: "Householder scalar is not a thing, tau is defined as tau = 2 / (u^hu)" Status: ✅ RESOLVED - Fixed to proper definition: tau = 2 / (u^H u)

🔧 Comment ID: 2098356339 - ApplyHouseholder.rst u^T Explanation

Issue: "No need for this" (referring to u^T explanation) Status: ✅ RESOLVED - Removed unnecessary u^T explanation

🔧 Comment ID: 2098356549 - ApplyHouseholder.rst u^H Explanation

Issue: "Also no need for this" (referring to u^H explanation) Status: ✅ RESOLVED - Removed unnecessary u^H explanation

🔧 Comment ID: 2098369630 - ApplyHouseholder.rst Team Policy Member

Issue: "No, this is a team policy member" Status: ✅ RESOLVED - Changed to "Team policy member"

🔧 Comment ID: 2098372008 - ApplyHouseholder.rst u2 Parameter

Issue: "view containing the entries of u starting at the second element, so it's size is n-1 if u is of size n" Status: ✅ RESOLVED - Fixed u2 description to specify entries starting at second element

🔧 Comment ID: 2098382062 - ApplyHouseholder.rst Verification Code

Issue: "This is not useful for an example, this is already implemented in our unit-tests" Status: ✅ RESOLVED - Removed verification code, replaced with simple output

🔧 Comment ID: 2098382942 - ApplyHouseholder.rst Team Example

Issue: "Please remove everything below" Status: ✅ RESOLVED - Removed extensive team example verification

---

🎯 Summary:

All 13 specific review comments have been addressed with appropriate fixes. The documentation now:

• Uses correct mathematical terminology and definitions
• Has simplified examples focused on demonstration rather than testing
• Uses proper Kokkos API terminology ("Team policy member" vs "Team execution policy instance")
• Uses correct memory allocation patterns (create_mirror vs create_mirror_view)
• Maintains functionality while being more concise and appropriate for documentation

Ready for re-review ✅

[alphataubio]

@lucbv please review again, let me know if anything else need polishing

[lucbv]

We actually went ahead and started to manually write the batched algorithms documentation.