API Ref Update for Version 6.0 (apple#1606)

* API Ref Update for Version 6.0 * Edits to README.md and tensor_transformation
RobertRiachi · Sep 21, 2022 · f700774 · f700774
1 parent 484be5c
commit f700774
Show file tree

Hide file tree

Showing 11 changed files with 130 additions and 116 deletions.
diff --git a/README.md b/README.md
@@ -23,26 +23,22 @@ With coremltools, you can do the following:
 
 After conversion, you can integrate the Core ML models with your app using Xcode.
 
-## Version 5
 
-The coremltools 5 package offers several performance improvements over previous versions, including the following new features: 
+## Version 6
+
+The coremltools 6 package offers new features to optimize the model conversion process. For details, see [New in coremltools](https://coremltools.readme.io/docs/new-in-coremltools).
 
-* [Core ML model package](https://coremltools.readme.io/docs/new-in-coremltools#save-a-core-ml-model-package): A new model container format that separates the model into components and offers more flexible metadata editing and better source control.
-* [ML program](https://coremltools.readme.io/docs/ml-programs): A new model type that represents computation as programmatic instructions, offers more control over the precision of its intermediate tensors and better performance. 
+For a full list of changes, see [Release Notes](https://github.com/apple/coremltools/releases/). 
 
-To install coremltools, use the following command in your terminal:
+To install [coremltools 6.0](https://github.com/apple/coremltools/releases/tag/6.0) use the following command:
 
 ```shell
 pip install coremltools
 ```
 
-## Version 6
-
-To install [the second beta of coremltools 6.0](https://github.com/apple/coremltools/releases/tag/6.0b2) use the following command in your terminal:
+## Version 5
 
-```shell
-pip install coremltools==6.0b2
-```
+The coremltools 5 package offers several performance improvements over previous versions, including new features. For details, see [New in coremltools](https://coremltools.readme.io/docs/new-in-coremltools).
 
 
 ## Core ML

diff --git a/coremltools/converters/mil/mil/ops/defs/iOS15/image_resizing.py b/coremltools/converters/mil/mil/ops/defs/iOS15/image_resizing.py
@@ -469,13 +469,13 @@ class crop_resize(Operation):
           coordinate corresponds to the top-left corner of the image.
         * This parameter can take one of four values:
 
-          "CORNERS_HEIGHT_FIRST": ``[h_start, w_start, h_end, w_end]``
+          ``"CORNERS_HEIGHT_FIRST"``: ``[h_start, w_start, h_end, w_end]``
 
-          "CORNERS_WIDTH_FIRST": ``[w_start, h_start, w_end, h_end]``
+          ``"CORNERS_WIDTH_FIRST"``: ``[w_start, h_start, w_end, h_end]``
 
-          "CENTER_SIZE_HEIGHT_FIRST": ``[h_center, w_center, box_height, box_width]``
+          ``"CENTER_SIZE_HEIGHT_FIRST"``: ``[h_center, w_center, box_height, box_width]``
 
-          "CENTER_SIZE_WIDTH_FIRST": ``[w_center, h_center, box_width, box_height]``
+          ``"CENTER_SIZE_WIDTH_FIRST"``: ``[w_center, h_center, box_width, box_height]``
 
     sampling_mode : const<str> (Optional, default="DEFAULT")
         * This parameter can take ``"STRICT_ALIGN_CORNERS"``,
@@ -644,7 +644,7 @@ class affine(Operation):
     value at the coordinate ``(x’,y’)`` in the input image using either bilinear or
     nearest neighbor interpolation. If the ``(x’, y’)`` point falls outside the input
     image, then padding information is used to compute the value.
-    
+
     .. sourcecode:: python
 
         * x’ = a0 * x + a1 * y + a2
@@ -792,7 +792,7 @@ class resample(Operation):
         * Coordinate (normalized or unnormalized) should be specified according
           to ``coordinates_mode``.
     sampling_mode: const<str>
-        * Allowed values: ``"bilinear" , "nearest"``
+        * Allowed values: ``"bilinear"`` , ``"nearest"``
     padding_mode: const<str>
         * Allowed values: ``"constant"``, ``"border"``, ``"reflection"``, ``"symmetric"``
         * Note that the following example is 1D case for brevity.

diff --git a/coremltools/converters/mil/mil/ops/defs/iOS15/tensor_operation.py b/coremltools/converters/mil/mil/ops/defs/iOS15/tensor_operation.py
@@ -96,16 +96,16 @@ class cumsum(Operation):
     x: tensor<\*?, T> (Required)
         * Input tensor.
     axis: const<i32> (Optional)
-        * default to ``0``.
+        * Defaults to ``0``.
         * Axis for which the cumulative sum is computed.
     exclusive: const<bool> (Optional)
-        * Default to ``False``.
+        * Defaults to ``False``.
         * When set to ``False``, inclusive cumsum is computed, that is the first element of
           the output is identical to the first element in the input.
         * When set to ``True``, exclusive cumsum is computed, which makes the first element
           of output to ``0``.
     reverse: const<bool> (Optional)
-        * Default to ``False``.
+        * Defaults to ``False``.
         * When set to ``True``, perform cumsum in the reverse order.
 
     Returns
@@ -173,7 +173,7 @@ class fill(Operation):
         * Target output tensor shape.
         * ``K`` is the rank of the output tensor. ``shape[k] > 0`` for ``k = 0,..., K-1``.
     value: const<T> (Optional)
-        * Default to ``0.0``.
+        * Defaults to ``0.0``.
         * Constant value to fill in.
 
     Returns
@@ -244,7 +244,7 @@ class non_maximum_suppression(Operation):
         * Maximum number of boxes to select. If the number of surviving boxes are
           less, output is padded up to this number.
     per_class_suppression: const<bool> (Optional)
-        * Default to ``False``.
+        * Defaults to ``False``.
         * If ``True``, suppression is performed independently within boxes of each class.
 
     Returns
@@ -348,12 +348,12 @@ class one_hot(Operation):
     axis: const i32 (Optional)
         * Indicates which dimension to append the new axis.
         * If the input indices is rank ``D``, the output tensor will have rank ``D+1``.
-        * Default to ``-1`` (the last dimension).
+        * Defaults to ``-1`` (the last dimension).
     on_value: const T (Optional)
         * Values for locations where defined in ``indices``.
-        * Default to ``1``.
+        * Defaults to ``1``.
     off_value: const T (Optional)
-        * Default to ``0``.
+        * Defaults to ``0``.
 
     Returns
     -------
@@ -433,20 +433,20 @@ class pad(Operation):
         ``N <= D_in``. Last ``N`` dimensions of ``x`` are padded as follows:
         
         * For each dimension ``i`` of ``x`` if ``i >= D_in - N``:
-            * pad ``pad[2*i]`` elements before ``x[..,i,..]``
-            * pad ``pad[2*i+1]`` elements after ``x[..,i,..]``
+            * pad ``pad[2*i]`` elements before ``x[..,i,..]``.
+            * pad ``pad[2*i+1]`` elements after ``x[..,i,..]``.
         * If mode is "reflect" then ``pad[2*i]`` and ``pad[2*i+1]`` can be at
           most ``D[i]-1``.
         * If mode is "replicate" then ``pad[2*i]`` and ``pad[2*i+1]`` can be
           at most ``D[i]``.
 
     mode: const<str> (Optional)
-        * Default to ``constant``.
+        * Defaults to ``constant``.
         * Must be one of the following values:
           ``constant``, ``reflect``, or ``replicate``.
 
     constant_val: const<T> (Optional)
-        * Default to ``0``.
+        * Defaults to ``0``.
         * Constant value to pad. Ignored if ``mode != constant``.
 
     Returns
@@ -680,11 +680,11 @@ class argsort(Operation):
     x: <\*?, T> (Required)
         * Input tensor.
     * axis: const<i32> (Optional)
-        * Default to ``-1`` (the last dimension).
+        * Defaults to ``-1`` (the last dimension).
         * Axis to perform the operation.
     * ascending: const<bool> (Optional)
-        * Default to ``False``, sort in descending order. ``True`` to sort in
-          ascending order.
+        * Defaults to ``False``, sort in descending order.
+        * ``True`` to sort in ascending order.
 
     Returns
     -------
@@ -734,14 +734,14 @@ class topk(Operation):
     x: <\*?, T> (Required)
         * Input tensor.
     k: const<i32> (Optional)
-        * Default to ``1``.
+        * Defaults to ``1``.
         * Number of values/indices to be computed along each axis.
-    * axis: const<i32> (Optional)
+    axis: const<i32> (Optional)
         * Defaults to ``-1`` (last dimension).
         * Axis to perform the operation.
-    * ascending: const<bool> (Optional)
-        * Default to ``False``, sort in descending order. ``True`` to sort in
-          ascending order.
+    ascending: const<bool> (Optional)
+        * Defaults to ``False``, sort in descending order.
+        * ``True`` to sort in ascending order.
 
     Returns
     -------
@@ -809,7 +809,7 @@ class flatten2d(Operation):
     ----------
     x: tensor<[*d], T> (Required)
         * Input tensor.
-    * axis: const<i32>  (Optional)
+    axis: const<i32>  (Optional)
         * Defaults to ``1``.
         * Negative axis is supported.
 
@@ -867,7 +867,7 @@ def value_inference(self):
 @register_op
 class shape(Operation):
     """
-    Returns a 1-dimensional tensor with the shape of the input tensor
+    Returns a 1-dimensional tensor with the shape of the input tensor.
 
     Parameters
     ----------
@@ -922,8 +922,8 @@ class concat(Operation):
         * The dimension along which to concatenate. Must be in the range
           ``[-rank(values[i]), rank(values[i]))`` for all ``i``.
     interleave: const<bool> (Optional, Default=False)
-        * If true, concatenate the inputs by interleaving them.
-        * If true, all the inputs to this op must have the exact same shape.
+        * If True, concatenate the inputs by interleaving them.
+        * If True, all the inputs to this op must have the exact same shape.
 
     Examples
     --------

diff --git a/coremltools/converters/mil/mil/ops/defs/iOS16/constexpr_ops.py b/coremltools/converters/mil/mil/ops/defs/iOS16/constexpr_ops.py
@@ -51,7 +51,7 @@ class constexpr_affine_dequantize(Operation):
     Returns
     -------
     const tensor<DstT, [1..]>
-  
+
     Attributes
     ----------
     SrcT: uint8, int8
@@ -202,7 +202,7 @@ class constexpr_lut_to_dense(Operation):
     * ``NUM_PALETTES`` can be one of ``{2, 4, 16, 64 or 256}``.
     * ``n_bits = log2(NUM_PALETTES)`` can thus be one of ``{1, 2, 4, 6, 8}``.
     * Indices are packed in bytes of size ``M``, where ``M = ceil(n_bits * product(shape) / 8)``.
-    
+
     The bit fields are packed one byte at a time, starting with the least significant bit (LSB) and
     moving upward to the most significant bit (MSB). It follows, naturally, that if an index is split
     across two bytes, the LSBs of that index is filled over the MSBs of current byte, and the remaining

diff --git a/coremltools/converters/mil/mil/ops/defs/iOS16/tensor_operation.py b/coremltools/converters/mil/mil/ops/defs/iOS16/tensor_operation.py
@@ -25,14 +25,14 @@
 @register_op(opset_version=_IOS16_TARGET)
 class fill_like(Operation):
     """
-    Returns a tensor with the same size as the input tensor filled with a constant value
+    Returns a tensor with the same size as the input tensor filled with a constant value.
 
     Parameters
     ----------
     ref_tensor: tensor<\*?, T> (Required)
         * Input tensor.
     value: const<U> (Optional)
-        * Default to ``0.0``.
+        * Default is ``0.0``.
         * Constant value to fill in.
 
     Returns
@@ -73,18 +73,19 @@ class topk(_topk_iOS15):
     """
     A version of ``topk`` for iOS 16+. This section documents the differences. For the
     rest of the documentation, see `the iOS 15 version of topk <#coremltools.converters.mil.mil.ops.defs.iOS15.tensor_operation.topk>`_.
+
     Parameters
     ----------
-       * The following are additional parameters for the iOS 16+ version. (For more parameters, see
-         `the iOS 15 version of topk <#coremltools.converters.mil.mil.ops.defs.iOS15.tensor_operation.topk>`_.)
+    The following are additional parameters for the iOS 16+ version. (For more parameters,
+    see `the iOS 15 version of topk <#coremltools.converters.mil.mil.ops.defs.iOS15.tensor_operation.topk>`_.)
     
     sort: const<bool> (Optional)
-        * Default to ``True``.
+        * Defaults to ``True``.
         * If ``True``, ``top-k`` elements are themselves sorted.
           Otherwise, no particular ordering is guaranteed.
     return_indices: const<bool> (Optional)
-        * Default to ``True``.
-        * If ``True`, returns both values and indices. Otherwise, returns only the ``top-k`` values.
+        * Defaults to ``True``.
+        * If ``True``, returns both values and indices. Otherwise, returns only the ``top-k`` values.
 
     Returns
     -------

diff --git a/coremltools/converters/mil/mil/ops/defs/iOS16/tensor_transformation.py b/coremltools/converters/mil/mil/ops/defs/iOS16/tensor_transformation.py
@@ -20,51 +20,57 @@
 @register_op(opset_version=_IOS16_TARGET)
 class reshape_like(Operation):
     """
-    Reshape a tensor to a output shape specified by some or all dimensions of a tuple of reference tensors ``ref_tensors``.
-    
+    Reshape a tensor to an output shape specified by some or all dimensions of a tuple of reference tensors ``ref_tensors``.
+
     Parameters
     ----------
     x: tensor<\*?, T> (Required)
         * The input tensor to be reshaped.
 
     ref_tensors: Tuple[tensor<\*?, R>] (Required)
         * A tuple of tensors that define the output shape.
-        
+
     begins: Tuple[const<int32>] (Required)
-        * A tuple of integers specifying the begin index into the shape vector of the corresponding ref_tensor.
-        
+        * A tuple of integers specifying the begin index into the shape vector of the corresponding ``ref_tensor``.
+
     ends: Tuple[const<int32>] (Required)
-        * A tuple of integers specifying the end index into the shape vector of the corresponding ref_tensor.
-        
+        * A tuple of integers specifying the end index into the shape vector of the corresponding ``ref_tensor``.
+
     end_masks: Tuple[const<bool>] (Required)
-        * If true, select all axes from begin until the end of the corresponding ref_tensor.
-           i.e. ref_tensors[i].shape[begins[i]:]
-           
-    The output shape is computed by the following way:
-    
-    ```
-    output_shape = []
-    num_of_refs = len(begins)
-    for i in range(num_of_refs):
-        if end_masks[i]:
-            output_shape.append(ref_tensor_i.shape[begins[i]:])
-        else:
-            output_shape.append(ref_tensor_i.shape[begins[i]:ends[i]])
-    output_shape = np.concat(output_shape, axis=0)
-    ```
-           
-    Here is an example:
-    ``ref_tensors=[tensor[2, 3, 4], tensor[1, 5, 6]]``
-    ``begins=[0, 1]``
-    ``ends=[2, 0]``
-    ``end_masks=[False, True]``
-    The output shape would be ``(2, 3, 5, 6)``
+        * If ``True``, select all axes from the begin index until the end of the corresponding ``ref_tensor``, as in
+          ``ref_tensors[i].shape[begins[i]:]``.
+
+    Notes
+    -----
+    The output shape is computed as follows:
+
+    .. sourcecode:: python
+
+        output_shape = []
+        num_of_refs = len(begins)
+        for i in range(num_of_refs):
+            if end_masks[i]:
+                output_shape.append(ref_tensor_i.shape[begins[i]:])
+            else:
+                output_shape.append(ref_tensor_i.shape[begins[i]:ends[i]])
+        output_shape = np.concat(output_shape, axis=0)
+
+    The following is an example:
+
+    .. sourcecode:: python
+
+        ref_tensors=[tensor[2, 3, 4], tensor[1, 5, 6]]
+        begins=[0, 1]``
+        ends=[2, 0]``
+        end_masks=[False, True]
+
+    The output shape would be ``(2, 3, 5, 6)``.
 
     Returns
     -------
     tensor<\*?, T>
-        * Same type as input tensor ``x``
-        * Output shape is computed by ``ref_tensors, begins, ends, and end_masks``
+        * Same type as input tensor ``x``.
+        * Output shape is computed by ``ref_tensors``, ``begins``, ``ends``, and ``end_masks``.
 
     Attributes
     ----------
@@ -147,6 +153,7 @@ class pixel_unshuffle(Operation):
     ----------
     x: tensor<[n, C, H / f , W / f], T> (Required)
         * Input tensor of rank ``4``.
+
     downscale_factor: const<i32>
         * Factor to decrease spatial resolution by.