Start documenting autodiff activities

[ZuseZ4]

@kevinyamauchi A first draft, please lmk whether they answer your question, or where you'd like clarifications or rewording, to make it easier to understand.

r? ghost

[rust-log-analyzer]

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

finished building tool typos error: `unter` should be `under` ╭▸ library/core/src/macros/mod.rs:1520:47 │ 1520 │ /// Related information can also be found unter the term "Vector-Jacobian product" (VJP). ╰╴ ━━━━━ error: `unter` should be `under` ╭▸ library/core/src/macros/mod.rs:1567:47 │ 1567 │ /// Related information can also be found unter the term "Jacobian-Vector Product" (JVP). ╰╴ ━━━━━ rerun tidy with `--extra-checks=spellcheck --bless` to fix typos tidy [extra_checks]: checks with external tool 'typos' failed tidy [extra_checks]: FAIL tidy: The following check failed: extra_checks Bootstrap failed while executing `test src/tools/tidy tidyselftest --extra-checks=py,cpp,js,spellcheck` Command `/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools-bin/rust-tidy /checkout /checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo /checkout/obj/build 4 /node/bin/npm --extra-checks=py,cpp,js,spellcheck` failed with exit code 1 Created at: src/bootstrap/src/core/build_steps/tool.rs:1549:23 Executed at: src/bootstrap/src/core/build_steps/test.rs:1280:29 Command has failed. Rerun with -v to see more details. Build completed unsuccessfully in 0:02:37 local time: Tue Oct 28 07:57:42 UTC 2025 network time: Tue, 28 Oct 2025 07:57:42 GMT ##[error]Process completed with exit code 1. ##[group]Run echo "disk usage:" 

[kevinyamauchi]

Thanks, @ZuseZ4 ! I will have a look tomorrow.

[kevinyamauchi]

Thanks @ZuseZ4 ! This already clarifies some things. Knowing which activity types are valid for forward/reverse mode is very helpful.

For me, it is still a bit unclear how the input/output annotations work in the reverse mode case where the output of the function is via a mutable reference function.

For example if we have a function f(x) = C * x^2 and we want to compute df / dx, is this how we would apply the macro?

#[autodiff_reverse(d_foo, Const, Active, Duplicated)] fn foo(c: f32: x: f32, out: &mut f32){ c * x * x }

If so, is this how we call the function?

let C: f32 = 4.0; let x: f32 = 3.0; // store the result of foo let mut foo_result: f32 = 0.0; // shadow variable to store the dF/dx value let mut dFoo_dx = 1.0; d_foo(C, x, &mut foo_result, &mut dFoo_dx); // I would expect dFoo_dx to be 2* 4 * 3 = 24 *[View changes since this review](https://triagebot.infra.rust-lang.org/gh-changes-since/rust-lang/rust/148201/df984edf44203c862e01b5a20c8092d5614d872e..a2dce774bc35a7fbafbe2d191a4eedf99023e17a)*

[kevinyamauchi]

To me, it is unclear what "this case" refers to. Based on the following text, I think this refers to the case when the output is a mutable reference or pointer argument. Is that right? If so, maybe something like the following would be more clear

Suggested change

	/// be a scalar return value, or a mutable reference or pointer argument. In this case, the
	/// be a scalar return value, or a mutable reference or pointer argument. In the latter case, the

or

Suggested change

	/// be a scalar return value, or a mutable reference or pointer argument. In this case, the
	/// be a scalar return value, or a mutable reference or pointer argument. If the output is stored in a mutable reference or pointer argument, the

[kevinyamauchi]

It is a bit unclear to me how the 1.0 and 0.0 are used to specify the partial derivatives. I would assume the output given 1.0 has it's derivative evaluated and the one 0.0 not, but I think it would be good to be explicit in the docs.