[PT] Pruning statistic (#3717)

### Changes

Add `nncf.pruning_statistic` to collect and display information about
pruning parameters.

```python
    pruning_stat = nncf.pruning_statistic(pruned_model)
    print(pruning_stat)
```

```
┍━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┑
│ Parameter's name   │ Shape        │   Pruning ratio │
┝━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━┥
│ conv.weight        │ (3, 3, 3, 3) │           0.506 │
├────────────────────┼──────────────┼─────────────────┤
│                    │              │                 │
├────────────────────┼──────────────┼─────────────────┤
│ Masked parameters  │              │           0.506 │
├────────────────────┼──────────────┼─────────────────┤
│ All parameters     │              │           0.488 │
┕━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┙
```


### Related tickets

174484

### Tests


https://github.com/openvinotoolkit/nncf/actions/runs/19045571789/job/54392808345

Author: AlexanderDokuchaev

examples/pruning/torch/resnet18/main.py

@@ -254,7 +254,15 @@ def main() -> float:
         print(f"Accuracy@1 of pruned model after {epoch} epoch: {acc1:.3f}")
 
     ###############################################################################
-    # Step 4: Export models
+    # Step 4: Print per tensor pruning statistics
+    print(os.linesep + "[Step 4]: Pruning statistics")
+
+    pruning_stat = nncf.pruning_statistic(pruned_model)
+    print(pruning_stat)
+
+    ###############################################################################
+    # Step 5: Export models
+    print(os.linesep + "[Step 5]: Export models")
     ir_path = ROOT / f"{BASE_MODEL_NAME}_pruned.xml"
     ov_model = ov.convert_model(pruned_model.cpu(), example_input=example_input.cpu(), input=tuple(example_input.shape))
     ov.save_model(ov_model, ir_path, compress_to_fp16=False)

src/nncf/__init__.py

@@ -45,6 +45,7 @@
 from nncf.parameters import StripFormat as StripFormat
 from nncf.parameters import TargetDevice as TargetDevice
 from nncf.pruning.prune_model import prune as prune
+from nncf.pruning.prune_model import pruning_statistic as pruning_statistic
 from nncf.quantization import QuantizationPreset as QuantizationPreset
 from nncf.quantization import compress_weights as compress_weights
 from nncf.quantization import quantize as quantize

src/nncf/pruning/prune_model.py

@@ -9,12 +9,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from dataclasses import dataclass
 from typing import Any, Optional
 
 import nncf
 from nncf.api.compression import TModel
 from nncf.common.utils.backend import BackendType
 from nncf.common.utils.backend import get_backend
+from nncf.common.utils.helpers import create_table
 from nncf.parameters import PruneMode
 from nncf.scopes import IgnoredScope
 
@@ -47,3 +49,61 @@ def prune(
         msg = f"Pruning is not supported for the {backend} backend."
         raise nncf.InternalError(msg)
     return model
+
+
+@dataclass
+class TensorPruningStatistic:
+    """
+    Statistics about pruning for a single tensor.
+
+    :param tensor_name: Name of the tensor.
+    :param shape: Shape of the tensor.
+    :param pruned_ratio: Ratio of pruned elements in the tensor.
+    """
+
+    tensor_name: str
+    shape: tuple[int, ...]
+    pruned_ratio: float
+
+
+@dataclass
+class ModelPruningStatistic:
+    """
+    Aggregated pruning statistics for a model.
+
+    :param pruning_ratio: Overall pruning ratio for pruned parameters in the model.
+    :param global_pruning_ratio: Overall pruning ratio for all parameters in the model.
+    :param pruned_tensors: List of pruning statistics for each tensor.
+    """
+
+    pruning_ratio: float
+    global_pruning_ratio: float
+    pruned_tensors: list[TensorPruningStatistic]
+
+    def __str__(self) -> str:
+        total = [
+            [None, None, None, None],
+            ["Prunable parameters", None, self.pruning_ratio],
+            ["All parameters", None, self.global_pruning_ratio],
+        ]
+
+        sorted_stat_per_tensor = sorted(self.pruned_tensors, key=lambda s: s.tensor_name)
+        rows_per_tensor = [[s.tensor_name, s.shape, s.pruned_ratio] for s in sorted_stat_per_tensor]
+        text = create_table(header=["Parameter's name", "Shape", "Pruning ratio"], rows=rows_per_tensor + total)
+        return text
+
+
+def pruning_statistic(model: TModel) -> ModelPruningStatistic:
+    """
+    Collects and returns pruning statistics for the given model.
+
+    :param model: The pruned model.
+    :return: A pruning statistic.
+    """
+    backend = get_backend(model)
+    if backend == BackendType.TORCH:
+        from nncf.torch.function_hook.pruning.statistics import pruning_statistic
+
+        return pruning_statistic(model)
+    msg = f"Pruning statistics collection is not supported for the {backend} backend."
+    raise nncf.InternalError(msg)

src/nncf/torch/function_hook/pruning/statistics.py

@@ -0,0 +1,68 @@
+# Copyright (c) 2025 Intel Corporation
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#      http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import torch
+from torch import nn
+
+from nncf.pruning.prune_model import ModelPruningStatistic
+from nncf.pruning.prune_model import TensorPruningStatistic
+from nncf.torch.function_hook.hook_storage import decode_hook_name
+from nncf.torch.function_hook.pruning.magnitude.modules import UnstructuredPruningMask
+from nncf.torch.function_hook.pruning.rb.modules import RBPruningMask
+from nncf.torch.function_hook.pruning.rb.modules import binary_mask
+from nncf.torch.function_hook.wrapper import get_hook_storage
+
+
+@torch.no_grad()
+def pruning_statistic(model: nn.Module) -> ModelPruningStatistic:
+    """
+    Collects and returns pruning statistics for the given model.
+
+    :param model: The pruned model.
+    :return: Pruning statistics.
+    """
+    total_params = sum(p.numel() for p in model.parameters())
+    num_elements = 0
+    pruned_elements = 0
+    stat_per_tensors: list[TensorPruningStatistic] = []
+
+    hook_storage = get_hook_storage(model)
+    for hook_name, hook_module in hook_storage.named_hooks():
+        if isinstance(hook_module, UnstructuredPruningMask):
+            mask = hook_module.binary_mask
+        elif isinstance(hook_module, RBPruningMask):
+            mask = binary_mask(hook_module.mask)
+            # Exclude RBPruningMask’s internal mask parameters from the total parameter count
+            total_params -= mask.numel()
+        else:
+            continue
+
+        pruned_el = int(torch.sum(mask == 0).item())
+        num_el = mask.numel()
+        shape = tuple(mask.shape)
+        pruned_ratio = pruned_el / num_el if num_el != 0 else 0.0
+
+        _, tensor_name, _ = decode_hook_name(hook_name)
+
+        num_elements += num_el
+        pruned_elements += pruned_el
+
+        stat_per_tensors.append(TensorPruningStatistic(tensor_name, shape, pruned_ratio))
+
+    masked_ratio = pruned_elements / num_elements if num_elements != 0 else 0.0
+    global_ratio = pruned_elements / total_params if total_params != 0 else 0.0
+
+    return ModelPruningStatistic(
+        pruning_ratio=masked_ratio,
+        global_pruning_ratio=global_ratio,
+        pruned_tensors=stat_per_tensors,
+    )

tests/torch2/function_hook/pruning/magnitude/test_algo.py

@@ -149,3 +149,23 @@ def test_save_load(tmpdir: Path):
     assert isinstance(d["post_hooks.conv:weight__0.0"], UnstructuredPruningMask)
 
     assert torch.allclose(orig_output, loaded_output)
+
+
+def test_statistic():
+    model = ConvModel()
+    example_inputs = ConvModel.get_example_inputs()
+
+    pruned_model = nncf.prune(
+        model, mode=PruneMode.UNSTRUCTURED_MAGNITUDE_LOCAL, ratio=0.5, examples_inputs=example_inputs
+    )
+    stat = nncf.pruning_statistic(pruned_model)
+
+    assert pytest.approx(stat.pruned_tensors[0].pruned_ratio, abs=1e-1) == 0.5
+    assert stat.pruned_tensors[0].tensor_name == "conv.weight"
+    assert stat.pruned_tensors[0].shape == (3, 3, 3, 3)
+    assert pytest.approx(stat.pruning_ratio, abs=1e-2) == 0.5
+    assert pytest.approx(stat.global_pruning_ratio, abs=1e-2) == 0.48
+
+    txt = str(stat)
+    assert "conv.weight" in txt
+    assert "All parameters" in txt

tests/torch2/function_hook/pruning/rb/test_algo.py

@@ -114,3 +114,30 @@ def test_save_load(tmpdir: Path):
     assert isinstance(d["post_hooks.conv:weight__0.0"], RBPruningMask)
 
     assert torch.allclose(orig_output, loaded_output)
+
+
+def test_statistic():
+    model = ConvModel()
+    example_inputs = ConvModel.get_example_inputs()
+
+    pruned_model = nncf.prune(
+        model, mode=PruneMode.UNSTRUCTURED_REGULARIZATION_BASED, ratio=0.5, examples_inputs=example_inputs
+    )
+
+    # Set mask
+    with torch.no_grad():
+        hook_storage = get_hook_storage(pruned_model)
+        pruning_module = hook_storage.post_hooks["conv:weight__0"]["0"]
+        pruning_module.mask[0] *= -1
+
+    stat = nncf.pruning_statistic(pruned_model)
+
+    assert pytest.approx(stat.pruned_tensors[0].pruned_ratio, abs=1e-1) == 0.3
+    assert stat.pruned_tensors[0].tensor_name == "conv.weight"
+    assert stat.pruned_tensors[0].shape == (3, 3, 3, 3)
+    assert pytest.approx(stat.pruning_ratio, abs=1e-2) == 0.33
+    assert pytest.approx(stat.global_pruning_ratio, abs=1e-2) == 0.32
+
+    txt = str(stat)
+    assert "conv.weight" in txt
+    assert "All parameters" in txt