From f700774e2fdcc47e56ae9212c32da6383f843d35 Mon Sep 17 00:00:00 2001 From: Tony Bove <70229264+tonybove-apple@users.noreply.github.com> Date: Wed, 21 Sep 2022 13:08:31 -0700 Subject: [PATCH] API Ref Update for Version 6.0 (#1606) * API Ref Update for Version 6.0 * Edits to README.md and tensor_transformation --- README.md | 18 ++--- .../mil/mil/ops/defs/iOS15/image_resizing.py | 12 ++-- .../mil/ops/defs/iOS15/tensor_operation.py | 48 ++++++------- .../mil/mil/ops/defs/iOS16/constexpr_ops.py | 4 +- .../mil/ops/defs/iOS16/tensor_operation.py | 15 ++-- .../ops/defs/iOS16/tensor_transformation.py | 69 ++++++++++--------- coremltools/converters/sklearn/_converter.py | 52 +++++++------- coremltools/converters/xgboost/_tree.py | 10 +-- docs/_static/css/norightmargin.css | 3 + docs/conf.py | 5 +- ...oremltools.converters.mil.mil.ops.defs.rst | 10 ++- 11 files changed, 130 insertions(+), 116 deletions(-) create mode 100644 docs/_static/css/norightmargin.css diff --git a/README.md b/README.md index 0a7b30999..5265c67d5 100644 --- 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 index 15f159ab1..7823a2117 100644 --- 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 (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 - * Allowed values: ``"bilinear" , "nearest"`` + * Allowed values: ``"bilinear"`` , ``"nearest"`` padding_mode: const * 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 index 8b1f1d9bf..b7ef83475 100644 --- 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 (Optional) - * default to ``0``. + * Defaults to ``0``. * Axis for which the cumulative sum is computed. exclusive: const (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 (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 (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 (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 (Optional) - * Default to ``constant``. + * Defaults to ``constant``. * Must be one of the following values: ``constant``, ``reflect``, or ``replicate``. constant_val: const (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 (Optional) - * Default to ``-1`` (the last dimension). + * Defaults to ``-1`` (the last dimension). * Axis to perform the operation. * ascending: const (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 (Optional) - * Default to ``1``. + * Defaults to ``1``. * Number of values/indices to be computed along each axis. - * axis: const (Optional) + axis: const (Optional) * Defaults to ``-1`` (last dimension). * Axis to perform the operation. - * ascending: const (Optional) - * Default to ``False``, sort in descending order. ``True`` to sort in - ascending order. + ascending: const (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 (Optional) + axis: const (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 (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 index 7380e3c4f..88bdc0fc0 100644 --- 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 - + 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 index bc3c69dfb..a666bff18 100644 --- 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 (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 (Optional) - * Default to ``True``. + * Defaults to ``True``. * If ``True``, ``top-k`` elements are themselves sorted. Otherwise, no particular ordering is guaranteed. return_indices: const (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 index e65ae503d..21f1822c5 100644 --- a/coremltools/converters/mil/mil/ops/defs/iOS16/tensor_transformation.py +++ b/coremltools/converters/mil/mil/ops/defs/iOS16/tensor_transformation.py @@ -20,8 +20,8 @@ @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) @@ -29,42 +29,48 @@ class reshape_like(Operation): ref_tensors: Tuple[tensor<\*?, R>] (Required) * A tuple of tensors that define the output shape. - + begins: Tuple[const] (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] (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] (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 * Factor to decrease spatial resolution by. diff --git a/coremltools/converters/sklearn/_converter.py b/coremltools/converters/sklearn/_converter.py index aeab54414..4fa62c71a 100644 --- a/coremltools/converters/sklearn/_converter.py +++ b/coremltools/converters/sklearn/_converter.py @@ -44,7 +44,7 @@ def convert(sk_obj, input_features=None, output_feature_names=None): or Classifier. Note that there may not be a one-to-one correspondence between scikit - learn models and which Core ML models are used to represent them. For + learn models and the Core ML models chosen to represent them. For example, many scikit learn models are embedded in a pipeline to handle processing of input features. @@ -52,64 +52,64 @@ def convert(sk_obj, input_features=None, output_feature_names=None): input_features: str | dict | list Optional name(s) that can be given to the inputs of the scikit-learn - model. Defaults to 'input'. + model. Defaults to ``"input"``. Input features can be specified in a number of forms. - Single string: In this case, the input is assumed to be a single - array, with the number of dimensions set using num_dimensions. + array, with the number of dimensions set using ``num_dimensions``. - List of strings: In this case, the overall input dimensions to the - scikit-learn model is assumed to be the length of the list. If + scikit-learn model are assumed to be the length of the list. If neighboring names are identical, they are assumed to be an input - array of that length. For example: + array of that length. For example: - ["a", "b", "c"] + ``["a", "b", "c"]`` - resolves to + resolves to: - [("a", Double), ("b", Double), ("c", Double)]. + ``[("a", Double), ("b", Double), ("c", Double)]``. - And: + In addition: - ["a", "a", "b"] + ``["a", "a", "b"]`` - resolves to + resolves to: - [("a", Array(2)), ("b", Double)]. + ``[("a", Array(2)), ("b", Double)]``. - Dictionary: Where the keys are the names and the indices or ranges of feature indices. - In this case, it's presented as a mapping from keys to indices or - ranges of contiguous indices. For example, + In this case, the Dictionary is presented as a mapping from keys to indices or + ranges of contiguous indices. For example: - {"a" : 0, "b" : [2,3], "c" : 1} + ``{"a" : 0, "b" : [2,3], "c" : 1}`` - Resolves to + resolves to: - [("a", Double), ("c", Double), ("b", Array(2))]. + ``[("a", Double), ("c", Double), ("b", Array(2))]``. Note that the ordering is determined by the indices. - - List of tuples of the form `(name, datatype)`. Here, `name` is the - name of the exposed feature, and `datatype` is an instance of - `String`, `Double`, `Int64`, `Array`, or `Dictionary`. + - List of tuples of the form ``(name, datatype)``, in which ``name`` is the + name of the exposed feature, and ``datatype`` is an instance of + ``String``, ``Double``, ``Int64``, ``Array``, or ``Dictionary``. output_feature_names: string or list of strings - Optional name(s) that can be given to the inputs of the scikit-learn - model. + Optional name(s) that can be given to the inputs of the scikit-learn + model. - The output_feature_names is interpreted according to the model type: + The ``output_feature_names`` is interpreted according to the model type: - If the scikit-learn model is a transformer, it is the name of the array feature output by the final sequence of the transformer - (defaults to "output"). + (defaults to ``"output"``). - If it is a classifier, it should be a 2-tuple of names giving the top class prediction and the array of scores for each class (defaults to - "classLabel" and "classScores"). + ``"classLabel"`` and ``"classScores"``). - If it is a regressor, it should give the name of the prediction value - (defaults to "prediction"). + (defaults to ``"prediction"``). Returns ------- diff --git a/coremltools/converters/xgboost/_tree.py b/coremltools/converters/xgboost/_tree.py index aab2952a3..8ac68f6fb 100644 --- a/coremltools/converters/xgboost/_tree.py +++ b/coremltools/converters/xgboost/_tree.py @@ -32,7 +32,7 @@ def convert( Can be set to one of the following: - - None for using the feature names from the model. + - ``None`` for using the feature names from the model. - List of names of the input features that should be exposed in the interface to the Core ML model. These input features are in the same order as the XGboost model. @@ -41,18 +41,18 @@ def convert( Name of the output feature name exposed to the Core ML model. force_32bit_float: bool - If True, then the resulting CoreML model will use 32 bit floats internally. + If ``True``, then the resulting CoreML model will use 32 bit floats internally. mode: str in ['regressor', 'classifier'] Mode of the tree model. class_labels: list[int] or None List of classes. When set to None, the class labels are just the range from - 0 to n_classes - 1. + 0 to ``n_classes - 1``. n_classes: int or None - Number of classes in classification. When set to None, the number of - classes is expected from the model or class_labels should be provided. + Number of classes in classification. When set to ``None``, the number of + classes is expected from the model or ``class_labels`` should be provided. Returns ------- diff --git a/docs/_static/css/norightmargin.css b/docs/_static/css/norightmargin.css new file mode 100644 index 000000000..b07bdb1b5 --- /dev/null +++ b/docs/_static/css/norightmargin.css @@ -0,0 +1,3 @@ +.wy-nav-content { + max-width: none; +} diff --git a/docs/conf.py b/docs/conf.py index 33005a3b8..9401e753b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -64,4 +64,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = ['_static'] +html_css_files = [ + 'css/norightmargin.css' +] diff --git a/docs/source/coremltools.converters.mil.mil.ops.defs.rst b/docs/source/coremltools.converters.mil.mil.ops.defs.rst index c0df6b40d..5e0539103 100644 --- a/docs/source/coremltools.converters.mil.mil.ops.defs.rst +++ b/docs/source/coremltools.converters.mil.mil.ops.defs.rst @@ -136,14 +136,15 @@ image\_resizing (iOS 15) .. automodule:: coremltools.converters.mil.mil.ops.defs.iOS15.image_resizing - .. autoclass:: affine .. autoclass:: upsample_nearest_neighbor - .. autoclass:: upsample_bilinear - .. autoclass:: resample .. autoclass:: resize_nearest_neighbor + .. autoclass:: upsample_bilinear .. autoclass:: resize_bilinear .. autoclass:: crop_resize .. autoclass:: crop + .. autoclass:: affine + .. autoclass:: resample + image\_resizing (iOS 16+) -------------------------------------------------------------- @@ -267,6 +268,7 @@ tensor\_operation (iOS 16+) .. automodule:: coremltools.converters.mil.mil.ops.defs.iOS16.tensor_operation + .. autoclass:: fill_like .. autoclass:: topk @@ -294,5 +296,7 @@ tensor\_transformation (iOS 16+) .. automodule:: coremltools.converters.mil.mil.ops.defs.iOS16.tensor_transformation + .. autoclass:: reshape_like .. autoclass:: pixel_unshuffle +