build based on 826d2c5

previews/PR416/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-02-03T19:01:59","documenter_version":"1.8.0"}}
+{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-02-03T19:29:22","documenter_version":"1.8.0"}}

previews/PR416/developer_documentation/misc_internals_notes/index.html

@@ -45,4 +45,4 @@
 good_tangent_type(::Type{Float32}) = Float32</code></pre><p>This leads to generated code which constant-folds / infers correctly:</p><pre><code class="language-julia hljs">julia&gt; Base.code_ircode(good_tangent_type, (Type{Tuple{Tuple{Float64}}}, ))[1]
 1 1 ─     return Tuple{Tuple{Float64}}
    =&gt; Type{Tuple{Tuple{Float64}}}</code></pre><p>I believe this works better because the recursion doesn&#39;t happen through another function, but appears directly in the function body. This is right at the edge of my understanding of Julia&#39;s compiler heuristics surrounding recursion though, so I might be mistaken.</p><p>It also behaves correctly under the addition of new methods of <code>good_tangent_type</code>, because <code>good_tangent_type</code> only appears in the expression returned by the generated function, not the body of the generated function itself:</p><pre><code class="language-julia hljs">julia&gt; good_tangent_type(Tuple{Float32})
-Tuple{Float32}</code></pre><h3 id="Effects-Etc"><a class="docs-heading-anchor" href="#Effects-Etc">Effects Etc</a><a id="Effects-Etc-1"></a><a class="docs-heading-anchor-permalink" href="#Effects-Etc" title="Permalink"></a></h3><p>This implementation is nearly sufficient to guarantee correct performance in all situations. However, in some cases it is possible that even this implementation will fall over. Annoyingly I&#39;ve not managed to produce a MWE that is even vaguely minimal in order to support this example, so you&#39;ll just have to believe me.</p><p>Based on all of the examples that I have seen thus far, it appears to be true that if you just <em>tell</em> the compiler that</p><ol><li>for the same inputs, the function always returns the same outputs, and</li><li>the function has no side-effects, so can be removed,</li></ol><p>everything will always constant fold nicely. This can be achieved by using the <code>Base.@assume_effects</code> macro in your method definitions, with the effects <code>:consistent</code> and <code>:removable</code>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../forwards_mode_design/">« Forwards-Mode Design</a><a class="docs-footer-nextpage" href="../internal_docstrings/">Internal Docstrings »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.8.0 on <span class="colophon-date" title="Monday 3 February 2025 19:01">Monday 3 February 2025</span>. Using Julia version 1.11.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+Tuple{Float32}</code></pre><h3 id="Effects-Etc"><a class="docs-heading-anchor" href="#Effects-Etc">Effects Etc</a><a id="Effects-Etc-1"></a><a class="docs-heading-anchor-permalink" href="#Effects-Etc" title="Permalink"></a></h3><p>This implementation is nearly sufficient to guarantee correct performance in all situations. However, in some cases it is possible that even this implementation will fall over. Annoyingly I&#39;ve not managed to produce a MWE that is even vaguely minimal in order to support this example, so you&#39;ll just have to believe me.</p><p>Based on all of the examples that I have seen thus far, it appears to be true that if you just <em>tell</em> the compiler that</p><ol><li>for the same inputs, the function always returns the same outputs, and</li><li>the function has no side-effects, so can be removed,</li></ol><p>everything will always constant fold nicely. This can be achieved by using the <code>Base.@assume_effects</code> macro in your method definitions, with the effects <code>:consistent</code> and <code>:removable</code>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../forwards_mode_design/">« Forwards-Mode Design</a><a class="docs-footer-nextpage" href="../internal_docstrings/">Internal Docstrings »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.8.0 on <span class="colophon-date" title="Monday 3 February 2025 19:29">Monday 3 February 2025</span>. Using Julia version 1.11.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

previews/PR416/known_limitations/index.html

@@ -38,4 +38,4 @@
 Mooncake.value_and_gradient!!(rule, foo, [5.0, 4.0])
 
 # output
-(4.0, (NoTangent(), [0.0, 1.0]))</code></pre><p><em><strong>The Solution</strong></em></p><p>This is only really a problem for tangent / fdata / rdata generation functionality, such as <code>zero_tangent</code>. As a work-around, AD testing functionality permits users to pass in <code>CoDual</code>s. So if you are testing something involving a pointer, you will need to construct its tangent yourself, and pass a <code>CoDual</code> to e.g. <code>Mooncake.TestUtils.test_rule</code>.</p><p>While pointers tend to be a low-level implementation detail in Julia code, you could in principle actually be interested in differentiating a function of a pointer. In this case, you will not be able to use <code>Mooncake.value_and_gradient!!</code> as this requires the use of <code>zero_tangent</code>. Instead, you will need to use lower-level (internal) functionality, such as <code>Mooncake.__value_and_gradient!!</code>, or use the rule interface directly.</p><p>Honestly, your best bet is just to avoid differentiating functions whose arguments are pointers if you can.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../developer_documentation/internal_docstrings/">« Internal Docstrings</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.8.0 on <span class="colophon-date" title="Monday 3 February 2025 19:01">Monday 3 February 2025</span>. Using Julia version 1.11.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+(4.0, (NoTangent(), [0.0, 1.0]))</code></pre><p><em><strong>The Solution</strong></em></p><p>This is only really a problem for tangent / fdata / rdata generation functionality, such as <code>zero_tangent</code>. As a work-around, AD testing functionality permits users to pass in <code>CoDual</code>s. So if you are testing something involving a pointer, you will need to construct its tangent yourself, and pass a <code>CoDual</code> to e.g. <code>Mooncake.TestUtils.test_rule</code>.</p><p>While pointers tend to be a low-level implementation detail in Julia code, you could in principle actually be interested in differentiating a function of a pointer. In this case, you will not be able to use <code>Mooncake.value_and_gradient!!</code> as this requires the use of <code>zero_tangent</code>. Instead, you will need to use lower-level (internal) functionality, such as <code>Mooncake.__value_and_gradient!!</code>, or use the rule interface directly.</p><p>Honestly, your best bet is just to avoid differentiating functions whose arguments are pointers if you can.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../developer_documentation/internal_docstrings/">« Internal Docstrings</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.8.0 on <span class="colophon-date" title="Monday 3 February 2025 19:29">Monday 3 February 2025</span>. Using Julia version 1.11.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>