@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/apple-on-device-ai/references/coreml-conversion.md

@@ -1,431 +1,324 @@
-# Core ML Model Conversion Reference
+# Core ML conversion with coremltools
 
-Complete reference for converting models to Core ML format using coremltools.
-Use this reference for Python-side export, conversion, deployment-target,
-shape, and compression decisions. For Swift app runtime wiring, hand off to the
-sibling `coreml` skill; in conversion reviews, describe runtime availability in
-prose unless the user explicitly asks for Swift integration code.
+This file is about the Python side: exporting from the training framework,
+converting, choosing a deployment target and input shapes, and preparing for
+compression. Swift runtime wiring belongs to the `coreml` skill. In a
+conversion review, describe what the app needs at runtime in prose unless the
+user asked for Swift code.
 
 ## Contents
 
-- [coremltools Installation](#coremltools-installation)
-- [Architecture Overview](#architecture-overview)
-- [Model Formats](#model-formats)
-- [Unified Conversion API](#unified-conversion-api)
-- [Converting from PyTorch](#converting-from-pytorch)
-- [Converting from TensorFlow](#converting-from-tensorflow)
-- [Converting from scikit-learn](#converting-from-scikit-learn)
-- [Converting from XGBoost](#converting-from-xgboost)
-- [ONNX Conversion (Deprecated)](#onnx-conversion-deprecated)
-- [Input and Output Types](#input-and-output-types)
-- [Flexible Input Shapes](#flexible-input-shapes)
-- [Deployment Targets](#deployment-targets)
-- [Compute Precision](#compute-precision)
-- [Compute Units](#compute-units)
-- [Stateful Models (iOS 18+)](#stateful-models-ios-18)
-- [Multifunction Models (iOS 18+)](#multifunction-models-ios-18)
-- [Model Utilities](#model-utilities)
-- [Graph Pass Control](#graph-pass-control)
-- [Custom Composite Operators](#custom-composite-operators)
-- [Common Mistakes to Avoid](#common-mistakes-to-avoid)
-
-## coremltools Installation
+- [Installing coremltools](#installing-coremltools)
+- [Where Core ML sits](#where-core-ml-sits)
+- [ML program versus neural network](#ml-program-versus-neural-network)
+- [ct.convert parameters](#ctconvert-parameters)
+- [From PyTorch](#from-pytorch)
+- [From TensorFlow, scikit-learn and XGBoost](#from-tensorflow-scikit-learn-and-xgboost)
+- [ONNX](#onnx)
+- [Describing inputs and outputs](#describing-inputs-and-outputs)
+- [Flexible shapes](#flexible-shapes)
+- [Deployment targets](#deployment-targets)
+- [Float16 or Float32](#float16-or-float32)
+- [Which processors to allow](#which-processors-to-allow)
+- [Keeping state between predictions](#keeping-state-between-predictions)
+- [Several functions in one package](#several-functions-in-one-package)
+- [Utilities](#utilities)
+- [Controlling graph passes](#controlling-graph-passes)
+- [Unsupported PyTorch ops](#unsupported-pytorch-ops)
+- [Conversion mistakes](#conversion-mistakes)
+
+## Installing coremltools
+
+Install into a fresh virtual environment and check the published wheels against
+your Python version and the version of the source framework:
 
 ```bash
+python3 -m venv .venv && source .venv/bin/activate
 pip install coremltools
 ```
 
-Use a fresh virtual environment and verify the wheel matrix for your Python and
-source-framework versions. The 9.0 release publishes wheels through CPython
-3.13 and adds iOS 26 / macOS 26 deployment targets.
+coremltools 9.0 has wheels up to CPython 3.13 and adds the iOS 26 and macOS 26
+deployment targets.
 
-## Architecture Overview
+## Where Core ML sits
 
-```text
-Your App (SwiftUI / UIKit)
-  |-- Vision, Natural Language, SoundAnalysis, Foundation Models
-  |-- Core ML (model loading, prediction, compilation)
-  |-- Metal Performance Shaders Graph (GPU) / Accelerate (CPU) / Neural Engine (ANE)
-```
-
-## Model Formats
-
-| Format | Extension | Model Type | When to Use |
-|---|---|---|---|
-| `.mlpackage` | Directory | mlprogram | All new models (iOS 15+) |
-| `.mlmodel` | Single file | neuralnetwork | Legacy only (iOS 11-14) |
-| `.mlmodelc` | Compiled | Either | Pre-compiled for faster loading |
-
-Always use mlprogram (.mlpackage) for new work. Neural network format is frozen
-and receives no new features.
+Higher-level frameworks (SoundAnalysis, Natural Language, Vision and
+Foundation Models) are built on Core ML. Core ML in turn runs each operation on
+the CPU through Accelerate, on the GPU through MPS Graph, or on the Neural
+Engine.
 
-### mlprogram vs neuralnetwork
+## ML program versus neural network
 
-| Aspect | neuralnetwork | mlprogram |
+| Aspect | Neural network (`.mlmodel`) | ML program (`.mlpackage`) |
 |---|---|---|
-| GPU precision | Float16 only | Float16 and Float32 |
-| Optimization APIs | Limited | Full (quantize, palettize, prune) |
-| Stateful models | No | Yes (iOS 18+) |
-| Multifunction models | No | Yes (iOS 18+) |
-| On-device training | Supported | Not supported |
-| Weight storage | Embedded in protobuf | Separated (memory-efficient) |
+| Status | Frozen, no new features | Current format |
+| GPU precision | Float16 only | Float16 or Float32 |
+| Compression APIs | Limited | Quantize, palettize and prune |
+| Where weights live | Inside the protobuf | Separate files, lighter on memory |
+| Training on the device | Yes | No |
+| State and multiple functions | No | Yes, from iOS 18 |
 
-## Unified Conversion API
+## ct.convert parameters
 
-```python
-import coremltools as ct
-
-mlmodel = ct.convert(
-    model,                          # PyTorch traced/exported model or TF model
-    source='auto',                  # 'auto', 'pytorch', 'tensorflow'
-    inputs=None,                    # list of TensorType/ImageType
-    outputs=None,                   # list of TensorType/ImageType
-    minimum_deployment_target=None, # ct.target.iOS15 through ct.target.iOS26
-    convert_to='mlprogram',         # 'mlprogram' (default) or 'neuralnetwork'
-    compute_precision=None,         # ct.precision.FLOAT16 (default), FLOAT32
-    compute_units=ct.ComputeUnit.ALL,
-    skip_model_load=False,          # True when converting on Linux
-    states=None,                    # list of StateType for stateful models
-    pass_pipeline=None,             # PassPipeline for graph optimization
-)
-mlmodel.save("Model.mlpackage")
-```
+| Parameter | Values |
+|---|---|
+| `source` | `"auto"`, `"pytorch"`, `"tensorflow"` |
+| `inputs`, `outputs` | Lists of `ct.TensorType` or `ct.ImageType` |
+| `convert_to` | `"mlprogram"` (default) or `"neuralnetwork"` |
+| `minimum_deployment_target` | any `ct.target` value from iOS15 up to iOS26 |
+| `compute_precision` | `ct.precision.FLOAT16` (default) or `FLOAT32` |
+| `compute_units` | `ct.ComputeUnit.ALL` and the other unit sets |
+| `skip_model_load` | `True` when converting on Linux, where the model cannot be loaded |
+| `states` | List of `ct.StateType` |
+| `pass_pipeline` | A `ct.PassPipeline` |
 
-## Converting from PyTorch
+## From PyTorch
 
-### torch.jit.trace (Recommended)
+Tracing is the recommended route:
 
 ```python
 import torch
 import coremltools as ct
 
-model = MyModel()
-model.eval()  # CRITICAL: always call eval() before tracing
-
-example_input = torch.rand(1, 3, 224, 224)
-traced_model = torch.jit.trace(model, example_input)
+model = load_keyword_spotter()
+model.eval()
+clip = torch.randn(1, 1, 16000)
+traced = torch.jit.trace(model, clip)
 
-mlmodel = ct.convert(
-    traced_model,
-    inputs=[ct.TensorType(shape=example_input.shape, name="input")],
+spotter = ct.convert(
+    traced,
     minimum_deployment_target=ct.target.iOS16,
+    inputs=[ct.TensorType(name="audio", shape=clip.shape)],
 )
-mlmodel.save("MyModel.mlpackage")
+spotter.save("KeywordSpotter.mlpackage")
 ```
 
-### torch.export (Beta)
+`torch.export` is supported in beta. Dynamic dimensions are declared when you
+export and become `RangeDim` automatically:
 
 ```python
-import torch
-import coremltools as ct
-
-model.eval()
-example_inputs = (torch.rand(1, 3, 224, 224),)
+from torch.export import Dim, export
 
-# Dynamic shapes defined at export time
-batch_dim = torch.export.Dim(name="batch", min=1, max=128)
-exported = torch.export.export(model, example_inputs,
-    dynamic_shapes={"x": {0: batch_dim}})
-
-mlmodel = ct.convert(exported)
+length = Dim(name="length", min=4000, max=48000)
+exported = export(model, (clip,), dynamic_shapes={"x": {2: length}})
+spotter = ct.convert(exported, minimum_deployment_target=ct.target.iOS17)
 ```
 
-Key difference: `torch.export` defines dynamic shapes upfront (auto-converted
-to RangeDim). `torch.jit.trace` defines shapes in `ct.convert()` via
-RangeDim/EnumeratedShapes.
-
-## Converting from TensorFlow
-
-```python
-import tensorflow as tf
-import coremltools as ct
-
-# Keras model
-tf_model = tf.keras.applications.MobileNetV2()
-mlmodel = ct.convert(tf_model)
+With `export`, shapes are fixed up front; with `trace`, you express flexibility
+inside `ct.convert()` using `RangeDim` or `EnumeratedShapes`.
 
-# SavedModel directory
-mlmodel = ct.convert("/path/to/saved_model/")
+## From TensorFlow, scikit-learn and XGBoost
 
-# HDF5 file
-mlmodel = ct.convert("/path/to/model.h5")
+TensorFlow: `ct.convert` accepts a Keras model object, a SavedModel directory,
+an `.h5` file, or a frozen `.pb` graph (the last needs explicit `inputs`).
 
-# Frozen graph (.pb)
-mlmodel = ct.convert("frozen_graph.pb",
-    inputs=[ct.TensorType(shape=(1, 224, 224, 3))])
+```python
+keras_net = tf.keras.models.load_model("leaf_classifier.keras")
+leaf = ct.convert(keras_net, minimum_deployment_target=ct.target.iOS17)
 ```
 
-## Converting from scikit-learn
+scikit-learn converts to the older `.mlmodel` format:
 
 ```python
-from sklearn.linear_model import LinearRegression
-import coremltools as ct
-
-model = LinearRegression()
-model.fit(X_train, y_train)
-
-mlmodel = ct.converters.sklearn.convert(
-    model, ["feature1", "feature2"], "prediction"
-)
-mlmodel.save("Regressor.mlmodel")
+price = ct.converters.sklearn.convert(forest, ["rooms", "area", "age"], "price")
+price.save("HousePrice.mlmodel")
 ```
 
-## Converting from XGBoost
+XGBoost:
 
 ```python
-import xgboost
-import coremltools as ct
-
-model = xgboost.XGBClassifier()
-model.fit(X_train, y_train)
-mlmodel = ct.converters.xgboost.convert(model)
+churn = ct.converters.xgboost.convert(booster)
 ```
 
-## ONNX Conversion (Deprecated)
-
-ONNX direct conversion is deprecated since coremltools 6. Convert from the
-original framework (PyTorch or TensorFlow) instead. If you only have an ONNX
-file, convert back to PyTorch first using `onnx2torch`.
+## ONNX
 
-## Input and Output Types
+coremltools stopped supporting direct ONNX input in version 6, so go back to
+the framework the model was trained in. If ONNX is all you have, convert it back to PyTorch
+with `onnx2torch` and trace that.
 
-### TensorType
-
-```python
-ct.TensorType(
-    name="input",              # must match model input name
-    shape=(1, 3, 224, 224),    # tuple of int, RangeDim, or EnumeratedShapes
-    dtype=np.float32,          # np.float32, np.float16, np.int32, np.int8 (iOS26+)
-    default_value=None,        # np.ndarray: makes input optional at runtime
-)
-```
+## Describing inputs and outputs
 
-### ImageType
+`ct.TensorType(name=, shape=, dtype=, default_value=)`:
 
-```python
-ct.ImageType(
-    name="image",
-    shape=(1, 3, 224, 224),
-    scale=1/255.0,                   # per-channel scaling
-    bias=[-0.485/0.229, -0.456/0.224, -0.406/0.225],  # ImageNet normalization
-    color_layout=ct.colorlayout.RGB, # RGB, BGR, GRAYSCALE, GRAYSCALE_FLOAT16
-    channel_first=True,              # True for PyTorch (NCHW), False for TF (NHWC)
-)
-```
+- `name` must match the model's input name.
+- `shape` takes fixed integers, `RangeDim` or `EnumeratedShapes`.
+- `dtype`: `np.int32`, `np.float16` or `np.float32`, plus `np.int8` from iOS 26.
+- `default_value` (a NumPy array) makes the input optional.
 
-### StateType (iOS 18+)
+`ct.ImageType(name=, shape=, scale=, bias=, color_layout=, channel_first=)`:
 
 ```python
-ct.StateType(
-    wrapped_type=ct.TensorType(shape=(1, 8, 128, 64), dtype=np.float16),
-    name="kv_cache",
+photo = ct.ImageType(
+    name="photo",
+    shape=(1, 3, 320, 320),
+    scale=1 / 127.5,
+    bias=[-1.0, -1.0, -1.0],             # maps pixels to the range -1...1
+    color_layout=ct.colorlayout.RGB,
+    channel_first=True,
 )
 ```
 
-## Flexible Input Shapes
+- Colour layouts: `GRAYSCALE`, `GRAYSCALE_FLOAT16`, `RGB` or `BGR`.
+- PyTorch models are NCHW, so pass `channel_first=True`; TensorFlow's NHWC
+  needs `False`.
 
-### Fixed Shape
-
-```python
-inputs=[ct.TensorType(shape=(1, 3, 224, 224))]
-```
+`ct.StateType(wrapped_type=ct.TensorType(...), name=)` (iOS 18+) declares
+state, for example a float16 `kv_cache` tensor.
 
-### RangeDim (Variable Dimensions)
+## Flexible shapes
 
 ```python
-inputs=[ct.TensorType(shape=(
-    1, 3,
-    ct.RangeDim(lower_bound=128, upper_bound=512, default=224),
-    ct.RangeDim(lower_bound=128, upper_bound=512, default=224),
-))]
-```
+fixed = ct.TensorType(name="x", shape=(1, 3, 512, 512))
 
-### EnumeratedShapes (Best Performance)
+side = ct.RangeDim(lower_bound=256, upper_bound=1024, default=512)
+ranged = ct.TensorType(name="x", shape=(1, 3, side, side))
 
-```python
-inputs=[ct.TensorType(shape=ct.EnumeratedShapes(
-    shapes=[(1,3,224,224), (1,3,384,384), (1,3,512,512)],
-    default=(1,3,224,224),
-))]
+sizes = [(1, 3, s, s) for s in (256, 512, 1024)]
+listed = ct.TensorType(name="x", shape=ct.EnumeratedShapes(shapes=sizes, default=sizes[1]))
 ```
 
-**Rule:** Prefer EnumeratedShapes over RangeDim when you have a known set of
-sizes. EnumeratedShapes allows the Neural Engine to optimize for each shape at
-compilation time. RangeDim only optimizes for the default shape.
-
-**Rule:** Before iOS 18, only ONE input can use EnumeratedShapes. Starting
-iOS 18, multiple inputs can use EnumeratedShapes.
+When the real sizes are known, list them with `EnumeratedShapes`: the Neural
+Engine compiles an optimised plan for each listed shape, while with `RangeDim`
+only the default shape gets that treatment. Until iOS 18,
+`EnumeratedShapes` was limited to a single input; newer targets allow it on
+several.
 
-## Deployment Targets
+## Deployment targets
 
-| Target | Model Type | Key Feature Unlocks |
+| iOS target | Matching macOS target | What it unlocks |
 |---|---|---|
-| `ct.target.iOS13` | neuralnetwork | Basic neural network |
-| `ct.target.iOS15` | mlprogram | FP16 precision, typed tensors |
-| `ct.target.iOS16` | mlprogram | Palettized weights, sparse weights |
-| `ct.target.iOS17` | mlprogram | W8A8 activation quantization (A17 Pro+) |
-| `ct.target.iOS18` | mlprogram | Stateful models, multifunction, per-block quantization |
-| `ct.target.iOS26` | mlprogram | INT8 I/O dtype, state read/write |
+| `ct.target.iOS13` | `ct.target.macOS10_15` | Neural network models only |
+| `ct.target.iOS15` | `ct.target.macOS12` | ML program, FP16, typed tensors |
+| `ct.target.iOS16` | `ct.target.macOS13` | Palettized and sparse weights |
+| `ct.target.iOS17` | `ct.target.macOS14` | W8A8 activation quantization (A17 Pro and later) |
+| `ct.target.iOS18` | `ct.target.macOS15` | Stateful and multifunction models, block-wise quantization |
+| `ct.target.iOS26` | `ct.target.macOS26` | INT8 input and output types, state read and write |
 
-Corresponding macOS targets: `macOS10_15`, `macOS12`, `macOS13`, `macOS14`,
-`macOS15`, `macOS26`.
+## Float16 or Float32
 
-## Compute Precision
-
-| Value | Description |
-|---|---|
-| `ct.precision.FLOAT16` | Default for mlprogram. Smaller, faster. |
-| `ct.precision.FLOAT32` | Higher accuracy. Use when FP16 causes issues. |
-
-### Mixed Precision (Selective Per-Op)
+ML programs default to `ct.precision.FLOAT16`, which is smaller and faster. Use
+`FLOAT32` only when half precision measurably hurts accuracy. To keep just the
+sensitive ops in FP32:
 
 ```python
-def keep_layernorm_fp32(op):
-    if op.op_type == "layer_norm":
-        return False  # keep in FP32
-    return True  # convert to FP16
-
-mlmodel = ct.convert(model,
-    compute_precision=ct.transform.FP16ComputePrecision(
-        op_selector=keep_layernorm_fp32
-    ))
+def keep_norms_fp32(op):
+    return op.op_type != "layer_norm"
+
+policy = ct.transform.FP16ComputePrecision(op_selector=keep_norms_fp32)
+mixed = ct.convert(
+    traced,
+    compute_precision=policy,
+    minimum_deployment_target=ct.target.iOS17,
+    inputs=[ct.TensorType(name="tokens", shape=(1, 128))],
+)
 ```
 
-## Compute Units
+The selector returns `False` for an op that should stay in FP32.
 
-| Value | Description | When to Use |
-|---|---|---|
-| `.all` | CPU + GPU + Neural Engine | Default, recommended |
-| `.cpuOnly` | CPU exclusively | Debugging, FP32 accuracy |
-| `.cpuAndGPU` | CPU and GPU, no ANE | When ANE causes issues |
-| `.cpuAndNeuralEngine` | CPU and ANE, no GPU | Energy efficiency (macOS 13+) |
+## Which processors to allow
 
-## Stateful Models (iOS 18+)
+| Setting | When |
+|---|---|
+| `.all` | Default and recommended: CPU, GPU and Neural Engine |
+| `.cpuOnly` | Debugging, or checking FP32 reference results |
+| `.cpuAndGPU` | When the Neural Engine produces bad results |
+| `.cpuAndNeuralEngine` | Lowest energy use; macOS 13 or later |
 
-Persist intermediate values across inference runs. Critical for LLM KV-cache.
+## Keeping state between predictions
 
-### Python Conversion
+From iOS 18 a model can keep values between predictions. The main use is the
+key-value cache of a language model.
 
 ```python
-mlmodel = ct.convert(
-    traced_model,
-    inputs=[ct.TensorType(shape=(1,), name="x")],
-    outputs=[ct.TensorType(name="y")],
-    states=[ct.StateType(
-        wrapped_type=ct.TensorType(shape=(1,)),
-        name="accumulator",
-    )],
+cache = ct.StateType(
+    name="kv_cache",
+    wrapped_type=ct.TensorType(dtype=np.float16, shape=(2, 1, 16, 1024, 64)),
+)
+decoder = ct.convert(
+    traced_decoder,
     minimum_deployment_target=ct.target.iOS18,
+    states=[cache],
+    inputs=[ct.TensorType(name="token", dtype=np.int32, shape=(1, 1))],
 )
-
-# Python prediction with state
-state = mlmodel.make_state()
-result = mlmodel.predict({"x": np.array([2.0])}, state=state)
+state = decoder.make_state()
+step = decoder.predict({"token": np.array([[42]], dtype=np.int32)}, state=state)
 ```
 
-### Swift Usage
-
-```swift
-let model = try MLModel(contentsOf: modelURL, configuration: config)
-let state = model.makeState()
-let input = try MLDictionaryFeatureProvider(
-    dictionary: ["x": MLFeatureValue(double: 2.0)]
-)
-let output = try model.prediction(from: input, using: state)
-```
+On the Swift side the equivalent is `let state = model.makeState()` followed by
+`try model.prediction(from: MLDictionaryFeatureProvider(dictionary: inputs), using: state)`.
 
-Impact: Llama 3.1 with stateful KV-cache achieves 16.26 tokens/s vs 1.25
-tokens/s without (13x improvement).
+Apple's published measurement for Llama 3.1: 16.26 tokens per second with a
+stateful KV cache against 1.25 without, roughly thirteen times faster.
 
-## Multifunction Models (iOS 18+)
+## Several functions in one package
 
-Pack multiple model functions (e.g., LoRA adapters) into a single .mlpackage.
-Shared weights are deduplicated.
+Also from iOS 18, one `.mlpackage` can hold several functions that share
+deduplicated weights, for example a base model and LoRA variants:
 
 ```python
-desc = ct.utils.MultiFunctionDescriptor()
-desc.add_function("base.mlpackage", src_function_name="main",
-                  target_function_name="base")
-desc.add_function("adapter1.mlpackage", src_function_name="main",
-                  target_function_name="style_1")
-desc.default_function_name = "base"
-ct.utils.save_multifunction(desc, "combined.mlpackage")
+bundle = ct.utils.MultiFunctionDescriptor()
+for variant in ("plain", "legal"):
+    bundle.add_function(f"Drafting-{variant}.mlpackage",
+                        target_function_name=variant, src_function_name="main")
+bundle.default_function_name = "plain"
+ct.utils.save_multifunction(bundle, "Drafting.mlpackage")
 ```
 
-```swift
-let config = MLModelConfiguration()
-config.functionName = "style_1"
-let model = try MLModel(contentsOf: modelURL, configuration: config)
-```
+In Swift, pick the function with `MLModelConfiguration.functionName`.
 
-## Model Utilities
+## Utilities
 
 ```python
-# Inspect model
-spec = mlmodel.get_spec()
-print(spec.description)
-
-# Rename inputs/outputs
-ct.utils.rename_feature(spec, "old_name", "new_name")
-
-# Set metadata
-mlmodel.author = "Author"
-mlmodel.short_description = "Description"
-mlmodel.input_description["image"] = "RGB image 224x224"
-
-# Split large models for debugging
-ct.models.utils.bisect_model("large.mlpackage", "./output/")
+spec = spotter.get_spec()
+ct.utils.rename_feature(spec, "var_512", "probabilities")
 
-# Create pipeline from multiple models
-pipeline = ct.models.utils.make_pipeline(model1, model2)
-
-# Randomize weights (for testing)
-random_model = ct.models.utils.randomize_weights(mlmodel)
+spotter.author = "Audio team"
+spotter.short_description = "Wake-word detector"
+spotter.input_description["audio"] = "One second of 16 kHz mono audio"
 ```
 
-## Graph Pass Control
+- `ct.models.utils.bisect_model` splits a large model into pieces for
+  debugging.
+- `make_pipeline` chains models.
+- `randomize_weights` produces a structurally identical model for tests.
+
+## Controlling graph passes
 
 ```python
-# Skip specific optimization passes
-pipeline = ct.PassPipeline()
-pipeline.remove_passes({"common::fuse_conv_batchnorm"})
-mlmodel = ct.convert(model, pass_pipeline=pipeline)
-
-# Predefined pipelines
-ct.PassPipeline.EMPTY              # no passes
-ct.PassPipeline.CLEANUP            # minimal cleanup
-ct.PassPipeline.DEFAULT_PRUNING    # optimized for pruned models
-ct.PassPipeline.DEFAULT_PALETTIZATION  # optimized for palettized models
+passes = ct.PassPipeline()
+passes.remove_passes({"common::fuse_conv_batchnorm"})    # keep BN visible while debugging
+debuggable = ct.convert(traced, minimum_deployment_target=ct.target.iOS17,
+                        pass_pipeline=passes)
 ```
 
-## Custom Composite Operators
+Predefined pipelines: `ct.PassPipeline.EMPTY`, `CLEANUP`, `DEFAULT_PRUNING`,
+`DEFAULT_PALETTIZATION`.
 
-When PyTorch uses ops not natively supported:
+## Unsupported PyTorch ops
+
+Register a composite for an op the converter does not know, built from MIL
+builder ops:
 
 ```python
-from coremltools.converters.mil.frontend.torch.torch_op_registry import register_torch_op
 from coremltools.converters.mil.frontend.torch.ops import _get_inputs
+from coremltools.converters.mil import register_torch_op
 from coremltools.converters.mil import Builder as mb
 
 @register_torch_op
-def selu(context, node):
-    x = _get_inputs(context, node, expected=1)[0]
-    x = mb.elu(x=x, alpha=1.6732632423543772)
-    x = mb.mul(x=x, y=1.0507009873554805, name=node.name)
-    context.add(x)
+def hardswish(ctx, torch_node):
+    (value,) = _get_inputs(ctx, torch_node, expected=1)
+    gate = mb.clip(x=mb.add(x=value, y=3.0), alpha=0.0, beta=6.0)
+    scaled = mb.mul(y=gate, x=value)
+    ctx.add(mb.real_div(x=scaled, y=6.0, name=torch_node.name))
 ```
 
-## Common Mistakes to Avoid
-
-1. **Forgetting model.eval().** PyTorch models MUST be in eval mode before
-   tracing or exporting.
-2. **Using RangeDim when EnumeratedShapes would work.** Known input sizes
-   should use EnumeratedShapes for better Neural Engine performance.
-3. **Targeting neuralnetwork format for new models.** Always use mlprogram.
-4. **Not specifying minimum_deployment_target.** Always set it explicitly.
-5. **Using Float32 when Float16 suffices.** Float16 is the default and correct
-   for most models.
-6. **Converting from ONNX directly.** ONNX conversion is deprecated. Convert
-   from the original framework.
-7. **Not testing on physical devices.** Simulator does not support Metal GPU
-   or Neural Engine.
+## Conversion mistakes
+
+- Tracing or exporting without `model.eval()`.
+- `RangeDim` where `EnumeratedShapes` would do.
+- Targeting the neural network format for a new model.
+- Leaving out `minimum_deployment_target`; always set it.
+- Picking Float32 when Float16 is accurate enough.
+- Converting straight from ONNX.
+- Testing only in the Simulator, which has no Metal GPU or Neural Engine path;
+  verify on physical devices.