Add an opt-in mechanism for non-differentiable types.

When clad has no custom derivative for a called function it synthesizes
one by cloning the function's body. For a type whose internals are not
meant to be differentiated -- a standard-library primitive, an I/O
stream -- that clone is at best wasteful and at worst ill-formed:
cloning std::string's char-pointer constructor emits a static
reverse-forward propagator that dereferences a null `this` and crashes
CodeGen.

A type is now non-differentiable when it carries the `non_differentiable`
annotation -- on the type itself for code the user owns
(CLAD_NONDIFFERENTIABLE), or on a clad::Tag<T> specialization for a
foreign type the user cannot annotate at its declaration
(CLAD_NONDIFFERENTIABLE_TYPE). utils::isNonDifferentiableType detects it,
so clad never clones such a type's constructor or member bodies, and
callOperatesOnNonDifferentiableType extends the treatment to a call whose
object is opaque (e.g. a std::ostream operation). Seed std::string,
std::allocator and the stream family in STLBuiltins.h.

-fclad-porting-hints prints the paste-able CLAD_NONDIFFERENTIABLE_TYPE
spelling and, for a reverse-forward pass, the elidable_reverse_forw
route with its signature -- pointing at existing mechanisms rather than
inventing new ones. isElidableConstructor is renamed to
constructorReverseForwIsElidable and documented so its "a trivial copy is
a shallow share" coverage is discoverable; that made a separate
data-less-copy heuristic unnecessary.

The user guide documents both macros; tests cover marker-based
construction opacity (StringConstructor) and a marked-type call
(NonDifferentiableMarkedType).

Author: vgvassilev

docs/userDocs/source/user/CustomDerivatives.rst

@@ -467,21 +467,25 @@ to provide *and* the marker to declare instead:
           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>{})
+    note: or mark it non-differentiable with CLAD_NONDIFFERENTIABLE_TYPE(Widget)
 
-Each remark gives you the two ways to resolve the boundary:
+Each remark gives you the 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.
+  (a stream, an allocator, a reference-count handle, ...), mark it with
+  :code:`CLAD_NONDIFFERENTIABLE_TYPE(T)` (see :doc:`UsingClad`) and clad will
+  treat every construction of and call on it as opaque. The marker note is
+  emitted for member functions and constructors, where the enclosing type is
+  the thing to mark.
+- **Elide its reverse-forward pass.** For a reverse-forward-pass boundary whose
+  pass is a no-op (e.g. a shallow copy that shares its adjoint), declare the
+  printed :code:`..._reverse_forw` and mark it :code:`elidable_reverse_forw`;
+  clad then skips the call instead of cloning a body.
 
 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

docs/userDocs/source/user/UsingClad.rst

@@ -598,36 +598,65 @@ The ``non_differentiable`` Attribute
 
 Occasionally, you may want to skip differentiating a specific variable or function call. For example, some variables might be used purely for logging, as constants, or as standalone metrics. Clad provides the ``non_differentiable`` annotation attribute to safely omit generating derivatives for these components.
 
-You can apply this attribute using Clang's annotation syntax. The most common approach is to define a macro alias:
+Clad ships the ``CLAD_NONDIFFERENTIABLE`` macro (defined in
+``clad/Differentiator/BuiltinDerivatives.h``, pulled in by ``Differentiator.h``)
+for this; it expands to ``__attribute__((annotate("non_differentiable")))``.
 
-.. code-block:: c++
-
-   #define non_differentiable __attribute__((annotate("non_differentiable")))
-
-If the ``non_differentiable`` attribute is applied to a variable, Clad skips generating a derivative counterpart for it:
+If ``CLAD_NONDIFFERENTIABLE`` is applied to a variable, Clad skips generating a
+derivative counterpart for it:
 
 .. code-block:: c++
 
    class PointData {
    public:
      double x;
      double y;
-     non_differentiable double weight; // Clad will not compute derivatives with respect to this member
+     CLAD_NONDIFFERENTIABLE double weight; // not differentiated
    };
 
 If the attribute is applied to a function declaration, Clad refrains from producing any derivative expressions for that specific function. Instead, calls to the primal function are injected directly, behaving as if the result has a zero derivative:
 
 .. code-block:: c++
 
-   non_differentiable double get_scaling_factor(double i, double j) { 
-       return i * j; 
+   CLAD_NONDIFFERENTIABLE double get_scaling_factor(double i, double j) {
+       return i * j;
    }
 
-   double compute(double i, double j) { 
-       // get_scaling_factor will skip differentiation completely. 
-       return get_scaling_factor(i, j) + i * j; 
+   double compute(double i, double j) {
+       // get_scaling_factor will skip differentiation completely.
+       return get_scaling_factor(i, j) + i * j;
+   }
+
+Marking a type you do not own
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The attribute must sit on the declaration you want to mark, so it cannot be
+attached to a library type declared in a header you do not control (a stream, an
+allocator, a third-party handle). For those, mark the type from the outside with
+``CLAD_NONDIFFERENTIABLE_TYPE`` at global scope; Clad then treats every
+construction of and call on that type as opaque:
+
+.. code-block:: c++
+
+   CLAD_NONDIFFERENTIABLE_TYPE(ThirdParty::Handle);
+   // template arguments (and commas) are fine:
+   CLAD_NONDIFFERENTIABLE_TYPE(std::map<int, double>);
+
+It expands to a ``clad::Tag`` specialization carrying
+``CLAD_NONDIFFERENTIABLE``. A concrete type is marked as written; a *template
+family* (e.g. every ``Boxed<T>``) needs a partial specialization the macro
+cannot express -- write it directly:
+
+.. code-block:: c++
+
+   namespace clad {
+   template <class T> class CLAD_NONDIFFERENTIABLE Tag<Boxed<T>> {};
    }
 
+The standard-library primitives Clad already knows are non-differentiable
+(``std::string``, ``std::allocator``, the stream family) are marked this way in
+``STLBuiltins.h``.
+
 Specifying Custom Derivatives
 -------------------------------
 

include/clad/Differentiator/BuiltinDerivatives.h

@@ -60,6 +60,21 @@ template <typename T, typename U> struct ValueAndAdjoint {
 /// We do the same for constructor_reverse_forw.
 template <class T> class Tag {};
 
+/// Marks an entity non-differentiable: clad treats it as opaque and never
+/// clones its body to synthesize a derivative. Apply at the declaration of a
+/// variable, member, function, or type you own, e.g.
+///   struct CLAD_NONDIFFERENTIABLE Handle { double* data; };
+#define CLAD_NONDIFFERENTIABLE __attribute__((annotate("non_differentiable")))
+
+/// Marks a type you do NOT own -- a library type you cannot annotate at its own
+/// declaration -- non-differentiable, by specializing clad::Tag for it. Use at
+/// global scope. The type may contain commas, e.g.
+///   CLAD_NONDIFFERENTIABLE_TYPE(std::map<int, double>);
+#define CLAD_NONDIFFERENTIABLE_TYPE(...)                                       \
+  namespace clad {                                                             \
+  template <> class CLAD_NONDIFFERENTIABLE Tag<__VA_ARGS__> {};                \
+  }
+
 /// We have aliases with for old tags for backwards compatibility.
 template <class T> using ConstructorPushforwardTag = Tag<T>;
 

include/clad/Differentiator/CladUtils.h

@@ -381,6 +381,26 @@ namespace clad {
 
     bool hasNonDifferentiableAttribute(const clang::Expr* E);
 
+    /// Returns true if \p RD is marked non-differentiable (opaque) by a
+    /// clad::custom_derivatives::nondifferentiable(clad::Tag<T>) declaration:
+    /// clad must not clone its member bodies to synthesize a derivative. The
+    /// built-in standard-library markers live in STLBuiltins.h; users extend
+    /// the set by declaring their own.
+    bool isNonDifferentiableType(clang::Sema& S,
+                                 const clang::CXXRecordDecl* RD);
+
+    /// Returns true if the type \p CE fundamentally operates on -- the object
+    /// of a member call, or the first argument of a free operator (`os << x`)
+    /// -- is non-differentiable (Tag-aware, so it honors clad::Tag<T> markers).
+    /// Deliberately narrower than hasNonDifferentiableAttribute(Expr): it looks
+    /// only at the operated-on type, so a differentiable call that merely
+    /// passes a marked value is unaffected. Callers use it to skip the call
+    /// outright (an early return) rather than to set the weaker nonDiff flag,
+    /// which in reverse mode would still schedule a pullback and descend into
+    /// the type's machinery.
+    bool callOperatesOnNonDifferentiableType(clang::Sema& S,
+                                             const clang::CallExpr* CE);
+
     /// Collects every DeclRefExpr, MemberExpr, ArraySubscriptExpr in an
     /// assignment operator or a ternary if operator. This is useful to when we
     /// need to decide what needs to be stored on tape in reverse mode.
@@ -429,8 +449,17 @@ namespace clad {
     bool isLinearConstructor(const clang::CXXConstructorDecl* CD,
                              const clang::ASTContext& C);
 
-    bool isElidableConstructor(const clang::CXXConstructorDecl* CD,
-                               const clang::ASTContext& C);
+    /// Returns true if the reverse-forward propagator for constructor \p CD is
+    /// structurally elidable -- clad need not synthesize one because the plain
+    /// construction plus the normal member-wise adjoint handling already covers
+    /// it. This holds for a trivial copy/move constructor (a shallow share of
+    /// pointer/handle members), an aggregate, and a memberwise zero-or-copy
+    /// initializer. A non-trivial constructor can additionally opt in with the
+    /// elidable_reverse_forw attribute on its custom reverse_forw (see
+    /// hasElidableReverseForwAttribute) -- both paths are combined where the
+    /// propagator is consumed.
+    bool constructorReverseForwIsElidable(const clang::CXXConstructorDecl* CD,
+                                          const clang::ASTContext& C);
 
     /// Returns true if T allows to edit any memory.
     bool isMemoryType(clang::QualType T);

include/clad/Differentiator/STLBuiltins.h

@@ -7,8 +7,10 @@
 #include <clad/Differentiator/FunctionTraits.h>
 #include <functional>
 #include <initializer_list>
+#include <iosfwd>
 #include <iterator>
 #include <memory>
+#include <string>
 #include <tuple>
 #include <type_traits>
 #include <vector>
@@ -30,6 +32,30 @@ template <class T> void zero_init(typename std::allocator<T>&) {
   // do nothing, unclear if allocators have differentiable properties.
 }
 
+// Mark a library type non-differentiable (opaque) by specializing clad::Tag for
+// it and annotating the specialization: the `non_differentiable` attribute
+// cannot be attached to a type declared in a header we do not own. clad then
+// treats the type as opaque and never clones its member bodies to synthesize a
+// derivative -- which for these primitives would be ill-formed. A custom
+// derivative, if present, still wins. Add your own non-differentiable library
+// types the same way.
+template <class C, class Tr, class A>
+class CLAD_NONDIFFERENTIABLE Tag<::std::basic_string<C, Tr, A>> {};
+template <class T> class CLAD_NONDIFFERENTIABLE Tag<::std::allocator<T>> {};
+// The stream family is non-differentiable I/O. Marking it lets clad treat a
+// stream operation (`os << x`, a streambuf method) as opaque instead of
+// descending into sentry/streambuf/scope_guard/char_traits machinery. Only
+// forward declarations (<iosfwd>) are needed to name the templates.
+template <class C, class Tr>
+class CLAD_NONDIFFERENTIABLE Tag<::std::basic_ostream<C, Tr>> {};
+template <class C, class Tr>
+class CLAD_NONDIFFERENTIABLE Tag<::std::basic_istream<C, Tr>> {};
+template <class C, class Tr>
+class CLAD_NONDIFFERENTIABLE Tag<::std::basic_streambuf<C, Tr>> {};
+template <class C, class Tr>
+class CLAD_NONDIFFERENTIABLE Tag<::std::basic_ios<C, Tr>> {};
+template <> class CLAD_NONDIFFERENTIABLE Tag<::std::ios_base> {};
+
 namespace custom_derivatives {
 
 namespace helpers {

lib/Differentiator/CladUtils.cpp

@@ -359,8 +359,8 @@ namespace clad {
       return true;
     }
 
-    bool isElidableConstructor(const clang::CXXConstructorDecl* CD,
-                               const clang::ASTContext& C) {
+    bool constructorReverseForwIsElidable(const clang::CXXConstructorDecl* CD,
+                                          const clang::ASTContext& C) {
       const CXXRecordDecl* RD = CD->getParent();
       if (CD->isCopyOrMoveConstructor() && CD->isTrivial())
         return true;
@@ -689,6 +689,51 @@ namespace clad {
       return false;
     }
 
+    bool isNonDifferentiableType(clang::Sema& S,
+                                 const clang::CXXRecordDecl* RD) {
+      // A type is non-differentiable (opaque) when it carries the
+      // `non_differentiable` annotation. For a type the user owns the attribute
+      // sits on the type itself; for a foreign type it cannot, so the opt-out
+      // is expressed on a clad::Tag<T> specialization instead (see
+      // STLBuiltins.h). Either way clad never clones the type's member bodies
+      // to synthesize a derivative, which for library internals is ill-formed
+      // (see DiffCollector::VisitCXXConstructExpr). A custom derivative, if
+      // present, still wins: it is looked up first, so the marker only
+      // suppresses the body-clone fallback.
+      if (!RD)
+        return false;
+      if (hasNonDifferentiableAttribute(RD))
+        return true;
+      // Out-of-line opt-out: the attribute lives on clad::Tag<RD>. Completing
+      // the specialization instantiates a matching partial specialization's
+      // attribute onto it (Tag's primary template is an empty class, so
+      // completion never fails); then read the attribute off it.
+      QualType TagTy = GetCladTagOfType(
+          S, clad_compat::getRecordType(S.getASTContext(), RD));
+      S.isCompleteType(GetValidSLoc(S), TagTy);
+      const auto* TagRD = TagTy->getAsCXXRecordDecl();
+      return TagRD && hasNonDifferentiableAttribute(TagRD);
+    }
+
+    bool callOperatesOnNonDifferentiableType(clang::Sema& S,
+                                             const clang::CallExpr* CE) {
+      // Extract the type the call operates on -- the declaring class of a
+      // member call, or the first argument of a free operator (`os << x`) --
+      // and ask whether it is non-differentiable. See the header for why this
+      // is narrower than hasNonDifferentiableAttribute(Expr) and why callers
+      // skip on it rather than set the nonDiff flag.
+      const clang::FunctionDecl* FD = CE->getDirectCallee();
+      if (const auto* MD = dyn_cast_or_null<clang::CXXMethodDecl>(FD))
+        if (isNonDifferentiableType(S, MD->getParent()))
+          return true;
+      if (FD && FD->isOverloadedOperator() && CE->getNumArgs() >= 1) {
+        QualType T = CE->getArg(0)->getType().getNonReferenceType();
+        if (isNonDifferentiableType(S, T->getAsCXXRecordDecl()))
+          return true;
+      }
+      return false;
+    }
+
     bool hasElidableReverseForwAttribute(const clang::Decl* D) {
       for (auto* Attr : D->specific_attrs<clang::AnnotateAttr>())
         if (Attr->getAnnotation() == "elidable_reverse_forw")

lib/Differentiator/DerivativeBuilder.cpp

@@ -476,8 +476,12 @@ static void registerDerivative(Decl* D, Sema& S, const DiffRequest& R) {
     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.
+    // Constructors have a non-identifier name (a constructor name) but are a
+    // primary porting case (e.g. std::string's constructor), so let them
+    // through; other non-identifier names (operators) have no clean suggested
+    // custom-derivative spelling, so skip them.
     if (!FD || request.CustomDerivative || !FD->isDefined() ||
-        !FD->getDeclName().isIdentifier())
+        (!FD->getDeclName().isIdentifier() && !isa<CXXConstructorDecl>(FD)))
       return;
     // Hint only at a library boundary: a function defined outside the main
     // source file (an included header), where the user decides "differentiate
@@ -502,11 +506,36 @@ static void registerDerivative(Decl* D, Sema& S, const DiffRequest& R) {
          "to differentiate it, provide clad::custom_derivatives::%0 with "
          "signature %1")
         << request.ComputeDerivativeName() << DerivativeType;
-    if (const auto* MD = dyn_cast<CXXMethodDecl>(FD))
+    if (const auto* MD = dyn_cast<CXXMethodDecl>(FD)) {
+      const CXXRecordDecl* RD = MD->getParent();
+      // Print the qualified name WITH template arguments
+      // (getQualifiedNameAsString drops them, yielding an ill-formed Tag<Boxed>
+      // for a Boxed<double>).
+      clang::PrintingPolicy Policy = m_Sema.getPrintingPolicy();
+      Policy.SuppressTagKeyword = true;
+      std::string TypeName =
+          clad_compat::getRecordType(m_Context, RD).getAsString(Policy);
       diag(DiagnosticsEngine::Note, Loc,
-           "or declare it non-differentiable with "
-           "clad::custom_derivatives::nondifferentiable(clad::Tag<%0>{})")
-          << MD->getParent()->getQualifiedNameAsString();
+           "or mark it non-differentiable with CLAD_NONDIFFERENTIABLE_TYPE(%0)")
+          << TypeName;
+      // The value-level macro marks a single type; a template instantiation is
+      // only that specialization. Marking the whole family needs a clad::Tag
+      // partial specialization the macro cannot express.
+      if (isa<clang::ClassTemplateSpecializationDecl>(RD))
+        diag(DiagnosticsEngine::Note, Loc,
+             "this marks only this specialization; to mark the whole template, "
+             "add a clad::Tag partial specialization carrying "
+             "CLAD_NONDIFFERENTIABLE");
+    }
+    // A reverse-forward pass that is a no-op (e.g. a shallow copy that shares
+    // its adjoint) need not be cloned: declare it and mark it elidable so clad
+    // skips the call. Point at the existing mechanism rather than a new one.
+    if (request.Mode == DiffMode::reverse_mode_forward_pass)
+      diag(DiagnosticsEngine::Note, Loc,
+           "or, if its reverse-forward pass is a no-op (e.g. a shallow copy "
+           "that shares its adjoint), declare %0 with signature %1 and mark it "
+           "elidable_reverse_forw")
+          << request.ComputeDerivativeName() << DerivativeType;
   }
 
   DerivativeAndOverload

lib/Differentiator/DiffPlanner.cpp

@@ -1252,6 +1252,15 @@ static QualType GetDerivedFunctionType(const CallExpr* CE) {
       if (clad::utils::hasNonDifferentiableAttribute(E))
         nonDiff = true;
 
+      // A call whose object is a marked non-differentiable type -- a stream
+      // operation (`os << x`) or a std::streambuf method -- is opaque. Do not
+      // schedule a derivative for it or recurse into its body; otherwise clad
+      // descends into the whole non-differentiable I/O machinery
+      // (sentry/streambuf/scope_guard/char_traits). The primal call is emitted
+      // as-is in the derivative.
+      if (clad::utils::callOperatesOnNonDifferentiableType(m_Sema, E))
+        return true;
+
       request.VerboseDiags = false;
       request.EnableTBRAnalysis = m_TopMostReq->EnableTBRAnalysis;
       request.EnableVariedAnalysis = m_TopMostReq->EnableVariedAnalysis;
@@ -1614,10 +1623,21 @@ static QualType GetDerivedFunctionType(const CallExpr* CE) {
     forwPassRequest.BaseFunctionName = "constructor";
     forwPassRequest.Mode = DiffMode::reverse_mode_forward_pass;
     forwPassRequest.CallContext = E;
+    forwPassRequest.EmitPortingHints = m_TopMostReq->EmitPortingHints;
     QualType recordTy = CD->getThisType()->getPointeeType();
     bool elideRevForw =
-        utils::isElidableConstructor(CD, m_Sema.getASTContext());
-    if (LookupCustomDerivativeDecl(forwPassRequest) || !elideRevForw)
+        utils::constructorReverseForwIsElidable(CD, m_Sema.getASTContext());
+    // Cloning the body of a non-differentiable constructor yields an ill-formed
+    // reverse-forward propagator: e.g. std::string's char-pointer constructor
+    // (reached through a Kokkos::View label) delegates to a private member
+    // (this->__init(...)), but the propagator is a static function with no
+    // `this`, so CodeGen crashes. Build a propagator for a marked type only
+    // when the user supplied a custom derivative, never by cloning the library
+    // body.
+    bool cloneBodyUnsafe =
+        utils::isNonDifferentiableType(m_Sema, CD->getParent());
+    if (LookupCustomDerivativeDecl(forwPassRequest) ||
+        (!elideRevForw && !cloneBodyUnsafe))
       m_DiffRequestGraph.addNode(forwPassRequest, /*isSource=*/true);
 
     // Don't build propagators for calls that do not contribute in