Document _copy function protocol used in Mooncake.jl's AD system

[Copilot]

This PR addresses the lack of documentation for the _copy function protocol used throughout Mooncake.jl's automatic differentiation system. The _copy function is a critical internal protocol that handles creating independent copies of data structures during AD operations, but was previously undocumented.

Changes Made

Comprehensive documentation: Added detailed docstring explaining the purpose, semantics, and usage guidelines for the _copy protocol in src/utils.jl. The documentation includes:

• Clear explanation of when and why _copy is used in the AD system
• Semantics for different categories of types (immutable AD types, mutable containers, composite types)
• Implementation requirements and performance considerations
• Comprehensive examples covering all major type categories:
  • Immutable AD types (CoDual) - no copying needed
  • Stack types - create new empty instances
  • Composite types (Tuple) - recursive copying
  • Rule types (DerivedRule) - copy captures/caches appropriately
  • Misty closure types (MistyClosureRData) - deep copy captures data
  • Tangent types (PossiblyUninitTangent) - conditional copying based on initialization
  • Data types (FData/RData/LazyZeroRData) - recursive copying of wrapped data

Code organization: Moved the main _copy documentation and generic implementations to src/utils.jl for better discoverability, while keeping type-specific implementations in their respective files to maintain proper dependency ordering.

Inline comments: Added explanatory comments to all existing _copy implementations across the codebase.

The documentation helps maintainers and contributors understand this important internal protocol and implement it correctly for new types.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 57.14286% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/utils.jl	57.14%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Mooncake.jl documentation for PR #755 is available at:
https://chalk-lab.github.io/Mooncake.jl/previews/PR755/

[github-actions]

Performance Ratio:
Ratio of time to compute gradient and time to compute function.
Warning: results are very approximate! See here for more context.

┌────────────────────────────┬──────────┬──────────┬─────────────┬─────────┬─────────────┬─────────┐
│                      Label │   Primal │ Mooncake │ MooncakeFwd │  Zygote │ ReverseDiff │  Enzyme │
│                     String │   String │   String │      String │  String │      String │  String │
├────────────────────────────┼──────────┼──────────┼─────────────┼─────────┼─────────────┼─────────┤
│                   sum_1000 │ 100.0 ns │      1.8 │         1.8 │     1.0 │        5.61 │    8.21 │
│                  _sum_1000 │ 941.0 ns │     6.95 │        1.01 │  1460.0 │        34.3 │    1.09 │
│               sum_sin_1000 │  6.64 μs │     2.17 │        1.36 │    1.65 │        10.6 │    2.16 │
│              _sum_sin_1000 │  6.16 μs │     2.19 │        1.88 │   231.0 │        11.4 │    2.14 │
│                   kron_sum │ 341.0 μs │     64.9 │        2.75 │    4.62 │       186.0 │    11.2 │
│              kron_view_sum │ 336.0 μs │     41.7 │        3.37 │    16.4 │       224.0 │    9.99 │
│      naive_map_sin_cos_exp │  2.13 μs │     2.21 │        1.41 │ missing │         7.2 │    2.34 │
│            map_sin_cos_exp │  2.14 μs │     2.42 │        1.44 │    1.57 │        6.76 │    2.87 │
│      broadcast_sin_cos_exp │  2.27 μs │     2.25 │        1.39 │    2.36 │        1.48 │    2.26 │
│                 simple_mlp │ 207.0 μs │     6.18 │        2.95 │    1.65 │        10.3 │    3.28 │
│                     gp_lml │ 249.0 μs │     8.57 │         2.1 │    3.72 │     missing │     4.5 │
│ turing_broadcast_benchmark │  1.99 ms │     3.71 │        2.99 │ missing │        24.3 │ missing │
│         large_single_block │ 381.0 ns │     4.57 │        2.02 │  4410.0 │        35.2 │    2.23 │
└────────────────────────────┴──────────┴──────────┴─────────────┴─────────┴─────────────┴─────────┘

[yebai]

This looks good to me.

[yebai]

@avik-pal, it appears that recent Lux releases break the Mooncake/Lux integration tests. Can you help take a look?

[willtebbutt]

@yebai why was this merged without my review?

Firstly, how can you know whether copilot has successfully captued the semantics of _copy when it's not explained anywhere? Secondly, copilot has added a bunch of untested methods of _copy, which presumably alter the semantics, and could compromise correctness.

Please revert this PR at your earliest convenience.

[yebai]

Did you look at the PR? No new method was added; only comments and docs were added, mostly explaining via enumerating code examples. Feel free to improve further.

In addition, you were not responsive for a while, and I did try to request your review for all PRs, but no responses for a long time. As a mentor, I had to email you to get your response.

[willtebbutt]

In addition, you were not responsive for a while, and I did try to request your review for all PRs, but no responses for a long time. As a mentor, I had to email you to get your response.

I am perfectly happy for you to nudge me about reviewing PRs if my review isn't forthcoming, but I do ask that you follow the usual review process (ie. ask someone who is knowledgeable about whatever is being modified to review changes), rather than rushing things and merging PRs before they are ready. This has happened a couple of times recently:

1. Update zero_rdata_from_type to check for concretetype #736 -- no tests and no version bump
   2 Add better error messages for tangent accessors when types are passed #707 -- many redundant test cases, sub-optimal method implementations, no version bump.

In both instances, we had to fix the issues post-merge. This is not a problem if code we merged after the usual review process turns out to have some problems -- sometimes things get missed. I appreciate that you want to press ahead and resolve issues, but doing this at the expense of quality will be counterproductive.

Did you look at the PR? No new method was added; only comments and docs were added, mostly explaining via enumerating code examples. Feel free to improve further.

In my quick post-merge skim of this PR it looked like a lot of methods had been added. On closer inspection, it looks like methods have just been moved around, rather than new ones having been added. I would have noticed this had I had the time to review properly prior to code being merged. There are definitely problems with the accuracy of the comments + docstring though -- this is a problem because it is better to leave something undocumented than to provide documentation which is misleading / incorrect.

I will open a PR to revert the changes.

[yebai]

I'd veto the PR (#760) and suggest improving upon it before merging.

I'd suggest that you stay responsive and be considerate of your mentor's time. Since Mooncake is an ongoing research project, it will follow best engineering practices to the best of its effort, but shouldn't hinder incremental progress.

[willtebbutt]

I am just holding you to the same standards that all contributors to this and other open-source projects we've worked on are held to. I would likely have said something similar if anyone else who has merge rights on this project (or the others we're involved in) had merged a PR like this without review, in the same way that I would expect others to do were I to do something like this.

I am entirely in favour of incremental progress. For example, we're quite stringent about continuous delivery (releasing a new version immediately after changes to src / ext etc), are happy to merge PRs which solve part of a problem, and avoid expanding the scope of PRs, etc. However, I suspect that this particular PR is really a regression.

For example, the comment on the method of _copy for CoDual states # CoDual is immutable and can be safely shared without copying: it is true that CoDual is an immutable type, but the comment implies that its immutability is why copying is not required, and it is unclear to me whether this is correct. I have similar concerns with comments on other methods. Regarding the docstring for _copy: I do not know whether the Semantics or Implementation Requirements sections are correct. Furthermore, the examples section just appears to repeat implementations of methods of _copy, meaning that it could easily become outdated and misleading if we need to modify the implementation of _copy in the future, and is at least redundant.

What is needed is for someone (probably me) to take the time to figure out what purpose _copy serves, and from there to figure out what its semantics must be, what considerations must be made when implementing it, whether any examples are necessary in the docstring, and whether comments on specific methods of _copy are helpful.

Prior to this PR being merged, the documentation for this function was not especially urgent, and I did not wish to devote time to it when there are other higher-priority things to look after. Now that it has been merged, I can either take the time to figure out what the correct documentation is and fix this if needed, convince you to accept that we revert the PR (since the absence of documentation is preferable to inaccurate documentation), or do nothing (and accept the regression).

[yebai]

Isn't it true that most Mooncake PRs up to date are authored by you and directly merged without a review?

It works because

1. You are the right person to work on Mooncake.
2. I gave you full support and freedom.

The critical problem here is not about disagreeing on any engineering or open-source workflow. It is about bus factor: the bus factor for Mooncake is smaller than 2 and has to be increased.

Solving the bus factor issue implies more PRs will be merged without your or my review. Whether that will do more harm or prove useful, that is a team science question. Speaking of experience, I have a great deal of trust in the Julia open-source community and would like to invite more contributions gradually.