[Mlir-commits] [mlir] 850dbff - [MLIR][Math] Improve docs (NFC)
lorenzo chelini
llvmlistbot at llvm.org
Tue May 31 09:17:04 PDT 2022
Author: lorenzo chelini
Date: 2022-05-31T18:16:59+02:00
New Revision: 850dbff708f1e371722306363231a3816179ad7b
URL: https://github.com/llvm/llvm-project/commit/850dbff708f1e371722306363231a3816179ad7b
DIFF: https://github.com/llvm/llvm-project/commit/850dbff708f1e371722306363231a3816179ad7b.diff
LOG: [MLIR][Math] Improve docs (NFC)
Remove boilerplate examples and add a text at the dialect level to describe
what kind of operands the operations accept (i.e., scalar, tensor or vector).
Left a shorter sentence describing the input operands for each operation as
this redundancy is convenient when browsing the documentation using the
website.
Reviewed By: ftynse
Differential Revision: https://reviews.llvm.org/D126648
Added:
Modified:
mlir/include/mlir/Dialect/Math/IR/MathBase.td
mlir/include/mlir/Dialect/Math/IR/MathOps.td
Removed:
################################################################################
diff --git a/mlir/include/mlir/Dialect/Math/IR/MathBase.td b/mlir/include/mlir/Dialect/Math/IR/MathBase.td
index 8df9e2ce6d136..85c8c2baff652 100644
--- a/mlir/include/mlir/Dialect/Math/IR/MathBase.td
+++ b/mlir/include/mlir/Dialect/Math/IR/MathBase.td
@@ -13,7 +13,21 @@ def Math_Dialect : Dialect {
let cppNamespace = "::mlir::math";
let description = [{
The math dialect is intended to hold mathematical operations on integer and
- floating type beyond simple arithmetics.
+ floating types beyond simple arithmetics. Each operation works on scalar, vector
+ or tensor type. On vector and tensor type operations apply elementwise unless
+ explicitly specified otherwise. As an example, the floating point absolute value
+ can be expressed as:
+
+ ```mlir
+ // Scalar absolute value.
+ %a = math.abs %b : f64
+
+ // Vector elementwise absolute value.
+ %f = math.abs %g : vector<4xf32>
+
+ // Tensor elementwise absolute value.
+ %x = math.abs %y : tensor<4x?xf8>
+ ```
}];
let hasConstantMaterializer = 1;
let emitAccessorPrefix = kEmitAccessorPrefix_Prefixed;
diff --git a/mlir/include/mlir/Dialect/Math/IR/MathOps.td b/mlir/include/mlir/Dialect/Math/IR/MathOps.td
index 221af3f6a5f2c..1378135cb354e 100644
--- a/mlir/include/mlir/Dialect/Math/IR/MathOps.td
+++ b/mlir/include/mlir/Dialect/Math/IR/MathOps.td
@@ -21,9 +21,9 @@ class Math_Op<string mnemonic, list<Trait> traits = []> :
DeclareOpInterfaceMethods<VectorUnrollOpInterface>] #
ElementwiseMappable.traits>;
-// Base class for unary math operations on integer types. Require a operand and
-// result of the same type. This type can be an integer type, or vector or tensor
-// thereof.
+// Base class for unary math operations on integer types. Require an operand
+// and result of the same type. This type can be an integer type, vector or
+// tensor thereof.
class Math_IntegerUnaryOp<string mnemonic, list<Trait> traits = []> :
Math_Op<mnemonic, traits # [SameOperandsAndResultType]> {
let arguments = (ins SignlessIntegerLike:$operand);
@@ -32,9 +32,9 @@ class Math_IntegerUnaryOp<string mnemonic, list<Trait> traits = []> :
let assemblyFormat = "$operand attr-dict `:` type($result)";
}
-// Base class for unary math operations on floating point types. Require a
+// Base class for unary math operations on floating point types. Require an
// operand and result of the same type. This type can be a floating point type,
-// or vector or tensor thereof.
+// vector or tensor thereof.
class Math_FloatUnaryOp<string mnemonic, list<Trait> traits = []> :
Math_Op<mnemonic, traits # [SameOperandsAndResultType]> {
let arguments = (ins FloatLike:$operand);
@@ -45,7 +45,7 @@ class Math_FloatUnaryOp<string mnemonic, list<Trait> traits = []> :
// Base class for binary math operations on floating point types. Require two
// operands and one result of the same type. This type can be a floating point
-// type, or a vector or tensor thereof.
+// type, vector or tensor thereof.
class Math_FloatBinaryOp<string mnemonic, list<Trait> traits = []> :
Math_Op<mnemonic, traits # [SameOperandsAndResultType]> {
let arguments = (ins FloatLike:$lhs, FloatLike:$rhs);
@@ -55,8 +55,8 @@ class Math_FloatBinaryOp<string mnemonic, list<Trait> traits = []> :
}
// Base class for floating point ternary operations. Require three operands and
-// one result of the same type. This type can be a floating point type, or a
-// vector or tensor thereof.
+// one result of the same type. This type can be a floating point type, vector
+// or tensor thereof.
class Math_FloatTernaryOp<string mnemonic, list<Trait> traits = []> :
Math_Op<mnemonic, traits # [SameOperandsAndResultType]> {
let arguments = (ins FloatLike:$a, FloatLike:$b, FloatLike:$c);
@@ -72,21 +72,15 @@ class Math_FloatTernaryOp<string mnemonic, list<Trait> traits = []> :
def Math_AbsOp : Math_FloatUnaryOp<"abs"> {
let summary = "floating point absolute-value operation";
let description = [{
- The `abs` operation computes the absolute value. It takes one operand and
- returns one result of the same type. This type may be a float scalar type,
- a vector whose element type is float, or a tensor of floats.
+ The `abs` operation computes the absolute value. It takes one operand of
+ floating point type (i.e., scalar, tensor or vector) and returns one result of
+ the same type.
Example:
```mlir
// Scalar absolute value.
%a = math.abs %b : f64
-
- // SIMD vector element-wise absolute value.
- %f = math.abs %g : vector<4xf32>
-
- // Tensor element-wise absolute value.
- %x = math.abs %y : tensor<4x?xf8>
```
}];
let hasFolder = 1;
@@ -106,21 +100,14 @@ def Math_AtanOp : Math_FloatUnaryOp<"atan">{
```
The `atan` operation computes the arcus tangent of a given value. It takes
- one operand and returns one result of the same type. This type may be a
- float scalar type, a vector whose element type is float, or a tensor of
- floats. It has no standard attributes.
+ one operand of floating point type (i.e., scalar, tensor or vector) and returns
+ one result of the same type. It has no standard attributes.
Example:
```mlir
// Arcus tangent of scalar value.
%a = math.atan %b : f64
-
- // SIMD vector element-wise arcus tangent.
- %f = math.atan %g : vector<4xf32>
-
- // Tensor element-wise arcus tangent.
- %x = math.atan %y : tensor<4x?xf8>
```
}];
}
@@ -139,9 +126,8 @@ def Math_Atan2Op : Math_FloatBinaryOp<"atan2">{
```
The `atan2` operation takes two operands and returns one result, all of
- which must be of the same type. This type may be a floating point scalar
- type, a vector whose element type is a floating point type, or a floating
- point tensor.
+ which must be of the same type. The operands must be of floating point type
+ (i.e., scalar, tensor or vector).
The 2-argument arcus tangent `atan2(y, x)` returns the angle in the
Euclidian plane between the positive x-axis and the ray through the point
@@ -155,12 +141,6 @@ def Math_Atan2Op : Math_FloatBinaryOp<"atan2">{
```mlir
// Scalar variant.
%a = math.atan2 %b, %c : f32
-
- // SIMD vector variant.
- %f = math.atan2 %g, %h : vector<4xf32>
-
- // Tensor variant.
- %x = math.atan2 %y, %z : tensor<4x?xf32>
```
}];
}
@@ -179,21 +159,14 @@ def Math_CeilOp : Math_FloatUnaryOp<"ceil"> {
```
The `ceil` operation computes the ceiling of a given value. It takes one
- operand and returns one result of the same type. This type may be a float
- scalar type, a vector whose element type is float, or a tensor of floats.
- It has no standard attributes.
+ operand of floating point type (i.e., scalar, tensor or vector) and returns one
+ result of the same type. It has no standard attributes.
Example:
```mlir
// Scalar ceiling value.
%a = math.ceil %b : f64
-
- // SIMD vector element-wise ceiling value.
- %f = math.ceil %g : vector<4xf32>
-
- // Tensor element-wise ceiling value.
- %x = math.ceil %y : tensor<4x?xf8>
```
}];
let hasFolder = 1;
@@ -213,22 +186,15 @@ def Math_CopySignOp : Math_FloatBinaryOp<"copysign"> {
```
The `copysign` returns a value with the magnitude of the first operand and
- the sign of the second operand. It takes two operands and returns one
- result of the same type. This type may be a float scalar type, a vector
- whose element type is float, or a tensor of floats. It has no standard
- attributes.
+ the sign of the second operand. It takes two operands and returns one result of
+ the same type. The operands must be of floating point type (i.e., scalar,
+ tensor or vector). It has no standard attributes.
Example:
```mlir
// Scalar copysign value.
%a = math.copysign %b, %c : f64
-
- // SIMD vector element-wise copysign value.
- %f = math.copysign %g, %h : vector<4xf32>
-
- // Tensor element-wise copysign value.
- %x = math.copysign %y, %z : tensor<4x?xf8>
```
}];
let hasFolder = 1;
@@ -248,21 +214,14 @@ def Math_CosOp : Math_FloatUnaryOp<"cos"> {
```
The `cos` operation computes the cosine of a given value. It takes one
- operand and returns one result of the same type. This type may be a float
- scalar type, a vector whose element type is float, or a tensor of floats.
- It has no standard attributes.
+ operand of floating point type (i.e., scalar, tensor or vector) and returns one
+ result of the same type. It has no standard attributes.
Example:
```mlir
// Scalar cosine value.
%a = math.cos %b : f64
-
- // SIMD vector element-wise cosine value.
- %f = math.cos %g : vector<4xf32>
-
- // Tensor element-wise cosine value.
- %x = math.cos %y : tensor<4x?xf8>
```
}];
}
@@ -281,21 +240,14 @@ def Math_SinOp : Math_FloatUnaryOp<"sin"> {
```
The `sin` operation computes the sine of a given value. It takes one
- operand and returns one result of the same type. This type may be a float
- scalar type, a vector whose element type is float, or a tensor of floats.
- It has no standard attributes.
+ operand of floating point type (i.e., scalar, tensor or vector) and returns one
+ result of the same type. It has no standard attributes.
Example:
```mlir
// Scalar sine value.
%a = math.sin %b : f64
-
- // SIMD vector element-wise sine value.
- %f = math.sin %g : vector<4xf32>
-
- // Tensor element-wise sine value.
- %x = math.sin %y : tensor<4x?xf8>
```
}];
}
@@ -308,18 +260,13 @@ def Math_CountLeadingZerosOp : Math_IntegerUnaryOp<"ctlz"> {
let summary = "counts the leading zeros an integer value";
let description = [{
The `ctlz` operation computes the number of leading zeros of an integer value.
+ It operates on scalar, tensor or vector.
Example:
```mlir
// Scalar ctlz function value.
%a = math.ctlz %b : i32
-
- // SIMD vector element-wise ctlz function value.
- %f = math.ctlz %g : vector<4xi16>
-
- // Tensor element-wise ctlz function value.
- %x = math.ctlz %y : tensor<4x?xi8>
```
}];
let hasFolder = 1;
@@ -333,18 +280,13 @@ def Math_CountTrailingZerosOp : Math_IntegerUnaryOp<"cttz"> {
let summary = "counts the trailing zeros an integer value";
let description = [{
The `cttz` operation computes the number of trailing zeros of an integer value.
+ It operates on scalar, tensor or vector.
Example:
```mlir
// Scalar cttz function value.
%a = math.cttz %b : i32
-
- // SIMD vector element-wise cttz function value.
- %f = math.cttz %g : vector<4xi16>
-
- // Tensor element-wise cttz function value.
- %x = math.cttz %y : tensor<4x?xi8>
```
}];
let hasFolder = 1;
@@ -358,18 +300,13 @@ def Math_CtPopOp : Math_IntegerUnaryOp<"ctpop"> {
let summary = "counts the number of set bits of an integer value";
let description = [{
The `ctpop` operation computes the number of set bits of an integer value.
+ It operates on scalar, tensor or vector.
Example:
```mlir
// Scalar ctpop function value.
%a = math.ctpop %b : i32
-
- // SIMD vector element-wise ctpop function value.
- %f = math.ctpop %g : vector<4xi16>
-
- // Tensor element-wise ctpop function value.
- %x = math.ctpop %y : tensor<4x?xi8>
```
}];
let hasFolder = 1;
@@ -388,22 +325,15 @@ def Math_ErfOp : Math_FloatUnaryOp<"erf"> {
operation ::= ssa-id `=` `math.erf` ssa-use `:` type
```
- The `erf` operation computes the error function. It takes one operand
- and returns one result of the same type. This type may be a float scalar
- type, a vector whose element type is float, or a tensor of floats. It has
- no standard attributes.
+ The `erf` operation computes the error function. It takes one operand of
+ floating point type (i.e., scalar, tensor or vector) and returns one result of
+ the same type. It has no standard attributes.
Example:
```mlir
// Scalar error function value.
%a = math.erf %b : f64
-
- // SIMD vector element-wise error function value.
- %f = math.erf %g : vector<4xf32>
-
- // Tensor element-wise error function value.
- %x = math.erf %y : tensor<4x?xf8>
```
}];
}
@@ -422,21 +352,15 @@ def Math_ExpOp : Math_FloatUnaryOp<"exp"> {
operation ::= ssa-id `=` `math.exp` ssa-use `:` type
```
- The `exp` operation takes one operand and returns one result of the same
- type. This type may be a float scalar type, a vector whose element type is
- float, or a tensor of floats. It has no standard attributes.
+ The `exp` operation takes one operand of floating point type (i.e., scalar,
+ tensor or vector) and returns one result of the same type. It has no standard
+ attributes.
Example:
```mlir
// Scalar natural exponential.
%a = math.exp %b : f64
-
- // SIMD vector element-wise natural exponential.
- %f = math.exp %g : vector<4xf32>
-
- // Tensor element-wise natural exponential.
- %x = math.exp %y : tensor<4x?xf8>
```
}];
}
@@ -455,21 +379,15 @@ def Math_Exp2Op : Math_FloatUnaryOp<"exp2"> {
operation ::= ssa-id `=` `math.exp2` ssa-use `:` type
```
- The `exp` operation takes one operand and returns one result of the same
- type. This type may be a float scalar type, a vector whose element type is
- float, or a tensor of floats. It has no standard attributes.
+ The `exp` operation takes one operand of floating point type (i.e., scalar,
+ tensor or vector) and returns one result of the same type. It has no standard
+ attributes.
Example:
```mlir
// Scalar natural exponential.
%a = math.exp2 %b : f64
-
- // SIMD vector element-wise natural exponential.
- %f = math.exp2 %g : vector<4xf32>
-
- // Tensor element-wise natural exponential.
- %x = math.exp2 %y : tensor<4x?xf8>
```
}];
}
@@ -489,21 +407,15 @@ def Math_ExpM1Op : Math_FloatUnaryOp<"expm1"> {
expm1(x) := exp(x) - 1
- The `expm1` operation takes one operand and returns one result of the same
- type. This type may be a float scalar type, a vector whose element type is
- float, or a tensor of floats. It has no standard attributes.
+ The `expm1` operation takes one operand of floating point type (i.e.,
+ scalar, tensor or vector) and returns one result of the same type. It has no
+ standard attributes.
Example:
```mlir
// Scalar natural exponential minus 1.
%a = math.expm1 %b : f64
-
- // SIMD vector element-wise natural exponential minus 1.
- %f = math.expm1 %g : vector<4xf32>
-
- // Tensor element-wise natural exponential minus 1.
- %x = math.expm1 %y : tensor<4x?xf8>
```
}];
}
@@ -522,21 +434,14 @@ def Math_FloorOp : Math_FloatUnaryOp<"floor"> {
```
The `floor` operation computes the floor of a given value. It takes one
- operand and returns one result of the same type. This type may be a float
- scalar type, a vector whose element type is float, or a tensor of floats.
- It has no standard attributes.
+ operand of floating point type (i.e., scalar, tensor or vector) and returns one
+ result of the same type. It has no standard attributes.
Example:
```mlir
// Scalar floor value.
- %a = math.floor %b : f64
-
- // SIMD vector element-wise floor value.
- %f = math.floor %g : vector<4xf32>
-
- // Tensor element-wise floor value.
- %x = math.floor %y : tensor<4x?xf8>
+ %a = math.floor %b : f64
```
}];
}
@@ -555,21 +460,14 @@ def Math_FmaOp : Math_FloatTernaryOp<"fma"> {
```
The `fma` operation takes three operands and returns one result, each of
- these is required to be the same type. This type may be a floating point
- scalar type, a vector whose element type is a floating point type, or a
- floating point tensor.
+ these is required to be the same type. Operands must be of floating point type
+ (i.e., scalar, tensor or vector).
Example:
```mlir
// Scalar fused multiply-add: d = a*b + c
%d = math.fma %a, %b, %c : f64
-
- // SIMD vector fused multiply-add, e.g. for Intel SSE.
- %i = math.fma %f, %g, %h : vector<4xf32>
-
- // Tensor fused multiply-add.
- %w = math.fma %x, %y, %z : tensor<4x?xbf16>
```
The semantics of the operation correspond to those of the `llvm.fma`
@@ -587,12 +485,14 @@ def Math_LogOp : Math_FloatUnaryOp<"log"> {
let summary = "base-e logarithm of the specified value";
let description = [{
- Computes the base-e logarithm of the given value. It takes one operand and
- returns one result of the same type.
+ Computes the base-e logarithm of the given value. It takes one operand of
+ floating point type (i.e., scalar, tensor or vector) and returns one result of
+ the same type.
Example:
```mlir
+ // Scalar log operation.
%y = math.log %x : f64
```
}];
@@ -606,12 +506,14 @@ def Math_Log10Op : Math_FloatUnaryOp<"log10"> {
let summary = "base-10 logarithm of the specified value";
let description = [{
- Computes the base-10 logarithm of the given value. It takes one operand and
- returns one result of the same type.
+ Computes the base-10 logarithm of the given value. It takes one operand of
+ floating point type (i.e., scalar, tensor or vector) and returns one result of
+ the same type.
Example:
```mlir
+ // Scalar log10 operation.
%y = math.log10 %x : f64
```
}];
@@ -626,13 +528,15 @@ def Math_Log1pOp : Math_FloatUnaryOp<"log1p"> {
let description = [{
Computes the base-e logarithm of one plus the given value. It takes one
- operand and returns one result of the same type.
+ operand of floating point type (i.e., scalar, tensor or vector) and returns one
+ result of the same type.
log1p(x) := log(1 + x)
Example:
```mlir
+ // Scalar log1p operation.
%y = math.log1p %x : f64
```
}];
@@ -646,12 +550,14 @@ def Math_Log2Op : Math_FloatUnaryOp<"log2"> {
let summary = "base-2 logarithm of the specified value";
let description = [{
- Computes the base-2 logarithm of the given value. It takes one operand and
- returns one result of the same type.
+ Computes the base-2 logarithm of the given value. It takes one operand of
+ floating point type (i.e., scalar, tensor or vector) and returns one result of
+ the same type.
Example:
```mlir
+ // Scalar log2 operation.
%y = math.log2 %x : f64
```
}];
@@ -671,22 +577,15 @@ def Math_PowFOp : Math_FloatBinaryOp<"powf"> {
operation ::= ssa-id `=` `math.powf` ssa-use `,` ssa-use `:` type
```
- The `powf` operation takes two operands and returns one result, each of
- these is required to be the same type. This type may be a floating point
- scalar type, a vector whose element type is a floating point type, or a
- floating point tensor.
+ The `powf` operation takes two operands of floating point type (i.e.,
+ scalar, tensor or vector) and returns one result of the same type. Operands
+ must have the same type.
Example:
```mlir
// Scalar exponentiation.
%a = math.powf %b, %c : f64
-
- // SIMD pointwise vector exponentiation
- %f = math.powf %g, %h : vector<4xf32>
-
- // Tensor pointwise exponentiation.
- %x = math.powf %y, %z : tensor<4x?xbf16>
```
}];
let hasFolder = 1;
@@ -700,9 +599,15 @@ def Math_RsqrtOp : Math_FloatUnaryOp<"rsqrt"> {
let summary = "reciprocal of sqrt (1 / sqrt of the specified value)";
let description = [{
The `rsqrt` operation computes the reciprocal of the square root. It takes
- one operand and returns one result of the same type. This type may be a
- float scalar type, a vector whose element type is float, or a tensor of
- floats. It has no standard attributes.
+ one operand of floating point type (i.e., scalar, tensor or vector) and returns
+ one result of the same type. It has no standard attributes.
+
+ Example:
+
+ ```mlir
+ // Scalar reciprocal square root value.
+ %a = math.rsqrt %b : f64
+ ```
}];
}
@@ -713,20 +618,15 @@ def Math_RsqrtOp : Math_FloatUnaryOp<"rsqrt"> {
def Math_SqrtOp : Math_FloatUnaryOp<"sqrt"> {
let summary = "sqrt of the specified value";
let description = [{
- The `sqrt` operation computes the square root. It takes one operand and
- returns one result of the same type. This type may be a float scalar type, a
- vector whose element type is float, or a tensor of floats. It has no standard
- attributes.
+ The `sqrt` operation computes the square root. It takes one operand of
+ floating point type (i.e., scalar, tensor or vector) and returns one result of
+ the same type. It has no standard attributes.
Example:
```mlir
// Scalar square root value.
%a = math.sqrt %b : f64
- // SIMD vector element-wise square root value.
- %f = math.sqrt %g : vector<4xf32>
- // Tensor element-wise square root value.
- %x = math.sqrt %y : tensor<4x?xf32>
```
}];
let hasFolder = 1;
@@ -740,21 +640,14 @@ def Math_TanhOp : Math_FloatUnaryOp<"tanh"> {
let summary = "hyperbolic tangent of the specified value";
let description = [{
The `tanh` operation computes the hyperbolic tangent. It takes one operand
- and returns one result of the same type. This type may be a float scalar
- type, a vector whose element type is float, or a tensor of floats. It has
- no standard attributes.
+ of floating point type (i.e., scalar, tensor or vector) and returns one
+ result of the same type. It has no standard attributes.
Example:
```mlir
// Scalar hyperbolic tangent value.
%a = math.tanh %b : f64
-
- // SIMD vector element-wise hyperbolic tangent value.
- %f = math.tanh %g : vector<4xf32>
-
- // Tensor element-wise hyperbolic tangent value.
- %x = math.tanh %y : tensor<4x?xf8>
```
}];
}
More information about the Mlir-commits
mailing list