wavedl 1.5.4__py3-none-any.whl → 1.5.6__py3-none-any.whl

wavedl/__init__.py

@@ -18,7 +18,7 @@ For inference:
     # or: python -m wavedl.test --checkpoint best_checkpoint --data_path test.npz
 """
 
-__version__ = "1.5.4"
+__version__ = "1.5.6"
 __author__ = "Ductho Le"
 __email__ = "ductho.le@outlook.com"
 

wavedl/hpo.py

@@ -175,13 +175,14 @@ def create_objective(args):
                 env["CUDA_VISIBLE_DEVICES"] = str(gpu_id)
 
             # Run training
+            # Note: We inherit the user's cwd instead of setting cwd=Path(__file__).parent
+            # because site-packages may be read-only and train.py creates cache directories
             try:
                 result = subprocess.run(
                     cmd,
                     capture_output=True,
                     text=True,
                     timeout=args.timeout,
-                    cwd=Path(__file__).parent,
                     env=env,
                 )
 

wavedl/models/vit.py

@@ -42,47 +42,89 @@ class PatchEmbed(nn.Module):
     Supports 1D and 2D inputs:
     - 1D: Input (B, 1, L) → (B, num_patches, embed_dim)
     - 2D: Input (B, 1, H, W) → (B, num_patches, embed_dim)
+
+    Args:
+        in_shape: Spatial shape (L,) for 1D or (H, W) for 2D
+        patch_size: Size of each patch
+        embed_dim: Embedding dimension
+        pad_if_needed: If True, pad input to nearest patch-aligned size instead of
+            dropping edge pixels. Important for NDE/QUS applications where edge
+            effects matter. Default: False (original behavior with warning).
     """
 
-    def __init__(self, in_shape: SpatialShape, patch_size: int, embed_dim: int):
+    def __init__(
+        self,
+        in_shape: SpatialShape,
+        patch_size: int,
+        embed_dim: int,
+        pad_if_needed: bool = False,
+    ):
         super().__init__()
 
         self.dim = len(in_shape)
         self.patch_size = patch_size
         self.embed_dim = embed_dim
+        self.pad_if_needed = pad_if_needed
+        self._padding = None  # Will be set if padding is needed
 
         if self.dim == 1:
             # 1D: segment patches
             L = in_shape[0]
-            if L % patch_size != 0:
-                import warnings
-
-                warnings.warn(
-                    f"Input length {L} not divisible by patch_size {patch_size}. "
-                    f"Last {L % patch_size} elements will be dropped. "
-                    f"Consider padding input to {((L // patch_size) + 1) * patch_size}.",
-                    UserWarning,
-                    stacklevel=2,
-                )
-            self.num_patches = L // patch_size
+            remainder = L % patch_size
+            if remainder != 0:
+                if pad_if_needed:
+                    # Pad to next multiple of patch_size
+                    pad_amount = patch_size - remainder
+                    self._padding = (0, pad_amount)  # (left, right)
+                    L_padded = L + pad_amount
+                    self.num_patches = L_padded // patch_size
+                else:
+                    import warnings
+
+                    warnings.warn(
+                        f"Input length {L} not divisible by patch_size {patch_size}. "
+                        f"Last {remainder} elements will be dropped. "
+                        f"Consider using pad_if_needed=True or padding input to "
+                        f"{((L // patch_size) + 1) * patch_size}.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                    self.num_patches = L // patch_size
+            else:
+                self.num_patches = L // patch_size
             self.proj = nn.Conv1d(
                 1, embed_dim, kernel_size=patch_size, stride=patch_size
             )
         elif self.dim == 2:
             # 2D: grid patches
             H, W = in_shape
-            if H % patch_size != 0 or W % patch_size != 0:
-                import warnings
-
-                warnings.warn(
-                    f"Input shape ({H}, {W}) not divisible by patch_size {patch_size}. "
-                    f"Border pixels will be dropped (H: {H % patch_size}, W: {W % patch_size}). "
-                    f"Consider padding to ({((H // patch_size) + 1) * patch_size}, "
-                    f"{((W // patch_size) + 1) * patch_size}).",
-                    UserWarning,
-                    stacklevel=2,
-                )
-            self.num_patches = (H // patch_size) * (W // patch_size)
+            h_rem, w_rem = H % patch_size, W % patch_size
+            if h_rem != 0 or w_rem != 0:
+                if pad_if_needed:
+                    # Pad to next multiple of patch_size
+                    h_pad = (patch_size - h_rem) % patch_size
+                    w_pad = (patch_size - w_rem) % patch_size
+                    # Padding format: (left, right, top, bottom)
+                    self._padding = (0, w_pad, 0, h_pad)
+                    H_padded, W_padded = H + h_pad, W + w_pad
+                    self.num_patches = (H_padded // patch_size) * (
+                        W_padded // patch_size
+                    )
+                else:
+                    import warnings
+
+                    warnings.warn(
+                        f"Input shape ({H}, {W}) not divisible by patch_size {patch_size}. "
+                        f"Border pixels will be dropped (H: {h_rem}, W: {w_rem}). "
+                        f"Consider using pad_if_needed=True or padding to "
+                        f"({((H // patch_size) + 1) * patch_size}, "
+                        f"{((W // patch_size) + 1) * patch_size}).",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                    self.num_patches = (H // patch_size) * (W // patch_size)
+            else:
+                self.num_patches = (H // patch_size) * (W // patch_size)
             self.proj = nn.Conv2d(
                 1, embed_dim, kernel_size=patch_size, stride=patch_size
             )
@@ -97,6 +139,10 @@ class PatchEmbed(nn.Module):
         Returns:
             Patch embeddings (B, num_patches, embed_dim)
         """
+        # Apply padding if configured
+        if self._padding is not None:
+            x = nn.functional.pad(x, self._padding, mode="constant", value=0)
+
         x = self.proj(x)  # (B, embed_dim, ..reduced_spatial..)
         x = x.flatten(2)  # (B, embed_dim, num_patches)
         x = x.transpose(1, 2)  # (B, num_patches, embed_dim)
@@ -185,6 +231,18 @@ class ViTBase(BaseModel):
     3. Transformer encoder blocks
     4. Extract CLS token
     5. Regression head
+
+    Args:
+        in_shape: Spatial shape (L,) for 1D or (H, W) for 2D
+        out_size: Number of regression targets
+        patch_size: Size of each patch (default: 16)
+        embed_dim: Embedding dimension (default: 768)
+        depth: Number of transformer blocks (default: 12)
+        num_heads: Number of attention heads (default: 12)
+        mlp_ratio: MLP hidden dim multiplier (default: 4.0)
+        dropout_rate: Dropout rate (default: 0.1)
+        pad_if_needed: If True, pad input to nearest patch-aligned size instead
+            of dropping edge pixels. Important for NDE/QUS applications.
     """
 
     def __init__(
@@ -197,6 +255,7 @@ class ViTBase(BaseModel):
         num_heads: int = 12,
         mlp_ratio: float = 4.0,
         dropout_rate: float = 0.1,
+        pad_if_needed: bool = False,
         **kwargs,
     ):
         super().__init__(in_shape, out_size)
@@ -207,9 +266,10 @@ class ViTBase(BaseModel):
         self.num_heads = num_heads
         self.dropout_rate = dropout_rate
         self.dim = len(in_shape)
+        self.pad_if_needed = pad_if_needed
 
         # Patch embedding
-        self.patch_embed = PatchEmbed(in_shape, patch_size, embed_dim)
+        self.patch_embed = PatchEmbed(in_shape, patch_size, embed_dim, pad_if_needed)
         num_patches = self.patch_embed.num_patches
 
         # Learnable CLS token and position embeddings

wavedl/train.py

@@ -162,12 +162,22 @@ except ImportError:
 os.environ.setdefault("MPLCONFIGDIR", os.getenv("TMPDIR", "/tmp") + "/matplotlib")
 os.environ.setdefault("FONTCONFIG_PATH", "/etc/fonts")
 
-# Suppress non-critical warnings for cleaner training logs
-warnings.filterwarnings("ignore", category=UserWarning)
+# Suppress warnings from known-noisy libraries, but preserve legitimate warnings
+# from torch/numpy about NaN, dtype, and numerical issues.
 warnings.filterwarnings("ignore", category=FutureWarning)
 warnings.filterwarnings("ignore", category=DeprecationWarning)
+# Pydantic v1/v2 compatibility warnings
 warnings.filterwarnings("ignore", module="pydantic")
 warnings.filterwarnings("ignore", message=".*UnsupportedFieldAttributeWarning.*")
+# Transformer library warnings (loading configs, etc.)
+warnings.filterwarnings("ignore", module="transformers")
+# Accelerate verbose messages
+warnings.filterwarnings("ignore", module="accelerate")
+# torch.compile backend selection warnings
+warnings.filterwarnings("ignore", message=".*TorchDynamo.*")
+warnings.filterwarnings("ignore", message=".*Dynamo is not supported.*")
+# Note: UserWarning from torch/numpy core is NOT suppressed to preserve
+# legitimate warnings about NaN values, dtype mismatches, etc.
 
 # ==============================================================================
 # GPU PERFORMANCE OPTIMIZATIONS (Ampere/Hopper: A100, H100)
@@ -228,6 +238,18 @@ def parse_args() -> argparse.Namespace:
         default=[],
         help="Python modules to import before training (for custom models)",
     )
+    parser.add_argument(
+        "--pretrained",
+        action="store_true",
+        default=True,
+        help="Use pretrained weights (default: True)",
+    )
+    parser.add_argument(
+        "--no_pretrained",
+        dest="pretrained",
+        action="store_false",
+        help="Train from scratch without pretrained weights",
+    )
 
     # Configuration File
     parser.add_argument(
@@ -543,15 +565,11 @@ def main():
         data_format = DataSource.detect_format(args.data_path)
         source = get_data_source(data_format)
 
-        # Use memory-mapped loading when available
+        # Use memory-mapped loading when available (now returns LazyDataHandle for all formats)
         _cv_handle = None
         if hasattr(source, "load_mmap"):
-            result = source.load_mmap(args.data_path)
-            if hasattr(result, "inputs"):
-                _cv_handle = result
-                X, y = result.inputs, result.outputs
-            else:
-                X, y = result  # NPZ returns tuple directly
+            _cv_handle = source.load_mmap(args.data_path)
+            X, y = _cv_handle.inputs, _cv_handle.outputs
         else:
             X, y = source.load(args.data_path)
 
@@ -684,7 +702,9 @@ def main():
     )
 
     # Build model using registry
-    model = build_model(args.model, in_shape=in_shape, out_size=out_dim)
+    model = build_model(
+        args.model, in_shape=in_shape, out_size=out_dim, pretrained=args.pretrained
+    )
 
     if accelerator.is_main_process:
         param_info = model.parameter_summary()
@@ -861,10 +881,22 @@ def main():
             milestones=milestones,
             warmup_epochs=args.warmup_epochs,
         )
-        # Prepare everything together
-        model, optimizer, train_dl, val_dl, scheduler = accelerator.prepare(
-            model, optimizer, train_dl, val_dl, scheduler
-        )
+
+        # For ReduceLROnPlateau: DON'T include scheduler in accelerator.prepare()
+        # because accelerator wraps scheduler.step() to sync across processes,
+        # which defeats our rank-0-only stepping for correct patience counting.
+        # Other schedulers are safe to prepare (no internal state affected by multi-call).
+        if args.scheduler == "plateau":
+            model, optimizer, train_dl, val_dl = accelerator.prepare(
+                model, optimizer, train_dl, val_dl
+            )
+            # Scheduler stays unwrapped - we handle sync manually in training loop
+            # But register it for checkpointing so state is saved/loaded on resume
+            accelerator.register_for_checkpointing(scheduler)
+        else:
+            model, optimizer, train_dl, val_dl, scheduler = accelerator.prepare(
+                model, optimizer, train_dl, val_dl, scheduler
+            )
 
     # ==========================================================================
     # AUTO-RESUME / RESUME FROM CHECKPOINT

wavedl/utils/data.py

@@ -13,6 +13,7 @@ Version: 1.0.0
 """
 
 import gc
+import hashlib
 import logging
 import os
 import pickle
@@ -49,6 +50,29 @@ INPUT_KEYS = ["input_train", "input_test", "X", "data", "inputs", "features", "x
 OUTPUT_KEYS = ["output_train", "output_test", "Y", "labels", "outputs", "targets", "y"]
 
 
+def _compute_file_hash(path: str, chunk_size: int = 8 * 1024 * 1024) -> str:
+    """
+    Compute SHA256 hash of a file for cache validation.
+
+    Uses chunked reading to handle large files efficiently without loading
+    the entire file into memory. This is more reliable than mtime for detecting
+    actual content changes, especially with cloud sync services (Dropbox, etc.)
+    that may touch files without modifying content.
+
+    Args:
+        path: Path to file to hash
+        chunk_size: Read buffer size (default 8MB for fast I/O)
+
+    Returns:
+        Hex string of SHA256 hash
+    """
+    hasher = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(chunk_size):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
 class LazyDataHandle:
     """
     Context manager wrapper for memory-mapped data handles.
@@ -207,6 +231,10 @@ class NPZSource(DataSource):
 
         The error for object arrays happens at ACCESS time, not load time.
         So we need to probe the keys to detect if pickle is required.
+
+        WARNING: When mmap_mode is not None, the returned NpzFile must be kept
+        open for arrays to remain valid. Caller is responsible for closing.
+        For non-mmap loading, use _load_and_copy() instead to avoid leaks.
         """
         data = np.load(path, allow_pickle=False, mmap_mode=mmap_mode)
         try:
@@ -222,6 +250,26 @@ class NPZSource(DataSource):
                 return np.load(path, allow_pickle=True, mmap_mode=mmap_mode)
             raise
 
+    @staticmethod
+    def _load_and_copy(path: str, keys: list[str]) -> dict[str, np.ndarray]:
+        """Load NPZ and copy arrays, ensuring file is properly closed.
+
+        This prevents file descriptor leaks by copying arrays before closing.
+        Use this for eager loading; use _safe_load for memory-mapped access.
+        """
+        data = NPZSource._safe_load(path, keys, mmap_mode=None)
+        try:
+            result = {}
+            for key in keys:
+                if key in data:
+                    arr = data[key]
+                    # Copy ensures we don't hold reference to mmap
+                    result[key] = arr.copy() if hasattr(arr, "copy") else arr
+            return result
+        finally:
+            if hasattr(data, "close"):
+                data.close()
+
     def load(self, path: str) -> tuple[np.ndarray, np.ndarray]:
         """Load NPZ file (pickle enabled only for sparse matrices)."""
         # First pass to find keys without loading data
@@ -238,7 +286,7 @@ class NPZSource(DataSource):
                 f"Found: {keys}"
             )
 
-        data = self._safe_load(path, [input_key, output_key])
+        data = self._load_and_copy(path, [input_key, output_key])
         inp = data[input_key]
         outp = data[output_key]
 
@@ -248,13 +296,21 @@ class NPZSource(DataSource):
 
         return inp, outp
 
-    def load_mmap(self, path: str) -> tuple[np.ndarray, np.ndarray]:
+    def load_mmap(self, path: str) -> LazyDataHandle:
         """
         Load data using memory-mapped mode for zero-copy access.
 
         This allows processing large datasets without loading them entirely
         into RAM. Critical for HPC environments with memory constraints.
 
+        Returns a LazyDataHandle for consistent API across all data sources.
+        The NpzFile is kept open for lazy access.
+
+        Usage:
+            with source.load_mmap(path) as (inputs, outputs):
+                # Use inputs and outputs
+                pass  # File automatically closed
+
         Note: Returns memory-mapped arrays - do NOT modify them.
         """
         # First pass to find keys without loading data
@@ -271,11 +327,13 @@ class NPZSource(DataSource):
                 f"Found: {keys}"
             )
 
+        # Keep NpzFile open for lazy access (like HDF5/MATSource)
         data = self._safe_load(path, [input_key, output_key], mmap_mode="r")
         inp = data[input_key]
         outp = data[output_key]
 
-        return inp, outp
+        # Return LazyDataHandle for consistent API with HDF5Source/MATSource
+        return LazyDataHandle(inp, outp, file_handle=data)
 
     def load_outputs_only(self, path: str) -> np.ndarray:
         """Load only targets from NPZ (avoids loading large input arrays)."""
@@ -290,7 +348,7 @@ class NPZSource(DataSource):
                 f"Supported keys: {OUTPUT_KEYS}. Found: {keys}"
             )
 
-        data = self._safe_load(path, [output_key])
+        data = self._load_and_copy(path, [output_key])
         return data[output_key]
 
 
@@ -527,9 +585,17 @@ class MATSource(DataSource):
                 inp = self._load_dataset(f, input_key)
                 outp = self._load_dataset(f, output_key)
 
-                # Handle 1D outputs that become (1, N) after transpose
-                if outp.ndim == 2 and outp.shape[0] == 1:
-                    outp = outp.T
+                # Handle transposed outputs from MATLAB.
+                # Case 1: (1, N) - N samples with 1 target → transpose to (N, 1)
+                # Case 2: (T, 1) - 1 sample with T targets → transpose to (1, T)
+                num_samples = inp.shape[0]  # inp is already transposed
+                if outp.ndim == 2:
+                    if outp.shape[0] == 1 and outp.shape[1] == num_samples:
+                        # 1D vector: (1, N) → (N, 1)
+                        outp = outp.T
+                    elif outp.shape[1] == 1 and outp.shape[0] != num_samples:
+                        # Single sample with multiple targets: (T, 1) → (1, T)
+                        outp = outp.T
 
         except OSError as e:
             raise ValueError(
@@ -614,7 +680,10 @@ class MATSource(DataSource):
                 # Load with sparse matrix support
                 outp = self._load_dataset(f, output_key)
 
-                # Handle 1D outputs
+                # Handle 1D outputs that become (1, N) after transpose.
+                # Note: This method has no input to compare against, so we can't
+                # distinguish single-sample outputs. This is acceptable for training
+                # data where single-sample is unlikely. For inference, use load_test_data.
                 if outp.ndim == 2 and outp.shape[0] == 1:
                     outp = outp.T
 
@@ -775,7 +844,7 @@ def load_test_data(
                 raise KeyError(
                     f"Input key not found. Tried: {custom_input_keys}. Found: {keys}"
                 )
-            data = NPZSource._safe_load(
+            data = NPZSource._load_and_copy(
                 path, [inp_key] + ([out_key] if out_key else [])
             )
             inp = data[inp_key]
@@ -824,8 +893,17 @@ def load_test_data(
                 inp = mat_source._load_dataset(f, inp_key)
                 if out_key:
                     outp = mat_source._load_dataset(f, out_key)
-                    if outp.ndim == 2 and outp.shape[0] == 1:
-                        outp = outp.T
+                    # Handle transposed outputs from MATLAB
+                    # Case 1: (1, N) - N samples with 1 target → transpose to (N, 1)
+                    # Case 2: (T, 1) - 1 sample with T targets → transpose to (1, T)
+                    num_samples = inp.shape[0]
+                    if outp.ndim == 2:
+                        if outp.shape[0] == 1 and outp.shape[1] == num_samples:
+                            # 1D vector: (1, N) → (N, 1)
+                            outp = outp.T
+                        elif outp.shape[1] == 1 and outp.shape[0] != num_samples:
+                            # Single sample with multiple targets: (T, 1) → (1, T)
+                            outp = outp.T
                 else:
                     outp = None
         else:
@@ -844,7 +922,7 @@ def load_test_data(
                 )
             out_key = DataSource._find_key(keys, custom_output_keys)
             keys_to_probe = [inp_key] + ([out_key] if out_key else [])
-            data = NPZSource._safe_load(path, keys_to_probe)
+            data = NPZSource._load_and_copy(path, keys_to_probe)
             inp = data[inp_key]
             if inp.dtype == object:
                 inp = np.array(
@@ -894,9 +972,17 @@ def load_test_data(
                 out_key = DataSource._find_key(keys, custom_output_keys)
                 if out_key:
                     outp = mat_source._load_dataset(f, out_key)
-                    # Handle 1D outputs that become (1, N) after transpose
-                    if outp.ndim == 2 and outp.shape[0] == 1:
-                        outp = outp.T
+                    # Handle transposed outputs from MATLAB
+                    # Case 1: (1, N) - N samples with 1 target → transpose to (N, 1)
+                    # Case 2: (T, 1) - 1 sample with T targets → transpose to (1, T)
+                    num_samples = inp.shape[0]
+                    if outp.ndim == 2:
+                        if outp.shape[0] == 1 and outp.shape[1] == num_samples:
+                            # 1D vector: (1, N) → (N, 1)
+                            outp = outp.T
+                        elif outp.shape[1] == 1 and outp.shape[0] != num_samples:
+                            # Single sample with multiple targets: (T, 1) → (1, T)
+                            outp = outp.T
                 else:
                     outp = None
         else:
@@ -1096,32 +1182,21 @@ def prepare_data(
         and os.path.exists(META_FILE)
     )
 
-    # Validate cache matches current data_path (prevents stale cache corruption)
+    # Validate cache using content hash (portable across folders/machines)
+    # File size is a fast pre-check, content hash is definitive validation
     if cache_exists:
         try:
             with open(META_FILE, "rb") as f:
                 meta = pickle.load(f)
-            cached_data_path = meta.get("data_path", None)
             cached_file_size = meta.get("file_size", None)
-            cached_file_mtime = meta.get("file_mtime", None)
+            cached_content_hash = meta.get("content_hash", None)
 
             # Get current file stats
             current_stats = os.stat(args.data_path)
             current_size = current_stats.st_size
-            current_mtime = current_stats.st_mtime
 
-            # Check if data path changed
-            if cached_data_path != os.path.abspath(args.data_path):
-                if accelerator.is_main_process:
-                    logger.warning(
-                        f"⚠️  Cache was created from different data file!\n"
-                        f"   Cached: {cached_data_path}\n"
-                        f"   Current: {os.path.abspath(args.data_path)}\n"
-                        f"   Invalidating cache and regenerating..."
-                    )
-                cache_exists = False
-            # Check if file was modified (size or mtime changed)
-            elif cached_file_size is not None and cached_file_size != current_size:
+            # Check if file size changed (fast check before expensive hash)
+            if cached_file_size is not None and cached_file_size != current_size:
                 if accelerator.is_main_process:
                     logger.warning(
                         f"⚠️  Data file size changed!\n"
@@ -1130,13 +1205,16 @@ def prepare_data(
                         f"   Invalidating cache and regenerating..."
                     )
                 cache_exists = False
-            elif cached_file_mtime is not None and cached_file_mtime != current_mtime:
-                if accelerator.is_main_process:
-                    logger.warning(
-                        "⚠️  Data file was modified!\n"
-                        "   Cache may be stale, regenerating..."
-                    )
-                cache_exists = False
+            # Content hash check (robust against cloud sync mtime changes)
+            elif cached_content_hash is not None:
+                current_hash = _compute_file_hash(args.data_path)
+                if cached_content_hash != current_hash:
+                    if accelerator.is_main_process:
+                        logger.warning(
+                            "⚠️  Data file content changed!\n"
+                            "   Cache is stale, regenerating..."
+                        )
+                    cache_exists = False
         except Exception:
             cache_exists = False
 
@@ -1153,6 +1231,18 @@ def prepare_data(
                         logger.warning(
                             f"   Failed to remove stale cache {stale_file}: {e}"
                         )
+
+            # Fail explicitly if stale cache files couldn't be removed
+            # This prevents silent reuse of outdated data
+            remaining_stale = [
+                f for f in [CACHE_FILE, SCALER_FILE] if os.path.exists(f)
+            ]
+            if remaining_stale:
+                raise RuntimeError(
+                    f"Cannot regenerate cache: stale files could not be removed. "
+                    f"Please manually delete: {remaining_stale}"
+                )
+
             # RANK 0: Create cache (can take a long time for large datasets)
             # Other ranks will wait at the barrier below
 
@@ -1170,16 +1260,11 @@ def prepare_data(
 
             # Load raw data using memory-mapped mode for all formats
             # This avoids loading the entire dataset into RAM at once
+            # All load_mmap() methods now return LazyDataHandle consistently
+            _lazy_handle = None
             try:
-                if data_format == "npz":
-                    source = NPZSource()
-                    inp, outp = source.load_mmap(args.data_path)
-                elif data_format == "hdf5":
-                    source = HDF5Source()
-                    _lazy_handle = source.load_mmap(args.data_path)
-                    inp, outp = _lazy_handle.inputs, _lazy_handle.outputs
-                elif data_format == "mat":
-                    source = MATSource()
+                source = get_data_source(data_format)
+                if hasattr(source, "load_mmap"):
                     _lazy_handle = source.load_mmap(args.data_path)
                     inp, outp = _lazy_handle.inputs, _lazy_handle.outputs
                 else:
@@ -1243,8 +1328,9 @@ def prepare_data(
                 f"   Shape Detected: {full_shape} [{dim_type}] | Output Dim: {out_dim}"
             )
 
-            # Save metadata (including data path, size, mtime for cache validation)
+            # Save metadata (including data path, size, content hash for cache validation)
             file_stats = os.stat(args.data_path)
+            content_hash = _compute_file_hash(args.data_path)
             with open(META_FILE, "wb") as f:
                 pickle.dump(
                     {
@@ -1252,7 +1338,7 @@ def prepare_data(
                         "out_dim": out_dim,
                         "data_path": os.path.abspath(args.data_path),
                         "file_size": file_stats.st_size,
-                        "file_mtime": file_stats.st_mtime,
+                        "content_hash": content_hash,
                     },
                     f,
                 )

wavedl/utils/metrics.py

@@ -815,7 +815,28 @@ def plot_qq(
 
         # Standardize errors for QQ plot
         err = errors[:, i]
-        standardized = (err - np.mean(err)) / np.std(err)
+        std_err = np.std(err)
+
+        # Guard against zero variance (constant errors)
+        if std_err < 1e-10:
+            title = (
+                param_names[i] if param_names and i < len(param_names) else f"Param {i}"
+            )
+            ax.text(
+                0.5,
+                0.5,
+                "Zero variance\n(constant errors)",
+                ha="center",
+                va="center",
+                fontsize=10,
+                transform=ax.transAxes,
+            )
+            ax.set_title(f"{title}\n(zero variance)")
+            ax.set_xlabel("Theoretical Quantiles")
+            ax.set_ylabel("Sample Quantiles")
+            continue
+
+        standardized = (err - np.mean(err)) / std_err
 
         # Calculate theoretical quantiles and sample quantiles
         (osm, osr), (slope, intercept, r) = stats.probplot(standardized, dist="norm")

{wavedl-1.5.4.dist-info → wavedl-1.5.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: wavedl
-Version: 1.5.4
+Version: 1.5.6
 Summary: A Scalable Deep Learning Framework for Wave-Based Inverse Problems
 Author: Ductho Le
 License: MIT
@@ -388,7 +388,7 @@ WaveDL/
 ├── configs/                      # YAML config templates
 ├── examples/                     # Ready-to-run examples
 ├── notebooks/                    # Jupyter notebooks
-├── unit_tests/                   # Pytest test suite (725 tests)
+├── unit_tests/                   # Pytest test suite (731 tests)
 │
 ├── pyproject.toml                # Package config, dependencies
 ├── CHANGELOG.md                  # Version history
@@ -470,6 +470,7 @@ WaveDL/
 ⭐ = **Pretrained on ImageNet** (recommended for smaller datasets). Weights are downloaded automatically on first use.
 - **Cache location**: `~/.cache/torch/hub/checkpoints/` (or `./.torch_cache/` on HPC if home is not writable)
 - **Size**: ~20–350 MB per model depending on architecture
+- **Train from scratch**: Use `--no_pretrained` to disable pretrained weights
 
 **💡 HPC Users**: If compute nodes block internet, pre-download weights on the login node:
 
@@ -1030,7 +1031,7 @@ print(f"✓ Output: {data['output_train'].shape} {data['output_train'].dtype}")
 
 ## 📦 Examples [![Try it on Colab](https://img.shields.io/badge/Try_it_on_Colab-8E44AD?style=plastic&logo=googlecolab&logoColor=white)](https://colab.research.google.com/github/ductho-le/WaveDL/blob/main/notebooks/demo.ipynb)
 
-The `examples/` folder contains a **complete, ready-to-run example** for **material characterization of isotropic plates**. The pre-trained CNN predicts three physical parameters from Lamb wave dispersion curves:
+The `examples/` folder contains a **complete, ready-to-run example** for **material characterization of isotropic plates**. The pre-trained MobileNetV3 predicts three physical parameters from Lamb wave dispersion curves:
 
 | Parameter | Unit | Description |
 |-----------|------|-------------|
@@ -1045,22 +1046,22 @@ The `examples/` folder contains a **complete, ready-to-run example** for **mater
 
 ```bash
 # Run inference on the example data
-python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoint \
-  --data_path ./examples/elastic_cnn_example/Test_data_500.mat \
-  --plot --save_predictions --output_dir ./examples/elastic_cnn_example/test_results
+python -m wavedl.test --checkpoint ./examples/elasticity_prediction/best_checkpoint \
+  --data_path ./examples/elasticity_prediction/Test_data_100.mat \
+  --plot --save_predictions --output_dir ./examples/elasticity_prediction/test_results
 
 # Export to ONNX (already included as model.onnx)
-python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoint \
-  --data_path ./examples/elastic_cnn_example/Test_data_500.mat \
-  --export onnx --export_path ./examples/elastic_cnn_example/model.onnx
+python -m wavedl.test --checkpoint ./examples/elasticity_prediction/best_checkpoint \
+  --data_path ./examples/elasticity_prediction/Test_data_100.mat \
+  --export onnx --export_path ./examples/elasticity_prediction/model.onnx
 ```
 
 **What's Included:**
 
 | File | Description |
 |------|-------------|
-| `best_checkpoint/` | Pre-trained CNN checkpoint |
-| `Test_data_500.mat` | 500 sample test set (500×500 dispersion curves → *h*, √(*E*/ρ), *ν*) |
+| `best_checkpoint/` | Pre-trained MobileNetV3 checkpoint |
+| `Test_data_100.mat` | 100 sample test set (500×500 dispersion curves → *h*, √(*E*/ρ), *ν*) |
 | `model.onnx` | ONNX export with embedded de-normalization |
 | `training_history.csv` | Epoch-by-epoch training metrics (loss, R², LR, etc.) |
 | `training_curves.png` | Training/validation loss and learning rate plot |
@@ -1070,59 +1071,59 @@ python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoin
 **Training Progress:**
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/training_curves.png" alt="Training curves" width="600"><br>
-  <em>Training and validation loss over 227 epochs with <code>onecycle</code> learning rate schedule</em>
+  <img src="examples/elasticity_prediction/training_curves.png" alt="Training curves" width="600"><br>
+  <em>Training and validation loss with <code>plateau</code> learning rate schedule</em>
 </p>
 
 **Inference Results:**
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/scatter_all.png" alt="Scatter plot" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/scatter_all.png" alt="Scatter plot" width="700"><br>
   <em>Figure 1: Predictions vs ground truth for all three elastic parameters</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/error_histogram.png" alt="Error histogram" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/error_histogram.png" alt="Error histogram" width="700"><br>
   <em>Figure 2: Distribution of prediction errors showing near-zero mean bias</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/residuals.png" alt="Residual plot" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/residuals.png" alt="Residual plot" width="700"><br>
   <em>Figure 3: Residuals vs predicted values (no heteroscedasticity detected)</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/bland_altman.png" alt="Bland-Altman plot" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/bland_altman.png" alt="Bland-Altman plot" width="700"><br>
   <em>Figure 4: Bland-Altman analysis with ±1.96 SD limits of agreement</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/qq_plot.png" alt="Q-Q plot" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/qq_plot.png" alt="Q-Q plot" width="700"><br>
   <em>Figure 5: Q-Q plots confirming normally distributed prediction errors</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/error_correlation.png" alt="Error correlation" width="300"><br>
+  <img src="examples/elasticity_prediction/test_results/error_correlation.png" alt="Error correlation" width="300"><br>
   <em>Figure 6: Error correlation matrix between parameters</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/relative_error.png" alt="Relative error" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/relative_error.png" alt="Relative error" width="700"><br>
   <em>Figure 7: Relative error (%) vs true value for each parameter</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/error_cdf.png" alt="Error CDF" width="500"><br>
+  <img src="examples/elasticity_prediction/test_results/error_cdf.png" alt="Error CDF" width="500"><br>
   <em>Figure 8: Cumulative error distribution — 95% of predictions within indicated bounds</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/prediction_vs_index.png" alt="Prediction vs index" width="700"><br>
+  <img src="examples/elasticity_prediction/test_results/prediction_vs_index.png" alt="Prediction vs index" width="700"><br>
   <em>Figure 9: True vs predicted values by sample index</em>
 </p>
 
 <p align="center">
-  <img src="examples/elastic_cnn_example/test_results/error_boxplot.png" alt="Error box plot" width="400"><br>
+  <img src="examples/elasticity_prediction/test_results/error_boxplot.png" alt="Error box plot" width="400"><br>
   <em>Figure 10: Error distribution summary (median, quartiles, outliers)</em>
 </p>
 

{wavedl-1.5.4.dist-info → wavedl-1.5.6.dist-info}/RECORD

@@ -1,8 +1,8 @@
-wavedl/__init__.py,sha256=L3ckuWk3BDr6h9oiADkGP_JKcGSF669qDkuzofh86IU,1177
+wavedl/__init__.py,sha256=qesevvzcBx9pJrvfW07e7PB9_sjb1eOL1BrWpUF-wZM,1177
 wavedl/hpc.py,sha256=6rV38nozzMt0-jKZbVJNwvQZXK0wUsIZmr9lgWN_XUw,9212
-wavedl/hpo.py,sha256=DGCGyt2yhr3WAifAuljhE26gg07CHdaQW4wpDaTKbyo,14968
+wavedl/hpo.py,sha256=CZF0MZwTGMOrPGDveUXZFbGHwLHj1FcJTCBKVVEtLWg,15105
 wavedl/test.py,sha256=WIHG3HWT-uF399FQApPpxjggBVFn59cC54HAL4990QU,38550
-wavedl/train.py,sha256=7AVaCORFUv2_IgdYSPKdHLxbi11GzMOyu4RcNc4Uf_I,55963
+wavedl/train.py,sha256=JlSXWyTdU4S_PTgvANqXN4ceCS9KONOybbRksDPPcuo,57570
 wavedl/models/__init__.py,sha256=lfSohEnAUztO14nuwayMJhPjpgySzRN3jGiyAUuBmAU,3206
 wavedl/models/_template.py,sha256=J_D8taSPmV8lBaucN_vU-WiG98iFr7CJrZVNNX_Tdts,4600
 wavedl/models/base.py,sha256=T9iDF9IQM2MYucG_ggQd31rieUkB2fob-nkHyNIl2ak,7337
@@ -19,20 +19,20 @@ wavedl/models/resnet3d.py,sha256=C7CL4XeSnRlIBuwf5Ei-z183uzIBObrXfkM9Iwuc5e0,874
 wavedl/models/swin.py,sha256=cbV_iqIS4no-EAUR8j_93gqd59AkAkfM5DYo6VryLEg,13937
 wavedl/models/tcn.py,sha256=RtY13QpFHqz72b4ultv2lStCIDxfvjySVe5JaTx_GaM,12601
 wavedl/models/unet.py,sha256=LqIXhasdBygwP7SZNNmiW1bHMPaJTVBpaeHtPgEHkdU,7790
-wavedl/models/vit.py,sha256=68o9nNjkftvHFArAPupU2ew5e5yCsI2AYaT9TQinVMk,12075
+wavedl/models/vit.py,sha256=D4jlYAlvegb3O19jCPpUHYmt5q0SZ7EGVBIWiYbq0GA,14816
 wavedl/utils/__init__.py,sha256=s5R9bRmJ8GNcJrD3OSAOXzwZJIXZbdYrAkZnus11sVQ,3300
 wavedl/utils/config.py,sha256=AsGwb3XtxmbTLb59BLl5AA4wzMNgVTpl7urOJ6IGqfM,10901
 wavedl/utils/constraints.py,sha256=Pof5hzeTSGsPY_E6Sc8iMQDaXc_zfEasQI2tCszk_gw,17614
 wavedl/utils/cross_validation.py,sha256=gwXSFTx5oxWndPjWLJAJzB6nnq2f1t9f86SbjbF-jNI,18475
-wavedl/utils/data.py,sha256=JusSrIZd98t9oiN0xTy2V2mfVyuBCIu0MLAQGcaC0vQ,54194
+wavedl/utils/data.py,sha256=l8aqC7mtnUyXPOS0cCbgE-jS8TKndXnHU2WiP1VU1Zk,58361
 wavedl/utils/distributed.py,sha256=7wQ3mRjkp_xjPSxDWMnBf5dSkAGUaTzntxbz0BhC5v0,4145
 wavedl/utils/losses.py,sha256=5762M-TBC_hz6uyj1NPbU1vZeFOJQq7fR3-j7OygJRo,7254
-wavedl/utils/metrics.py,sha256=EJmJvF7gACQsUoKYldlladN_SbnRiuE-Smj0eSnbraQ,39394
+wavedl/utils/metrics.py,sha256=El2NYsulH5jxBhC1gCAMcS8C-yxEjuSC930LhsKYQrY,40059
 wavedl/utils/optimizers.py,sha256=PyIkJ_hRhFi_Fio81Gy5YQNhcME0JUUEl8OTSyu-0RA,6323
 wavedl/utils/schedulers.py,sha256=e6Sf0yj8VOqkdwkUHLMyUfGfHKTX4NMr-zfgxWqCTYI,7659
-wavedl-1.5.4.dist-info/LICENSE,sha256=cEUCvcvH-9BT9Y-CNGY__PwWONCKu9zsoIqWA-NeHJ4,1066
-wavedl-1.5.4.dist-info/METADATA,sha256=D7_MbjGWyVEIEH2m23GrJInZO4pcfHAINlY1FIUgD-A,45604
-wavedl-1.5.4.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
-wavedl-1.5.4.dist-info/entry_points.txt,sha256=f1RNDkXFZwBzrBzTMFocJ6xhfTvTmaEDTi5YyDEUaF8,140
-wavedl-1.5.4.dist-info/top_level.txt,sha256=ccneUt3D5Qzbh3bsBSSrq9bqrhGiogcWKY24ZC4Q6Xw,7
-wavedl-1.5.4.dist-info/RECORD,,
+wavedl-1.5.6.dist-info/LICENSE,sha256=cEUCvcvH-9BT9Y-CNGY__PwWONCKu9zsoIqWA-NeHJ4,1066
+wavedl-1.5.6.dist-info/METADATA,sha256=lLNnw1m1vOKEvFKr-9-v3xb71RHqDUUJxqu4VzNR8eI,45715
+wavedl-1.5.6.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
+wavedl-1.5.6.dist-info/entry_points.txt,sha256=f1RNDkXFZwBzrBzTMFocJ6xhfTvTmaEDTi5YyDEUaF8,140
+wavedl-1.5.6.dist-info/top_level.txt,sha256=ccneUt3D5Qzbh3bsBSSrq9bqrhGiogcWKY24ZC4Q6Xw,7
+wavedl-1.5.6.dist-info/RECORD,,