Start documenting autodiff activities

library/core/src/macros/mod.rs

@@ -1499,6 +1499,25 @@ pub(crate) mod builtin {
  /// - `INPUT_ACTIVITIES`: Specifies one valid activity for each input parameter.
  /// - `OUTPUT_ACTIVITY`: Must not be set if the function implicitly returns nothing
  /// (or explicitly returns `-> ()`). Otherwise, it must be set to one of the allowed activities.
+ ///
+ /// ACTIVITIES might either be `Dual` or `Const`, more options will be exposed later.
+ ///
+ /// `Const` should be used on non-float arguments, or float-based arguments as an optimization
+ /// if we are not interested in computing the derivatives with respect to this argument.
+ ///
+ /// `Dual` can be used for float scalar values or for references, raw pointers, or other
+ /// indirect input arguments. It can also be used on a scalar float return value.
+ /// If used on a return value, the generated function will return a tuple of two float scalars.
+ /// If used on an input argument, a new shadow argument of the same type will be created,
+ /// directly following the original argument.
+ ///
+ /// We might want to track how one input float affects one or more output floats. In this case,
+ /// the shadow of one input should be initialized to `1.0`, while the shadows of the other
+ /// inputs should be initialized to `0.0`. The shadow of the output(s) should be initialized to
+ /// `0.0`. After calling the generated function, the shadow of the input will be zeroed,
+ /// while the shadow(s) of the output(s) will contain the derivatives. Forward mode is generally
+ /// more efficient if we have more output floats marked as `Dual` than input floats.
+ /// Related information can also be found unter the term "Vector-Jacobian product" (VJP).
  #[unstable(feature = "autodiff", issue = "124509")]
  #[allow_internal_unstable(rustc_attrs)]
  #[allow_internal_unstable(core_intrinsics)]
@@ -1518,6 +1537,34 @@ pub(crate) mod builtin {
  /// - `INPUT_ACTIVITIES`: Specifies one valid activity for each input parameter.
  /// - `OUTPUT_ACTIVITY`: Must not be set if the function implicitly returns nothing
  /// (or explicitly returns `-> ()`). Otherwise, it must be set to one of the allowed activities.
+ ///
+ /// ACTIVITIES might either be `Active`, `Duplicated` or `Const`, more options will be exposed later.
+ ///
+ /// `Active` can be used for float scalar values.
+ /// If used on an input, a new float will be appended to the return tuple of the generated
+ /// function. If the function returns a float scalar, `Active` can be used for the return as
+ /// well. In this case a float scalar will be appended to the argument list, it works as seed.
+ ///
+ /// `Duplicated` can be used on references, raw pointers, or other indirect input
+ /// arguments. It creates a new shadow argument of the same type, following the original argument.
+ /// A const reference or pointer argument will receive a mutable reference or pointer as shadow.
+ ///
+ /// `Const` should be used on non-float arguments, or float-based arguments as an optimization
+ /// if we are not interested in computing the derivatives with respect to this argument.
+ ///
+ /// We often want to track how one or more input floats affect one output float. This output can
+ /// be a scalar return value, or a mutable reference or pointer argument. In this case, the
+ /// shadow of the input should be marked as duplicated and initialized to `0.0`. The shadow of
+ /// the output should be marked as active or duplicated and initialized to `1.0`. After calling
+ /// the generated function, the shadow(s) of the input(s) will contain the derivatives. If the
+ /// function has more than one output float marked as active or duplicated, users might want to
+ /// set one of them to `1.0` and the others to `0.0` to compute partial derivatives.
+ /// Unlike forward-mode, a call to the generated function does not reset the shadow of the
+ /// inputs.
+ /// Reverse mode is generally more efficient if we have more active/duplicated input than
+ /// output floats.
+ ///
+ /// Related information can also be found unter the term "Jacobian-Vector Product" (JVP).
  #[unstable(feature = "autodiff", issue = "124509")]
  #[allow_internal_unstable(rustc_attrs)]
  #[allow_internal_unstable(core_intrinsics)]