improvement for documentations and error messages

Author: haojin2

python/mxnet/ndarray/numpy/_op.py

@@ -523,6 +523,14 @@ def add(x1, x2, out=None, **kwargs):
     -------
     add : ndarray or scalar
         The sum of x1 and x2, element-wise. This is a scalar if both x1 and x2 are scalars.
+
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), not supported yet.
     """
     return _ufunc_helper(x1, x2, _npi.add, _np.add, _npi.add_scalar, None, out)
 
@@ -549,6 +557,14 @@ def subtract(x1, x2, out=None, **kwargs):
     -------
     subtract : ndarray or scalar
         The difference of x1 and x2, element-wise. This is a scalar if both x1 and x2 are scalars.
+
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), not supported yet.
     """
     return _ufunc_helper(x1, x2, _npi.subtract, _np.subtract, _npi.subtract_scalar,
                          _npi.rsubtract_scalar, out)
@@ -576,6 +592,14 @@ def multiply(x1, x2, out=None, **kwargs):
     out : ndarray or scalar
         The multiplication of x1 and x2, element-wise. This is a scalar if both x1 and x2
         are scalars.
+
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), not supported yet.
     """
     return _ufunc_helper(x1, x2, _npi.multiply, _np.multiply, _npi.multiply_scalar, None, out)
 
@@ -603,6 +627,14 @@ def divide(x1, x2, out=None, **kwargs):
     -------
     out : ndarray or scalar
         This is a scalar if both x1 and x2 are scalars.
+
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), the output is of float32 type.
     """
     return _ufunc_helper(x1, x2, _npi.true_divide, _np.divide, _npi.true_divide_scalar,
                          _npi.rtrue_divide_scalar, out)
@@ -633,6 +665,14 @@ def true_divide(x1, x2, out=None):
     -------
     out : ndarray or scalar
         This is a scalar if both x1 and x2 are scalars.
+
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), the output is of float32 type.
     """
     return _ufunc_helper(x1, x2, _npi.true_divide, _np.divide, _npi.true_divide_scalar,
                          _npi.rtrue_divide_scalar, out)

python/mxnet/numpy/multiarray.py

@@ -2402,6 +2402,14 @@ def add(x1, x2, out=None, **kwargs):
     add : ndarray or scalar
         The sum of x1 and x2, element-wise. This is a scalar if both x1 and x2 are scalars.
 
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), not supported yet.
+
     Examples
     --------
     >>> np.add(1.0, 4.0)
@@ -2440,6 +2448,14 @@ def subtract(x1, x2, out=None, **kwargs):
     subtract : ndarray or scalar
         The difference of x1 and x2, element-wise. This is a scalar if both x1 and x2 are scalars.
 
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), not supported yet.
+
     Examples
     --------
     >>> np.subtract(1.0, 4.0)
@@ -2476,6 +2492,14 @@ def multiply(x1, x2, out=None, **kwargs):
     out : ndarray or scalar
         The difference of x1 and x2, element-wise. This is a scalar if both x1 and x2 are scalars.
 
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), not supported yet.
+
     Examples
     --------
     >>> np.multiply(2.0, 4.0)
@@ -2514,6 +2538,14 @@ def divide(x1, x2, out=None, **kwargs):
     out : ndarray or scalar
         This is a scalar if both x1 and x2 are scalars.
 
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), the output is of float32 type.
+
     Examples
     --------
     >>> np.true_divide(x, 4)
@@ -2548,6 +2580,14 @@ def true_divide(x1, x2, out=None):
     out : ndarray or scalar
         This is a scalar if both x1 and x2 are scalars.
 
+    Notes
+    -----
+    This operator now supports automatic type promotion. The resulting type will be determined
+    according to the following rules:
+        * If both inputs are of floating number types, the output is the more precise type.
+        * If only one of the inputs is floating number type, the result is that type.
+        * If both inputs are of integer types (including boolean), the output is of float32 type.
+
     Examples
     --------
     >>> x = np.arange(5)

src/common/utils.h

@@ -365,6 +365,30 @@ inline bool ContainsStorageType(const std::vector<int>& ndstypes,
   return false;
 }
 
+inline std::string dtype_string(const int dtype) {
+  switch (dtype) {
+    case mshadow::kFloat32:
+      return "float";
+    case mshadow::kFloat64:
+      return "double";
+    case mshadow::kFloat16:
+      return "half";
+    case mshadow::kUint8:
+      return "unsigned char";
+    case mshadow::kInt8:
+      return "char";
+    case mshadow::kInt32:
+      return "int";
+    case mshadow::kInt64:
+      return "long long";
+    case mshadow::kBool:
+      return "bool";
+    default:
+      LOG(FATAL) << "Unknown type enum " << dtype;
+  }
+  return "unknown";
+}
+
 /*! \brief get string representation of dispatch_mode */
 inline std::string dispatch_mode_string(const DispatchMode x) {
   switch (x) {

src/operator/numpy/np_elemwise_broadcast_op.h

@@ -20,7 +20,7 @@
 /*!
  *  Copyright (c) 2019 by Contributors
  * \file np_elemwise_binary_op.h
- * \brief 
+ * \brief Function definition of elemwise and broadcast operators
  */
 #ifndef MXNET_OPERATOR_NUMPY_NP_ELEMWISE_BROADCAST_OP_H_
 #define MXNET_OPERATOR_NUMPY_NP_ELEMWISE_BROADCAST_OP_H_
@@ -33,9 +33,16 @@
 namespace mxnet {
 namespace op {
 
+inline void PrintErrorMessage(const std::string& name, const int dtype1, const int dtype2) {
+  LOG(FATAL) << "Operator " << name << " does not support combination of "
+             << common::dtype_string(dtype1) << " with " << common::dtype_string(dtype2)
+             << " yet...";
+}
+
 #ifndef _WIN32
 template<typename xpu, typename OP>
-void MixedAllRealBinaryElemwiseCompute(const OpContext& ctx,
+void MixedAllRealBinaryElemwiseCompute(const std::string& op_name,
+                                       const OpContext& ctx,
                                        const TBlob& lhs,
                                        const TBlob& rhs,
                                        const TBlob& out,
@@ -61,7 +68,7 @@ void MixedAllRealBinaryElemwiseCompute(const OpContext& ctx,
               lhs.dptr<float>());
           });
         } else {
-          LOG(ERROR) << "Should not reach here!";
+          PrintErrorMessage(op_name, lhs.type_flag_, rhs.type_flag_);
         }
         break;
       }
@@ -80,13 +87,13 @@ void MixedAllRealBinaryElemwiseCompute(const OpContext& ctx,
               lhs.dptr<double>());
           });
         } else {
-          LOG(ERROR) << "Should not reach here!";
+          PrintErrorMessage(op_name, lhs.type_flag_, rhs.type_flag_);
         }
         break;
       }
       default:
       {
-        LOG(ERROR) << "Not supported case of ...";
+        PrintErrorMessage(op_name, lhs.type_flag_, rhs.type_flag_);
         break;
       }
     }
@@ -137,9 +144,9 @@ void MixedBinaryElemwiseCompute(const nnvm::NodeAttrs& attrs,
 
   if (common::is_float(lhs.type_flag_) && common::is_float(rhs.type_flag_)) {
     if (lhs.type_flag_ == out.type_flag_) {
-      MixedAllRealBinaryElemwiseCompute<xpu, ROP>(ctx, lhs, rhs, out, req[0]);
+      MixedAllRealBinaryElemwiseCompute<xpu, ROP>(attrs.op->name, ctx, lhs, rhs, out, req[0]);
     } else {
-      MixedAllRealBinaryElemwiseCompute<xpu, LOP>(ctx, rhs, lhs, out, req[0]);
+      MixedAllRealBinaryElemwiseCompute<xpu, LOP>(attrs.op->name, ctx, rhs, lhs, out, req[0]);
     }
   } else if (common::is_float(lhs.type_flag_) || common::is_float(rhs.type_flag_)) {
     if (lhs.type_flag_ == out.type_flag_) {
@@ -148,12 +155,13 @@ void MixedBinaryElemwiseCompute(const nnvm::NodeAttrs& attrs,
       MixedIntRealBinaryElemwiseCompute<xpu, LOP>(ctx, rhs, lhs, out, req[0]);
     }
   } else {
-    LOG(ERROR) << "not implemented yet...";
+    PrintErrorMessage(attrs.op->name, lhs.type_flag_, rhs.type_flag_);
   }
 }
 
 template<typename xpu, typename OP>
-void MixedAllRealBinaryBroadcastCompute(const OpContext& ctx,
+void MixedAllRealBinaryBroadcastCompute(const std::string& op_name,
+                                        const OpContext& ctx,
                                         const TBlob& lhs,
                                         const TBlob& rhs,
                                         const TBlob& out,
@@ -180,7 +188,7 @@ void MixedAllRealBinaryBroadcastCompute(const OpContext& ctx,
           template LaunchEx(s, new_oshape.Size(), req, rstride, lstride, oshape,
           rhs.dptr<mshadow::half::half_t>(), lhs.dptr<float>(), out.dptr<float>());
         } else {
-          LOG(ERROR) << "Should not reach here!";
+          PrintErrorMessage(op_name, lhs.type_flag_, rhs.type_flag_);
         }
         break;
       }
@@ -195,13 +203,13 @@ void MixedAllRealBinaryBroadcastCompute(const OpContext& ctx,
           template LaunchEx(s, new_oshape.Size(), req, rstride, lstride, oshape,
           rhs.dptr<float>(), lhs.dptr<double>(), out.dptr<double>());
         } else {
-          LOG(ERROR) << "Should not reach here!";
+          PrintErrorMessage(op_name, lhs.type_flag_, rhs.type_flag_);
         }
         break;
       }
       default:
       {
-        LOG(ERROR) << "Not supported case of ...";
+        PrintErrorMessage(op_name, lhs.type_flag_, rhs.type_flag_);
         break;
       }
     }
@@ -242,10 +250,10 @@ void MixedBinaryBroadcastCompute(const nnvm::NodeAttrs& attrs,
     if (common::is_float(lhs.type_flag_) && common::is_float(rhs.type_flag_)) {
       if (lhs.type_flag_ == out.type_flag_) {
         MixedAllRealBinaryBroadcastCompute<xpu, ROP>(
-          ctx, lhs, rhs, out, req[0], ndim, new_oshape, new_lshape, new_rshape);
+          attrs.op->name, ctx, lhs, rhs, out, req[0], ndim, new_oshape, new_lshape, new_rshape);
       } else {
         MixedAllRealBinaryBroadcastCompute<xpu, LOP>(
-          ctx, rhs, lhs, out, req[0], ndim, new_oshape, new_rshape, new_lshape);
+          attrs.op->name, ctx, rhs, lhs, out, req[0], ndim, new_oshape, new_rshape, new_lshape);
       }
     } else if (common::is_float(lhs.type_flag_) || common::is_float(rhs.type_flag_)) {
       CHECK(lhs.type_flag_ == out.type_flag_ || rhs.type_flag_ == out.type_flag_)
@@ -273,7 +281,7 @@ void MixedBinaryBroadcastCompute(const nnvm::NodeAttrs& attrs,
         }
       });
     } else {
-      LOG(ERROR) << "not implemented yet...";
+      PrintErrorMessage(attrs.op->name, lhs.type_flag_, rhs.type_flag_);
     }
   }
 #else
@@ -303,7 +311,7 @@ void MixedBinaryBroadcastCompute(const nnvm::NodeAttrs& attrs,
         attrs, ctx, {temp_tblob.reshape(lhs.shape_), rhs}, req, outputs);
     }
   } else {
-    LOG(ERROR) << "not implemented yet...";
+    PrintErrorMessage(attrs.op->name, lhs.type_flag_, rhs.type_flag_);
   }
 #endif
 }
@@ -324,7 +332,7 @@ void MixedBinaryBackwardUseIn(const nnvm::NodeAttrs& attrs,
     return;
   }
 
-  LOG(ERROR) << "Binary operation with mixed input data types does not support backward yet...";
+  PrintErrorMessage(attrs.op->name, lhs.type_flag_, rhs.type_flag_);
 }
 
 }  // namespace op