Add -fclad-porting-hints to name missing custom derivatives.

When clad has no custom derivative for a function whose definition it
can see, it silently falls back to differentiating that definition,
descending into the library's internals (reference counting,
allocation, I/O). At a library boundary that is rarely intended and
often yields ill-formed or incorrect derivatives. The hard part of
teaching clad a new library is discovering which functions need a
custom derivative -- or a non-differentiable marker -- and with which
signature.

-fclad-porting-hints surfaces every such boundary. For each function
defined outside the main source file that clad differentiates by
cloning, it emits a remark naming the expected custom-derivative
signature and, for methods and constructors, the non-differentiable
marker to declare instead. The hint is a per-request flag propagated
to sub-requests, so the boundary function -- reached as a sub-request
during a gradient -- is covered. It changes no generated code and is
off by default.

The custom-derivatives guide documents the workflow, and the flag is
listed in -plugin-arg-clad -help.

Author: vgvassilev

docs/userDocs/source/user/CustomDerivatives.rst

@@ -435,3 +435,55 @@ Note that the constructor pullback does not need anything such as
 :code:`clad::ConstructorPushforwardTag<::Coordinates>`. It is because
 the constructor pullback takes :code:`d_coordinates` as an argument, which can be
 used to identify the class for which the constructor pullback is defined.
+
+Porting hints: discovering which custom derivatives to write
+============================================================
+
+When you bring clad to a new library, the hard part is usually finding *which*
+functions need a custom derivative (or a non-differentiable marker) and what
+signature each one must have. If clad has no custom derivative for a function
+and can see its definition, it silently falls back to **differentiating that
+definition** -- recursively descending into the library's internals (reference
+counting, allocation, I/O, ...), which for a library boundary is rarely what
+you want and often produces ill-formed or incorrect derivatives.
+
+The :code:`-fclad-porting-hints` plugin flag surfaces every such boundary. Pass
+it through the compiler driver:
+
+.. code-block:: bash
+
+  clang -fplugin=/path/to/clad.so \
+        -Xclang -plugin-arg-clad -Xclang -fclad-porting-hints \
+        -I/path/to/clad/include yourcode.cpp
+
+For every function that is defined **outside the main source file** (i.e. in an
+included header -- the library boundary) and that clad differentiates by cloning
+its definition, clad emits a remark naming the exact custom-derivative signature
+to provide *and* the marker to declare instead:
+
+.. code-block:: text
+
+  remark: clad has no custom derivative for 'scale' and is differentiating its
+          definition, descending into library internals
+    note: to differentiate it, provide clad::custom_derivatives::scale_pullback
+          with signature 'void (const Widget *, double, double, Widget *, double *)'
+    note: or declare it non-differentiable with
+          clad::custom_derivatives::nondifferentiable(clad::Tag<Widget>{})
+
+Each remark gives you the two ways to resolve the boundary:
+
+- **Differentiate it semantically.** Copy the printed signature and implement
+  the custom derivative (a pushforward, pullback, or reverse-forward -- see the
+  sections above). This is the right choice when the function has a meaningful
+  derivative that is simpler or more correct than clad cloning its
+  implementation (a matrix product's adjoint, a container's element access, ...).
+- **Mark it non-differentiable.** If the type carries no differentiable data
+  (a stream, an allocator, a reference-count handle, ...), declare
+  :code:`clad::custom_derivatives::nondifferentiable(clad::Tag<T>{})` and clad
+  will treat every use of it as opaque. The marker note is emitted for member
+  functions and constructors, where the enclosing type is the thing to mark.
+
+Only functions outside the main file are reported, so differentiating your own
+code stays quiet; the remarks focus on the library edge you are porting. The
+flag is a diagnostic aid only -- it changes no generated code. It is also listed
+in :code:`-plugin-arg-clad -help`.

include/clad/Differentiator/DerivativeBuilder.h

@@ -201,6 +201,11 @@ struct DerivativeAndOverload {
     /// context.
     ///
     DerivativeAndOverload Derive(const DiffRequest& request);
+    /// Under -fclad-porting-hints, when \p request will differentiate the
+    /// definition of a function defined outside the main source file (a library
+    /// boundary) with no custom derivative, emit a remark naming the expected
+    /// custom-derivative signature and the non-differentiable marker.
+    void EmitPortingHint(const DiffRequest& request);
     /// Find the derived function if present in the DerivedFnCollector.
     ///
     /// \param[in] request The request to find the derived function.

include/clad/Differentiator/DiffPlanner.h

@@ -122,6 +122,11 @@ struct DiffRequest {
   bool EnableVariedAnalysis = false;
   /// A flag to enable useful analysis during reverse-mode differentiation.
   bool EnableUsefulAnalysis = false;
+  /// A flag to emit porting-hint remarks (-fclad-porting-hints) when a function
+  /// defined outside the main source file is differentiated by cloning its
+  /// definition. Diagnostic-only; it does not affect the generated derivative
+  /// and is therefore excluded from request equality.
+  bool EmitPortingHints = false;
   /// A flag to request a clad::restore_tracker parameter in the generated
   /// _reverse_forw function.
   bool UseRestoreTracker = false;
@@ -279,6 +284,7 @@ struct RequestOptions {
   bool EnableTBRAnalysis = false;
   bool EnableVariedAnalysis = false;
   bool EnableUsefulAnalysis = false;
+  bool EmitPortingHints = false;
 };
 
   class DiffCollector: public clang::RecursiveASTVisitor<DiffCollector> {

lib/Differentiator/DerivativeBuilder.cpp

@@ -470,9 +470,49 @@ static void registerDerivative(Decl* D, Sema& S, const DiffRequest& R) {
     }
   }
 
+  void DerivativeBuilder::EmitPortingHint(const DiffRequest& request) {
+    if (!request.EmitPortingHints)
+      return;
+    const FunctionDecl* FD = request.Function;
+    // A custom derivative already covers this call; nothing to port. Only a
+    // function whose *definition* clad is about to clone is a porting gap.
+    if (!FD || request.CustomDerivative || !FD->isDefined() ||
+        !FD->getDeclName().isIdentifier())
+      return;
+    // Hint only at a library boundary: a function defined outside the main
+    // source file (an included header), where the user decides "differentiate
+    // vs. mark opaque" rather than clad silently cloning library internals.
+    if (m_Sema.getSourceManager().isInMainFile(FD->getLocation()))
+      return;
+
+    SourceLocation Loc = request.CallContext
+                             ? request.CallContext->getBeginLoc()
+                             : FD->getLocation();
+    llvm::SmallVector<const ValueDecl*, 4> diffParams;
+    for (const DiffInputVarInfo& VarInfo : request.DVI)
+      diffParams.push_back(VarInfo.param);
+    QualType DerivativeType = utils::GetDerivativeType(
+        m_Sema, FD, request.Mode, diffParams, /*forCustomDerv=*/true);
+
+    diag(DiagnosticsEngine::Remark, Loc,
+         "clad has no custom derivative for %0 and is differentiating its "
+         "definition, descending into library internals")
+        << FD;
+    diag(DiagnosticsEngine::Note, Loc,
+         "to differentiate it, provide clad::custom_derivatives::%0 with "
+         "signature %1")
+        << request.ComputeDerivativeName() << DerivativeType;
+    if (const auto* MD = dyn_cast<CXXMethodDecl>(FD))
+      diag(DiagnosticsEngine::Note, Loc,
+           "or declare it non-differentiable with "
+           "clad::custom_derivatives::nondifferentiable(clad::Tag<%0>{})")
+          << MD->getParent()->getQualifiedNameAsString();
+  }
+
   DerivativeAndOverload
   DerivativeBuilder::Derive(const DiffRequest& request) {
     TimedGenerationRegion G([&request]() { return (std::string)request; });
+    EmitPortingHint(request);
     if (const FunctionDecl* FD = request.Function) {
       // Process the custom derivative
       if (request.CustomDerivative) {

lib/Differentiator/DiffPlanner.cpp

@@ -907,6 +907,7 @@ static QualType GetDerivedFunctionType(const CallExpr* CE) {
       request.EnableTBRAnalysis = ReqOpts.EnableTBRAnalysis;
     request.EnableVariedAnalysis = ReqOpts.EnableVariedAnalysis;
     request.EnableUsefulAnalysis = ReqOpts.EnableUsefulAnalysis;
+    request.EmitPortingHints = ReqOpts.EmitPortingHints;
 
     const TemplateArgumentList* TAL = FD->getTemplateSpecializationArgs();
     assert(TAL && "Call must have specialization args!");
@@ -1255,6 +1256,7 @@ static QualType GetDerivedFunctionType(const CallExpr* CE) {
       request.EnableTBRAnalysis = m_TopMostReq->EnableTBRAnalysis;
       request.EnableVariedAnalysis = m_TopMostReq->EnableVariedAnalysis;
       request.EnableUsefulAnalysis = m_TopMostReq->EnableUsefulAnalysis;
+      request.EmitPortingHints = m_TopMostReq->EmitPortingHints;
       request.EnableErrorEstimation = m_TopMostReq->EnableErrorEstimation;
       request.CallContext = E;
 
@@ -1632,6 +1634,7 @@ static QualType GetDerivedFunctionType(const CallExpr* CE) {
     request.VerboseDiags = false;
     request.EnableTBRAnalysis = m_TopMostReq->EnableTBRAnalysis;
     request.EnableVariedAnalysis = m_TopMostReq->EnableVariedAnalysis;
+    request.EmitPortingHints = m_TopMostReq->EmitPortingHints;
 
     for (const auto* paramDecl : CD->parameters())
       request.DVI.push_back(paramDecl);

test/Misc/Args.C

@@ -10,6 +10,7 @@
 // CHECK_HELP-NEXT: -disable-tbr
 // CHECK_HELP-NEXT: -fcustom-estimation-model
 // CHECK_HELP-NEXT: -fprint-num-diff-errors
+// CHECK_HELP-NEXT: -fclad-porting-hints
 // CHECK_HELP-NEXT: -help
 
 // RUN: clang -fsyntax-only -fplugin=%cladlib -Xclang -plugin-arg-clad\

test/Misc/PortingHints.cpp

@@ -0,0 +1,40 @@
+// With -fclad-porting-hints, clad emits a remark for every function defined
+// outside the main file that it differentiates by cloning (i.e. that has no
+// custom derivative), naming the expected custom-derivative signature and the
+// non-differentiable marker.
+// RUN: clang -std=c++17 -fsyntax-only -fplugin=%cladlib -Xclang -plugin-arg-clad -Xclang \
+// RUN:   -fclad-porting-hints %s -I%S/../../include 2>&1 | %filecheck %s
+//
+// Without the flag, clad is silent about the clone.
+// RUN: clang -std=c++17 -fsyntax-only -fplugin=%cladlib %s -I%S/../../include 2>&1 \
+// RUN:   | %filecheck --check-prefix=CHECK-QUIET --allow-empty %s
+//
+// The flag is listed in -help.
+// RUN: clang -std=c++17 -fsyntax-only -fplugin=%cladlib -Xclang -plugin-arg-clad -Xclang \
+// RUN:   -help %s -I%S/../../include 2>&1 | %filecheck --check-prefix=CHECK-HELP %s
+//
+#include "clad/Differentiator/Differentiator.h"
+#include "PortingHintsLib.h"
+
+double f(double x) {
+  Widget w{2.0};
+  return w.scale(x);
+}
+
+int main() {
+  auto g = clad::gradient(f);
+  double dx = 0;
+  g.execute(2, &dx);
+}
+
+// The main-file function under differentiation is never reported as a boundary
+// -- only functions defined outside it are. 'f' is differentiated before it
+// descends into 'scale', so a broken main-file guard would emit this first.
+// CHECK-NOT: no custom derivative for 'f'
+// CHECK: remark: clad has no custom derivative for 'scale' and is differentiating its definition, descending into library internals
+// CHECK: note: to differentiate it, provide clad::custom_derivatives::scale_{{.*}} with signature
+// CHECK: note: or declare it non-differentiable with clad::custom_derivatives::nondifferentiable(clad::Tag<Widget>{})
+
+// CHECK-QUIET-NOT: remark:
+
+// CHECK-HELP: -fclad-porting-hints

test/Misc/PortingHintsLib.h

@@ -0,0 +1,9 @@
+// Companion "library" header for PortingHints.C. Its functions live outside the
+// test's main file, so clad treats them as a library boundary and (under
+// -fclad-porting-hints) emits porting remarks when it differentiates them.
+#pragma once
+
+struct Widget {
+  double value;
+  double scale(double x) const { return x * value; }
+};

tools/ClangPlugin.cpp

@@ -588,6 +588,7 @@ void InitTimers();
       SetTBRAnalysisOptions(m_DO, opts);
       SetActivityAnalysisOptions(m_DO, opts);
       SetUsefulAnalysisOptions(m_DO, opts);
+      opts.EmitPortingHints = m_DO.EmitPortingHints;
     }
 
     DiffScheduler& CladPlugin::getScheduler() {

tools/ClangPlugin.h

@@ -66,6 +66,7 @@ struct DifferentiationOptions {
   bool EnableUsefulAnalysis = false;
   bool DisableUsefulAnalysis = false;
   bool PrintNumDiffErrorInfo = false;
+  bool EmitPortingHints = false;
 };
 
     class CladExternalSource : public clang::ExternalSemaSource {
@@ -330,6 +331,8 @@ struct DifferentiationOptions {
             return false;
           } else if (args[i] == "-fprint-num-diff-errors") {
             m_DO.PrintNumDiffErrorInfo = true;
+          } else if (args[i] == "-fclad-porting-hints") {
+            m_DO.EmitPortingHints = true;
           } else if (args[i] == "-help") {
             // Print some help info.
             // CI.getFrontendOpts().ShowHelp does not give us control.
@@ -357,7 +360,13 @@ struct DifferentiationOptions {
                    "shared object to use as the custom estimation model.\n"
                 << "-fprint-num-diff-errors - allows users to print the "
                    "calculated numerical diff errors, this flag is overriden "
-                   "by -DCLAD_NO_NUM_DIFF.\n";
+                   "by -DCLAD_NO_NUM_DIFF.\n"
+                << "-fclad-porting-hints - When clad has no custom derivative "
+                   "for a function defined outside the main source file and "
+                   "falls back to differentiating its definition, emit a "
+                   "remark naming the expected custom-derivative signature and "
+                   "the non-differentiable marker. Useful when teaching clad "
+                   "about a new library.\n";
 
             llvm::errs() << "-help - Prints out this screen.\n\n";
           } else if (args[i] == "-version" || args[i] == "-v") {