[Core] Clarify how the visitor knows if a state is mapped or not (#6086)

clarify how the visitor knows if a state is mapped or not

Co-authored-by: Hugo <hugo.talbot@sofa-framework.org>

Author: alxbilger

Sofa/framework/Simulation/Core/src/sofa/simulation/BaseMechanicalVisitor.cpp

@@ -53,6 +53,22 @@ BaseMechanicalVisitor::BaseMechanicalVisitor(const sofa::core::ExecParams *param
     canAccessSleepingNode = false;
 }
 
+bool BaseMechanicalVisitor::isMechanicalStateMapped(simulation::Node* node) const
+{
+    /**
+     * WARNING!!!!!
+     *
+     * This condition is not valid for all cases, as it only checks for the presence of a mechanical
+     * mapping in the same Node. This condition does not ensure that the state is not an output of a
+     * mapping.
+     *
+     * Examples of situations where this condition is not appropritate:
+     * - No mapping in the Node but the mapping is defined in another Node.
+     * - There is a mapping in the Node, but the state is not an output of this mapping.
+     */
+    return node->mechanicalMapping != nullptr;
+}
+
 Visitor::Result BaseMechanicalVisitor::processNodeTopDown(simulation::Node *node, VisitorContext *ctx)
 {
     for (auto *solver : node->solver)
@@ -76,7 +92,7 @@ Visitor::Result BaseMechanicalVisitor::processNodeTopDown(simulation::Node *node
 
     if (node->mechanicalState != nullptr)
     {
-        if (node->mechanicalMapping != nullptr)
+        if (isMechanicalStateMapped(node))
         {
             res = runVisitorTask(this, ctx, &BaseMechanicalVisitor::fwdMappedMechanicalState, &*node->mechanicalState, fwdVisitorType);
         }
@@ -134,7 +150,7 @@ void BaseMechanicalVisitor::processNodeBottomUp(simulation::Node *node, VisitorC
 
     if (node->mechanicalState != nullptr)
     {
-        if (node->mechanicalMapping != nullptr)
+        if (isMechanicalStateMapped(node))
         {
             runVisitorTask(this, ctx, &BaseMechanicalVisitor::bwdMappedMechanicalState, &*node->mechanicalState, bwdVisitorType);
         }

Sofa/framework/Simulation/Core/src/sofa/simulation/BaseMechanicalVisitor.h

@@ -44,7 +44,7 @@ class SOFA_SIMULATION_CORE_API BaseMechanicalVisitor : public Visitor
 {
 
 protected:
-    simulation::Node* root; ///< root node from which the visitor was executed
+    simulation::Node* root { nullptr }; ///< root node from which the visitor was executed
 
     virtual Result processNodeTopDown(simulation::Node* node, VisitorContext* ctx);
     virtual void processNodeBottomUp(simulation::Node* node, VisitorContext* ctx);
@@ -56,6 +56,12 @@ class SOFA_SIMULATION_CORE_API BaseMechanicalVisitor : public Visitor
     /// Only used for debugging / profiling purposes
     const char* getClassName() const override;
 
+    /**
+     * Returns true if the node has a mapped mechanical state. It is mapped if the state is not an
+     * output of a mapping.
+     */
+    virtual bool isMechanicalStateMapped(simulation::Node* node) const;
+
     /**@name Forward processing
     Methods called during the forward (top-down) traversal of the data structure.
     Method processNodeTopDown(simulation::Node*) calls the fwd* methods in the order given here. When there is a mapping, it is processed first, then method fwdMappedMechanicalState is applied to the BaseMechanicalState.