rewrite the PTQMetaOps.hpp documentation

include/aidge/operator/PTQMetaOps.hpp

@@ -20,51 +20,65 @@
 
 namespace Aidge {
 
+    /**
+     * @brief Create a Quantizer node that initially consists of a multiplier and a scaling factor.
+     * @param scalingFactor The value of the multiplicative coefficient 
+     * @param name Name of the Quantizer
+     */
     std::shared_ptr<Aidge::Node> BaseQuantizer(double scalingFactor, const std::string& name);
-    void multiplyScalingFactor(std::shared_ptr<Aidge::Node> scalingNode, double coeff);
 
+    /**
+     * @brief Given a Quantizer, multiply it's internal multiplicative coefficient by a value.
+     * @param coeff The value of the multiplicative coefficient.
+     */
+    void multiplyScalingFactor(std::shared_ptr<Aidge::Node> quantizer, double coeff);
+
+    /**
+     * @brief Given a Quantizer, create a copy of it that has a Round node and a Clip node added
+     * at its endpoint, and replace the given Quantizer by it (a swap is also done by reference). 
+     * @param quantizer The quantizer to modify and replace.
+     * @param clipMin the min value of the clip node.
+     * @param clipMax the max value of the clip node.
+     */
     void appendRoundClip(std::shared_ptr<Node>& quantizer, double clipMin, double clipMax);
+    
+    /**
+     * @brief Given a Quantizer, create a copy of it that has the Round node removed,
+     * and replace the given Quantizer by it (a swap is also done by reference). 
+     * @param quantizer The quantizer to modify and replace.
+     */
     void removeRound(std::shared_ptr<Node>& quantizer);
-    void replaceScalingWithBitShift(std::shared_ptr<Node>& quantizer);
-    void castQuantizerIOs(std::shared_ptr<Node>& quantizer, Aidge::DataType externalType);
 
-/// @brief Quantizer acts as a meta-operator to handle scaling operations in the PTQ, replacing the Scaling Operator.
-/// This operator is composed of a sequence of [Mul] -> [Clip] -> [Round] operations.
-///
-/// @param scalingFactor The scaling factor to apply to the input (essentially a scalar to multiply the input with).
-/// @param clip_min The minimum value for the clip operation.
-/// @param clip_max The maximum value for the clip operation.
-/// @param name The name of the meta-operator node created.
-/// @return A shared pointer to an instance of the meta-operator node.
-std::shared_ptr<Aidge::Node> Quantizer(double scalingFactor, double clipMin, double clipMax, const std::string& name);
+    /**
+     * @brief Given a Quantizer, create a copy of it where the Mul node is replaced by
+     * a Bit-Shift node, and replace the given Quantizer by it (a swap is also done by reference). 
+     * @param quantizer The quantizer to modify and replace.
+     */
+    void replaceScalingWithBitShift(std::shared_ptr<Node>& quantizer);
 
-/// @brief Updates the scaling factor of a PTQ meta-operator node, allowing for dynamic adjustment of the scaling parameter.
-/// This function sets a new scaling factor for a specified meta-operator node, modifying the scalar applied in the [Mul] operation.
-/// The meta-operator node must be a PTQ-specific operator, such as a Quantizer or Scaling node.
-///
-/// @param MetaOpNode A shared pointer to the PTQ meta-operator node whose scaling factor will be updated.
-/// @param newScalingFactor The new scaling factor to apply to the meta-operator node.
-/// @return True if the scaling factor was successfully updated, false if the operation failed (e.g., if MetaOpNode is null or incompatible).
-void updateScalingFactor(std::shared_ptr<Aidge::Node> MetaOpNode, double newScalingFactor);
+    /**
+     * @brief Given a Quantizer, create a copy of it that has Cast nodes inserted at it's IOs,
+     * and replace the given Quantizer by it (a swap is also done by reference). The input cast 
+     * node convert the input data to the internal type, while the output cast convert it back
+     * to the external type.
+     * @param quantizer The quantizer to modify and replace.
+     * @param externalType The external data type used for the casts.
+     */
+    void castQuantizerIOs(std::shared_ptr<Node>& quantizer, Aidge::DataType externalType);
 
-/// @brief Retrieves the current scaling factor of a PTQ meta-operator node.
-/// This function returns the scaling factor associated with the specified PTQ meta-operator node,
-/// allowing inspection of the current scalar applied in the [Mul] operation.
-///
-/// @param MetaOpNode A shared pointer to the PTQ meta-operator node whose scaling factor is being queried.
-/// @return The scaling factor currently applied to the meta-operator node, or -1 if the operation fails (e.g., if MetaOpNode is null or incompatible).
-double getScalingFactor(std::shared_ptr<Aidge::Node> MetaOpNode);
+    /**
+     * @brief Given a Quantizer, retreive the coefficient of it's Mul node.
+     * @param quantizer The quantizer containing the multiplicative coefficient.
+     */
+    double getScalingFactor(std::shared_ptr<Aidge::Node> quantizer);
 
-/// @brief Sets the clip range for an existing Quantizer node by specifying minimum and maximum clipping values.
-/// This function modifies the clip range of a Quantizer node, allowing adjustment of the range within which values are clipped
-/// in the [Clip] operation of the Quantizer sequence.
-///
-/// @param QuantizerNode A shared pointer to the Quantizer node whose clip range is being set.
-/// This node should have been created using the Quantizer function.
-/// @param min The minimum value for the clip range. Values below this will be clipped to this minimum.
-/// @param max The maximum value for the clip range. Values above this will be clipped to this maximum.
-/// @return True if the clip range was successfully set, false if the operation failed (e.g., if QuantizerNode is null).
-void setClipRange(std::shared_ptr<Aidge::Node> QuantizerNode, double min, double max);
+    /**
+     * @brief Given a Quantizer containing a Clip node, replace its clipping values.
+     * @param quantizer The quantizer containing the Clip node.
+     * @param min The min clipping value.
+     * @param max The max clipping value.
+     */
+    void setClipRange(std::shared_ptr<Aidge::Node> quantizer, double min, double max);
 
 }
 

src/operator/PTQMetaOps.cpp

@@ -78,14 +78,14 @@ std::shared_ptr<Node> BaseQuantizer(double scalingFactor, const std::string& nam
     // alternative : capture the Producer ...
     // std::shared_ptr<GraphView> connectedGraphView = getConnectedGraphView(mulNode); 
 
-    std::shared_ptr<Node> quantizerNode = MetaOperator("BaseQuantizer", graphView, {}, name); // an simpler prototype exists ...
+    std::shared_ptr<Node> quantizer = MetaOperator("BaseQuantizer", graphView, {}, name); // an simpler prototype exists ...
 
-    return quantizerNode;
+    return quantizer;
 }
 
-void multiplyScalingFactor(std::shared_ptr<Aidge::Node> scalingNode, double coeff)
+void multiplyScalingFactor(std::shared_ptr<Aidge::Node> quantizer, double coeff)
 {
-    auto quantizerOp = std::static_pointer_cast<MetaOperator_Op> (scalingNode->getOperator());
+    auto quantizerOp = std::static_pointer_cast<MetaOperator_Op> (quantizer->getOperator());
 
     // Get the Mul node from the microGraph
 
@@ -169,18 +169,11 @@ void appendRoundClip(std::shared_ptr<Node>& quantizer, double clipMin, double cl
     quantizer = newQuantizer;
 }
 
-void updateScalingFactor(std::shared_ptr<Node> quantizerNode, double scalingFactor)
-{
-    // XXX TODO : implement or remove the function ...
-
-    Log::error(" updateScalingFactor() : not yet implemented ... ");
-}
-
-double getScalingFactor(std::shared_ptr<Node> quantizerNode)
+double getScalingFactor(std::shared_ptr<Node> quantizer)
 {
     // Retreive the previous microGraph
 
-    auto quantizerOp = std::static_pointer_cast<MetaOperator_Op> (quantizerNode->getOperator());
+    auto quantizerOp = std::static_pointer_cast<MetaOperator_Op> (quantizer->getOperator());
     auto microGraph = quantizerOp->getMicroGraph();
 
     // Get the Mul node from the microGraph
@@ -203,9 +196,9 @@ double getScalingFactor(std::shared_ptr<Node> quantizerNode)
     return scalingFactor;
 }
 
-void setClipRange(std::shared_ptr<Node> quantizerNode, double min, double max)
+void setClipRange(std::shared_ptr<Node> quantizer, double min, double max)
 {
-    auto quantizerOp = std::static_pointer_cast<MetaOperator_Op> (quantizerNode->getOperator());
+    auto quantizerOp = std::static_pointer_cast<MetaOperator_Op> (quantizer->getOperator());
     auto microGraph = quantizerOp->getMicroGraph();
 
     std::shared_ptr<Node> clipNode = nullptr;