ultralytics 8.3.88__py3-none-any.whl → 8.3.90__py3-none-any.whl

ultralytics/utils/torch_utils.py

@@ -90,16 +90,14 @@ def autocast(enabled: bool, device: str = "cuda"):
     Returns:
         (torch.amp.autocast): The appropriate autocast context manager.
 
-    Note:
+    Notes:
         - For PyTorch versions 1.13 and newer, it uses `torch.amp.autocast`.
         - For older versions, it uses `torch.cuda.autocast`.
 
-    Example:
-        ```python
-        with autocast(amp=True):
-            # Your mixed precision operations here
-            pass
-        ```
+    Examples:
+        >>> with autocast(enabled=True):
+        ...     # Your mixed precision operations here
+        ...     pass
     """
     if TORCH_1_13:
         return torch.amp.autocast(device, enabled=enabled)
@@ -132,7 +130,7 @@ def get_gpu_info(index):
 
 def select_device(device="", batch=0, newline=False, verbose=True):
     """
-    Selects the appropriate PyTorch device based on the provided arguments.
+    Select the appropriate PyTorch device based on the provided arguments.
 
     The function takes a string specifying the device or a torch.device object and returns a torch.device object
     representing the selected device. The function also validates the number of available devices and raises an
@@ -301,7 +299,18 @@ def fuse_deconv_and_bn(deconv, bn):
 
 
 def model_info(model, detailed=False, verbose=True, imgsz=640):
-    """Print and return detailed model information layer by layer."""
+    """
+    Print and return detailed model information layer by layer.
+
+    Args:
+        model (nn.Module): Model to analyze.
+        detailed (bool, optional): Whether to print detailed layer information. Defaults to False.
+        verbose (bool, optional): Whether to print model information. Defaults to True.
+        imgsz (int | List, optional): Input image size. Defaults to 640.
+
+    Returns:
+        (Tuple[int, int, int, float]): Number of layers, parameters, gradients, and GFLOPs.
+    """
     if not verbose:
         return
     n_p = get_num_params(model)  # number of parameters
@@ -345,17 +354,21 @@ def model_info_for_loggers(trainer):
     """
     Return model info dict with useful model information.
 
-    Example:
+    Args:
+        trainer (ultralytics.engine.trainer.BaseTrainer): The trainer object containing model and validation data.
+
+    Returns:
+        (dict): Dictionary containing model parameters, GFLOPs, and inference speeds.
+
+    Examples:
         YOLOv8n info for loggers
-        ```python
-        results = {
-            "model/parameters": 3151904,
-            "model/GFLOPs": 8.746,
-            "model/speed_ONNX(ms)": 41.244,
-            "model/speed_TensorRT(ms)": 3.211,
-            "model/speed_PyTorch(ms)": 18.755,
-        }
-        ```
+        >>> results = {
+        ...    "model/parameters": 3151904,
+        ...    "model/GFLOPs": 8.746,
+        ...    "model/speed_ONNX(ms)": 41.244,
+        ...    "model/speed_TensorRT(ms)": 3.211,
+        ...    "model/speed_PyTorch(ms)": 18.755,
+        ...}
     """
     if trainer.args.profile:  # profile ONNX and TensorRT times
         from ultralytics.utils.benchmarks import ProfileModels
@@ -372,7 +385,16 @@ def model_info_for_loggers(trainer):
 
 
 def get_flops(model, imgsz=640):
-    """Return a YOLO model's FLOPs."""
+    """
+    Return a YOLO model's FLOPs.
+
+    Args:
+        model (nn.Module): The model to calculate FLOPs for.
+        imgsz (int | List[int], optional): Input image size. Defaults to 640.
+
+    Returns:
+        (float): The model's FLOPs in billions.
+    """
     if not thop:
         return 0.0  # if not installed return 0.0 GFLOPs
 
@@ -396,7 +418,16 @@ def get_flops(model, imgsz=640):
 
 
 def get_flops_with_torch_profiler(model, imgsz=640):
-    """Compute model FLOPs (thop package alternative, but 2-10x slower unfortunately)."""
+    """
+    Compute model FLOPs using torch profiler (alternative to thop package, but 2-10x slower).
+
+    Args:
+        model (nn.Module): The model to calculate FLOPs for.
+        imgsz (int | List[int], optional): Input image size. Defaults to 640.
+
+    Returns:
+        (float): The model's FLOPs in billions.
+    """
     if not TORCH_2_0:  # torch profiler implemented in torch>=2.0
         return 0.0
     model = de_parallel(model)
@@ -434,7 +465,18 @@ def initialize_weights(model):
 
 
 def scale_img(img, ratio=1.0, same_shape=False, gs=32):
-    """Scales and pads an image tensor, optionally maintaining aspect ratio and padding to gs multiple."""
+    """
+    Scales and pads an image tensor, optionally maintaining aspect ratio and padding to gs multiple.
+
+    Args:
+        img (torch.Tensor): Input image tensor.
+        ratio (float, optional): Scaling ratio. Defaults to 1.0.
+        same_shape (bool, optional): Whether to maintain the same shape. Defaults to False.
+        gs (int, optional): Grid size for padding. Defaults to 32.
+
+    Returns:
+        (torch.Tensor): Scaled and padded image tensor.
+    """
     if ratio == 1.0:
         return img
     h, w = img.shape[2:]
@@ -446,7 +488,15 @@ def scale_img(img, ratio=1.0, same_shape=False, gs=32):
 
 
 def copy_attr(a, b, include=(), exclude=()):
-    """Copies attributes from object 'b' to object 'a', with options to include/exclude certain attributes."""
+    """
+    Copies attributes from object 'b' to object 'a', with options to include/exclude certain attributes.
+
+    Args:
+        a (object): Destination object to copy attributes to.
+        b (object): Source object to copy attributes from.
+        include (tuple, optional): Attributes to include. If empty, all attributes are included. Defaults to ().
+        exclude (tuple, optional): Attributes to exclude. Defaults to ().
+    """
     for k, v in b.__dict__.items():
         if (len(include) and k not in include) or k.startswith("_") or k in exclude:
             continue
@@ -455,7 +505,12 @@ def copy_attr(a, b, include=(), exclude=()):
 
 
 def get_latest_opset():
-    """Return the second-most recent ONNX opset version supported by this version of PyTorch, adjusted for maturity."""
+    """
+    Return the second-most recent ONNX opset version supported by this version of PyTorch, adjusted for maturity.
+
+    Returns:
+        (int): The ONNX opset version.
+    """
     if TORCH_1_13:
         # If the PyTorch>=1.13, dynamically compute the latest opset minus one using 'symbolic_opset'
         return max(int(k[14:]) for k in vars(torch.onnx) if "symbolic_opset" in k) - 1
@@ -465,27 +520,69 @@ def get_latest_opset():
 
 
 def intersect_dicts(da, db, exclude=()):
-    """Returns a dictionary of intersecting keys with matching shapes, excluding 'exclude' keys, using da values."""
+    """
+    Returns a dictionary of intersecting keys with matching shapes, excluding 'exclude' keys, using da values.
+
+    Args:
+        da (dict): First dictionary.
+        db (dict): Second dictionary.
+        exclude (tuple, optional): Keys to exclude. Defaults to ().
+
+    Returns:
+        (dict): Dictionary of intersecting keys with matching shapes.
+    """
     return {k: v for k, v in da.items() if k in db and all(x not in k for x in exclude) and v.shape == db[k].shape}
 
 
 def is_parallel(model):
-    """Returns True if model is of type DP or DDP."""
+    """
+    Returns True if model is of type DP or DDP.
+
+    Args:
+        model (nn.Module): Model to check.
+
+    Returns:
+        (bool): True if model is DataParallel or DistributedDataParallel.
+    """
     return isinstance(model, (nn.parallel.DataParallel, nn.parallel.DistributedDataParallel))
 
 
 def de_parallel(model):
-    """De-parallelize a model: returns single-GPU model if model is of type DP or DDP."""
+    """
+    De-parallelize a model: returns single-GPU model if model is of type DP or DDP.
+
+    Args:
+        model (nn.Module): Model to de-parallelize.
+
+    Returns:
+        (nn.Module): De-parallelized model.
+    """
     return model.module if is_parallel(model) else model
 
 
 def one_cycle(y1=0.0, y2=1.0, steps=100):
-    """Returns a lambda function for sinusoidal ramp from y1 to y2 https://arxiv.org/pdf/1812.01187.pdf."""
+    """
+    Returns a lambda function for sinusoidal ramp from y1 to y2 https://arxiv.org/pdf/1812.01187.pdf.
+
+    Args:
+        y1 (float, optional): Initial value. Defaults to 0.0.
+        y2 (float, optional): Final value. Defaults to 1.0.
+        steps (int, optional): Number of steps. Defaults to 100.
+
+    Returns:
+        (function): Lambda function for computing the sinusoidal ramp.
+    """
     return lambda x: max((1 - math.cos(x * math.pi / steps)) / 2, 0) * (y2 - y1) + y1
 
 
 def init_seeds(seed=0, deterministic=False):
-    """Initialize random number generator (RNG) seeds https://pytorch.org/docs/stable/notes/randomness.html."""
+    """
+    Initialize random number generator (RNG) seeds https://pytorch.org/docs/stable/notes/randomness.html.
+
+    Args:
+        seed (int, optional): Random seed. Defaults to 0.
+        deterministic (bool, optional): Whether to set deterministic algorithms. Defaults to False.
+    """
     random.seed(seed)
     np.random.seed(seed)
     torch.manual_seed(seed)
@@ -514,16 +611,30 @@ def unset_deterministic():
 
 class ModelEMA:
     """
-    Updated Exponential Moving Average (EMA) from https://github.com/rwightman/pytorch-image-models. Keeps a moving
-    average of everything in the model state_dict (parameters and buffers).
+    Updated Exponential Moving Average (EMA) from https://github.com/rwightman/pytorch-image-models.
 
+    Keeps a moving average of everything in the model state_dict (parameters and buffers).
     For EMA details see https://www.tensorflow.org/api_docs/python/tf/train/ExponentialMovingAverage
 
     To disable EMA set the `enabled` attribute to `False`.
+
+    Attributes:
+        ema (nn.Module): Copy of the model in evaluation mode.
+        updates (int): Number of EMA updates.
+        decay (function): Decay function that determines the EMA weight.
+        enabled (bool): Whether EMA is enabled.
     """
 
     def __init__(self, model, decay=0.9999, tau=2000, updates=0):
-        """Initialize EMA for 'model' with given arguments."""
+        """
+        Initialize EMA for 'model' with given arguments.
+
+        Args:
+            model (nn.Module): Model to create EMA for.
+            decay (float, optional): Maximum EMA decay rate. Defaults to 0.9999.
+            tau (int, optional): EMA decay time constant. Defaults to 2000.
+            updates (int, optional): Initial number of updates. Defaults to 0.
+        """
         self.ema = deepcopy(de_parallel(model)).eval()  # FP32 EMA
         self.updates = updates  # number of EMA updates
         self.decay = lambda x: decay * (1 - math.exp(-x / tau))  # decay exponential ramp (to help early epochs)
@@ -532,7 +643,12 @@ class ModelEMA:
         self.enabled = True
 
     def update(self, model):
-        """Update EMA parameters."""
+        """
+        Update EMA parameters.
+
+        Args:
+            model (nn.Module): Model to update EMA from.
+        """
         if self.enabled:
             self.updates += 1
             d = self.decay(self.updates)
@@ -545,7 +661,14 @@ class ModelEMA:
                     # assert v.dtype == msd[k].dtype == torch.float32, f'{k}: EMA {v.dtype},  model {msd[k].dtype}'
 
     def update_attr(self, model, include=(), exclude=("process_group", "reducer")):
-        """Updates attributes and saves stripped model with optimizer removed."""
+        """
+        Updates attributes and saves stripped model with optimizer removed.
+
+        Args:
+            model (nn.Module): Model to update attributes from.
+            include (tuple, optional): Attributes to include. Defaults to ().
+            exclude (tuple, optional): Attributes to exclude. Defaults to ("process_group", "reducer").
+        """
         if self.enabled:
             copy_attr(self.ema, model, include, exclude)
 
@@ -555,24 +678,18 @@ def strip_optimizer(f: Union[str, Path] = "best.pt", s: str = "", updates: dict
     Strip optimizer from 'f' to finalize training, optionally save as 's'.
 
     Args:
-        f (str): file path to model to strip the optimizer from. Default is 'best.pt'.
-        s (str): file path to save the model with stripped optimizer to. If not provided, 'f' will be overwritten.
-        updates (dict): a dictionary of updates to overlay onto the checkpoint before saving.
+        f (str | Path): File path to model to strip the optimizer from. Defaults to 'best.pt'.
+        s (str, optional): File path to save the model with stripped optimizer to. If not provided, 'f' will be overwritten.
+        updates (dict, optional): A dictionary of updates to overlay onto the checkpoint before saving.
 
     Returns:
         (dict): The combined checkpoint dictionary.
 
-    Example:
-        ```python
-        from pathlib import Path
-        from ultralytics.utils.torch_utils import strip_optimizer
-
-        for f in Path("path/to/model/checkpoints").rglob("*.pt"):
-            strip_optimizer(f)
-        ```
-
-    Note:
-        Use `ultralytics.nn.torch_safe_load` for missing modules with `x = torch_safe_load(f)[0]`
+    Examples:
+        >>> from pathlib import Path
+        >>> from ultralytics.utils.torch_utils import strip_optimizer
+        >>> for f in Path("path/to/model/checkpoints").rglob("*.pt"):
+        >>>    strip_optimizer(f)
     """
     try:
         x = torch.load(f, map_location=torch.device("cpu"))
@@ -620,7 +737,11 @@ def convert_optimizer_state_dict_to_fp16(state_dict):
     """
     Converts the state_dict of a given optimizer to FP16, focusing on the 'state' key for tensor conversions.
 
-    This method aims to reduce storage size without altering 'param_groups' as they contain non-tensor data.
+    Args:
+        state_dict (dict): Optimizer state dictionary.
+
+    Returns:
+        (dict): Converted optimizer state dictionary with FP16 tensors.
     """
     for state in state_dict["state"].values():
         for k, v in state.items():
@@ -660,15 +781,22 @@ def profile(input, ops, n=10, device=None, max_num_obj=0):
     """
     Ultralytics speed, memory and FLOPs profiler.
 
-    Example:
-        ```python
-        from ultralytics.utils.torch_utils import profile
+    Args:
+        input (torch.Tensor | List[torch.Tensor]): Input tensor(s) to profile.
+        ops (nn.Module | List[nn.Module]): Model or list of operations to profile.
+        n (int, optional): Number of iterations to average. Defaults to 10.
+        device (str | torch.device, optional): Device to profile on. Defaults to None.
+        max_num_obj (int, optional): Maximum number of objects for simulation. Defaults to 0.
+
+    Returns:
+        (List): Profile results for each operation.
 
-        input = torch.randn(16, 3, 640, 640)
-        m1 = lambda x: x * torch.sigmoid(x)
-        m2 = nn.SiLU()
-        profile(input, [m1, m2], n=100)  # profile over 100 iterations
-        ```
+    Examples:
+        >>> from ultralytics.utils.torch_utils import profile
+        >>> input = torch.randn(16, 3, 640, 640)
+        >>> m1 = lambda x: x * torch.sigmoid(x)
+        >>> m2 = nn.SiLU()
+        >>> profile(input, [m1, m2], n=100)  # profile over 100 iterations
     """
     results = []
     if not isinstance(device, torch.device):
@@ -731,7 +859,15 @@ def profile(input, ops, n=10, device=None, max_num_obj=0):
 
 
 class EarlyStopping:
-    """Early stopping class that stops training when a specified number of epochs have passed without improvement."""
+    """
+    Early stopping class that stops training when a specified number of epochs have passed without improvement.
+
+    Attributes:
+        best_fitness (float): Best fitness value observed.
+        best_epoch (int): Epoch where best fitness was observed.
+        patience (int): Number of epochs to wait after fitness stops improving before stopping.
+        possible_stop (bool): Flag indicating if stopping may occur next epoch.
+    """
 
     def __init__(self, patience=50):
         """
@@ -780,11 +916,12 @@ class FXModel(nn.Module):
     """
     A custom model class for torch.fx compatibility.
 
-    This class extends `torch.nn.Module` and is designed to ensure compatibility with torch.fx for tracing and graph manipulation.
-    It copies attributes from an existing model and explicitly sets the model attribute to ensure proper copying.
+    This class extends `torch.nn.Module` and is designed to ensure compatibility with torch.fx for tracing and graph
+    manipulation. It copies attributes from an existing model and explicitly sets the model attribute to ensure proper
+    copying.
 
-    Args:
-        model (torch.nn.Module): The original model to wrap for torch.fx compatibility.
+    Attributes:
+        model (nn.Module): The original model's layers.
     """
 
     def __init__(self, model):
@@ -792,7 +929,7 @@ class FXModel(nn.Module):
         Initialize the FXModel.
 
         Args:
-            model (torch.nn.Module): The original model to wrap for torch.fx compatibility.
+            model (nn.Module): The original model to wrap for torch.fx compatibility.
         """
         super().__init__()
         copy_attr(self, model)
@@ -803,7 +940,8 @@ class FXModel(nn.Module):
         """
         Forward pass through the model.
 
-        This method performs the forward pass through the model, handling the dependencies between layers and saving intermediate outputs.
+        This method performs the forward pass through the model, handling the dependencies between layers and saving
+        intermediate outputs.
 
         Args:
             x (torch.Tensor): The input tensor to the model.

ultralytics/utils/triton.py

@@ -10,6 +10,9 @@ class TritonRemoteModel:
     """
     Client for interacting with a remote Triton Inference Server model.
 
+    This class provides a convenient interface for sending inference requests to a Triton Inference Server
+    and processing the responses.
+
     Attributes:
         endpoint (str): The name of the model on the Triton server.
         url (str): The URL of the Triton server.
@@ -20,6 +23,13 @@ class TritonRemoteModel:
         np_input_formats (List[type]): The numpy data types of the model inputs.
         input_names (List[str]): The names of the model inputs.
         output_names (List[str]): The names of the model outputs.
+        metadata: The metadata associated with the model.
+
+    Examples:
+        Initialize a Triton client with HTTP
+        >>> model = TritonRemoteModel(url="localhost:8000", endpoint="yolov8", scheme="http")
+        Make inference with numpy arrays
+        >>> outputs = model(np.random.rand(1, 3, 640, 640).astype(np.float32))
     """
 
     def __init__(self, url: str, endpoint: str = "", scheme: str = ""):
@@ -27,7 +37,7 @@ class TritonRemoteModel:
         Initialize the TritonRemoteModel.
 
         Arguments may be provided individually or parsed from a collective 'url' argument of the form
-            <scheme>://<netloc>/<endpoint>/<task_name>
+        <scheme>://<netloc>/<endpoint>/<task_name>
 
         Args:
             url (str): The URL of the Triton server.
@@ -73,10 +83,10 @@ class TritonRemoteModel:
         Call the model with the given inputs.
 
         Args:
-            *inputs (List[np.ndarray]): Input data to the model.
+            *inputs (np.ndarray): Input data to the model.
 
         Returns:
-            (List[np.ndarray]): Model outputs.
+            (List[np.ndarray]): Model outputs with the same dtype as the input.
         """
         infer_inputs = []
         input_format = inputs[0].dtype

ultralytics/utils/tuner.py

@@ -13,29 +13,25 @@ def run_ray_tune(
     **train_args,
 ):
     """
-    Runs hyperparameter tuning using Ray Tune.
+    Run hyperparameter tuning using Ray Tune.
 
     Args:
         model (YOLO): Model to run the tuner on.
-        space (dict, optional): The hyperparameter search space. Defaults to None.
-        grace_period (int, optional): The grace period in epochs of the ASHA scheduler. Defaults to 10.
-        gpu_per_trial (int, optional): The number of GPUs to allocate per trial. Defaults to None.
-        max_samples (int, optional): The maximum number of trials to run. Defaults to 10.
-        train_args (dict, optional): Additional arguments to pass to the `train()` method. Defaults to {}.
+        space (dict, optional): The hyperparameter search space.
+        grace_period (int, optional): The grace period in epochs of the ASHA scheduler.
+        gpu_per_trial (int, optional): The number of GPUs to allocate per trial.
+        max_samples (int, optional): The maximum number of trials to run.
+        **train_args (Any): Additional arguments to pass to the `train()` method.
 
     Returns:
         (dict): A dictionary containing the results of the hyperparameter search.
 
-    Example:
-        ```python
-        from ultralytics import YOLO
+    Examples:
+        >>> from ultralytics import YOLO
+        >>> model = YOLO("yolo11n.pt")  # Load a YOLO11n model
 
-        # Load a YOLO11n model
-        model = YOLO("yolo11n.pt")
-
-        # Start tuning hyperparameters for YOLO11n training on the COCO8 dataset
-        result_grid = model.tune(data="coco8.yaml", use_ray=True)
-        ```
+        Start tuning hyperparameters for YOLO11n training on the COCO8 dataset
+        >>> result_grid = model.tune(data="coco8.yaml", use_ray=True)
     """
     LOGGER.info("💡 Learn about RayTune at https://docs.ultralytics.com/integrations/ray-tune")
     if train_args is None:
@@ -65,7 +61,7 @@ def run_ray_tune(
         "lr0": tune.uniform(1e-5, 1e-1),
         "lrf": tune.uniform(0.01, 1.0),  # final OneCycleLR learning rate (lr0 * lrf)
         "momentum": tune.uniform(0.6, 0.98),  # SGD momentum/Adam beta1
-        "weight_decay": tune.uniform(0.0, 0.001),  # optimizer weight decay 5e-4
+        "weight_decay": tune.uniform(0.0, 0.001),  # optimizer weight decay
         "warmup_epochs": tune.uniform(0.0, 5.0),  # warmup epochs (fractions ok)
         "warmup_momentum": tune.uniform(0.0, 0.95),  # warmup initial momentum
         "box": tune.uniform(0.02, 0.2),  # box loss gain
@@ -91,15 +87,7 @@ def run_ray_tune(
     model_in_store = ray.put(model)
 
     def _tune(config):
-        """
-        Trains the YOLO model with the specified hyperparameters and additional arguments.
-
-        Args:
-            config (dict): A dictionary of hyperparameters to use for training.
-
-        Returns:
-            None
-        """
+        """Train the YOLO model with the specified hyperparameters."""
         model_to_train = ray.get(model_in_store)  # get the model from ray store for tuning
         model_to_train.reset_callbacks()
         config.update(train_args)

{ultralytics-8.3.88.dist-info → ultralytics-8.3.90.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: ultralytics
-Version: 8.3.88
+Version: 8.3.90
 Summary: Ultralytics YOLO 🚀 for SOTA object detection, multi-object tracking, instance segmentation, pose estimation and image classification.
 Author-email: Glenn Jocher <glenn.jocher@ultralytics.com>, Jing Qiu <jing.qiu@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>
@@ -65,7 +65,7 @@ Requires-Dist: coremltools>=7.0; (platform_system != "Windows" and python_versio
 Requires-Dist: scikit-learn>=1.3.2; (platform_system != "Windows" and python_version <= "3.11") and extra == "export"
 Requires-Dist: openvino!=2025.0.0,>=2024.0.0; extra == "export"
 Requires-Dist: tensorflow>=2.0.0; extra == "export"
-Requires-Dist: tensorflowjs>=3.9.0; extra == "export"
+Requires-Dist: tensorflowjs>=4.0.0; extra == "export"
 Requires-Dist: tensorstore>=0.1.63; (platform_machine == "aarch64" and python_version >= "3.9") and extra == "export"
 Requires-Dist: keras; extra == "export"
 Requires-Dist: flatbuffers<100,>=23.5.26; platform_machine == "aarch64" and extra == "export"