wavedl 1.6.1__py3-none-any.whl → 1.6.3__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.6.1"
+__version__ = "1.6.3"
 __author__ = "Ductho Le"
 __email__ = "ductho.le@outlook.com"
 

wavedl/hpo.py

@@ -440,7 +440,7 @@ Examples:
     print("\n" + "=" * 60)
     print("TO TRAIN WITH BEST PARAMETERS:")
     print("=" * 60)
-    cmd_parts = ["accelerate launch -m wavedl.train"]
+    cmd_parts = ["wavedl-train"]
     cmd_parts.append(f"--data_path {args.data_path}")
     for key, value in study.best_params.items():
         cmd_parts.append(f"--{key} {value}")

wavedl/{hpc.py → launcher.py}

@@ -1,12 +1,21 @@
 #!/usr/bin/env python
 """
-WaveDL HPC Training Launcher.
+WaveDL Training Launcher.
 
-This module provides a Python-based HPC training launcher that wraps accelerate
-for distributed training on High-Performance Computing clusters.
+This module provides a universal training launcher that wraps accelerate
+for distributed training. It works seamlessly on both:
+- Local machines (uses standard cache locations)
+- HPC clusters (uses local caching, offline WandB)
+
+The environment is auto-detected based on scheduler variables (SLURM, PBS, etc.)
+and home directory writability.
 
 Usage:
-    wavedl-hpc --model cnn --data_path train.npz --num_gpus 4
+    # Local machine or HPC - same command!
+    wavedl-train --model cnn --data_path train.npz --output_dir results
+
+    # Multi-GPU is automatic (uses all available GPUs)
+    wavedl-train --model resnet18 --data_path train.npz --num_gpus 4
 
 Example SLURM script:
     #!/bin/bash
@@ -14,7 +23,7 @@ Example SLURM script:
     #SBATCH --gpus-per-node=4
     #SBATCH --time=12:00:00
 
-    wavedl-hpc --model cnn --data_path /scratch/data.npz --compile
+    wavedl-train --model cnn --data_path /scratch/data.npz --compile
 
 Author: Ductho Le (ductho.le@outlook.com)
 """
@@ -53,78 +62,138 @@ def detect_gpus() -> int:
     return 1
 
 
-def setup_hpc_environment() -> None:
-    """Configure environment variables for HPC systems.
+def is_hpc_environment() -> bool:
+    """Detect if running on an HPC cluster.
+
+    Checks for:
+    1. Common HPC scheduler environment variables (SLURM, PBS, LSF, SGE, Cobalt)
+    2. Non-writable home directory (common on HPC systems)
 
-    Handles restricted home directories (e.g., Compute Canada) and
-    offline logging configurations. Always uses CWD-based TORCH_HOME
-    since compute nodes typically lack internet access.
+    Returns:
+        True if HPC environment detected, False otherwise.
     """
-    # Use CWD for cache base since HPC compute nodes typically lack internet
-    cache_base = os.getcwd()
+    # Check for common HPC scheduler environment variables
+    hpc_indicators = [
+        "SLURM_JOB_ID",  # SLURM
+        "PBS_JOBID",  # PBS/Torque
+        "LSB_JOBID",  # LSF
+        "SGE_TASK_ID",  # Sun Grid Engine
+        "COBALT_JOBID",  # Cobalt
+    ]
+    if any(var in os.environ for var in hpc_indicators):
+        return True
 
-    # TORCH_HOME always set to CWD - compute nodes need pre-cached weights
-    os.environ.setdefault("TORCH_HOME", f"{cache_base}/.torch_cache")
-    Path(os.environ["TORCH_HOME"]).mkdir(parents=True, exist_ok=True)
+    # Check if home directory is not writable (common on HPC)
+    home = os.path.expanduser("~")
+    return not os.access(home, os.W_OK)
 
-    # Triton/Inductor caches - prevents permission errors with --compile
-    # These MUST be set before any torch.compile calls
-    os.environ.setdefault("TRITON_CACHE_DIR", f"{cache_base}/.triton_cache")
-    os.environ.setdefault("TORCHINDUCTOR_CACHE_DIR", f"{cache_base}/.inductor_cache")
-    Path(os.environ["TRITON_CACHE_DIR"]).mkdir(parents=True, exist_ok=True)
-    Path(os.environ["TORCHINDUCTOR_CACHE_DIR"]).mkdir(parents=True, exist_ok=True)
 
-    # Check if home is writable for other caches
-    home = os.path.expanduser("~")
-    home_writable = os.access(home, os.W_OK)
-
-    # Other caches only if home is not writable
-    if not home_writable:
-        os.environ.setdefault("MPLCONFIGDIR", f"{cache_base}/.matplotlib")
-        os.environ.setdefault("FONTCONFIG_CACHE", f"{cache_base}/.fontconfig")
-        os.environ.setdefault("XDG_CACHE_HOME", f"{cache_base}/.cache")
-
-        # Ensure directories exist
-        for env_var in [
-            "MPLCONFIGDIR",
-            "FONTCONFIG_CACHE",
-            "XDG_CACHE_HOME",
-        ]:
-            Path(os.environ[env_var]).mkdir(parents=True, exist_ok=True)
-
-    # WandB configuration (offline by default for HPC)
-    os.environ.setdefault("WANDB_MODE", "offline")
-    os.environ.setdefault("WANDB_DIR", f"{cache_base}/.wandb")
-    os.environ.setdefault("WANDB_CACHE_DIR", f"{cache_base}/.wandb_cache")
-    os.environ.setdefault("WANDB_CONFIG_DIR", f"{cache_base}/.wandb_config")
-
-    # Suppress non-critical warnings
+def setup_environment() -> None:
+    """Configure environment for HPC or local machine.
+
+    Automatically detects the environment and configures accordingly:
+    - HPC: Uses CWD-based caching, offline WandB (compute nodes lack internet)
+    - Local: Uses standard cache locations (~/.cache), doesn't override WandB
+    """
+    is_hpc = is_hpc_environment()
+
+    if is_hpc:
+        # HPC: use CWD-based caching (compute nodes lack internet)
+        cache_base = os.getcwd()
+
+        # TORCH_HOME set to CWD - compute nodes need pre-cached weights
+        os.environ.setdefault("TORCH_HOME", f"{cache_base}/.torch_cache")
+        Path(os.environ["TORCH_HOME"]).mkdir(parents=True, exist_ok=True)
+
+        # Triton/Inductor caches - prevents permission errors with --compile
+        os.environ.setdefault("TRITON_CACHE_DIR", f"{cache_base}/.triton_cache")
+        os.environ.setdefault(
+            "TORCHINDUCTOR_CACHE_DIR", f"{cache_base}/.inductor_cache"
+        )
+        Path(os.environ["TRITON_CACHE_DIR"]).mkdir(parents=True, exist_ok=True)
+        Path(os.environ["TORCHINDUCTOR_CACHE_DIR"]).mkdir(parents=True, exist_ok=True)
+
+        # Check if home is writable for other caches
+        home = os.path.expanduser("~")
+        home_writable = os.access(home, os.W_OK)
+
+        # Other caches only if home is not writable
+        if not home_writable:
+            os.environ.setdefault("MPLCONFIGDIR", f"{cache_base}/.matplotlib")
+            os.environ.setdefault("FONTCONFIG_CACHE", f"{cache_base}/.fontconfig")
+            os.environ.setdefault("XDG_CACHE_HOME", f"{cache_base}/.cache")
+
+            for env_var in [
+                "MPLCONFIGDIR",
+                "FONTCONFIG_CACHE",
+                "XDG_CACHE_HOME",
+            ]:
+                Path(os.environ[env_var]).mkdir(parents=True, exist_ok=True)
+
+        # WandB configuration (offline by default for HPC)
+        os.environ.setdefault("WANDB_MODE", "offline")
+        os.environ.setdefault("WANDB_DIR", f"{cache_base}/.wandb")
+        os.environ.setdefault("WANDB_CACHE_DIR", f"{cache_base}/.wandb_cache")
+        os.environ.setdefault("WANDB_CONFIG_DIR", f"{cache_base}/.wandb_config")
+
+        print("🖥️  HPC environment detected - using local caching")
+    else:
+        # Local machine: use standard locations, don't override user settings
+        # TORCH_HOME defaults to ~/.cache/torch (PyTorch default)
+        # WANDB_MODE defaults to online (WandB default)
+        print("💻 Local environment detected - using standard cache locations")
+
+    # Suppress non-critical warnings (both environments)
     os.environ.setdefault(
         "PYTHONWARNINGS",
         "ignore::UserWarning,ignore::FutureWarning,ignore::DeprecationWarning",
     )
 
 
+def handle_fast_path_args() -> int | None:
+    """Handle utility flags that don't need accelerate launch.
+
+    Returns:
+        Exit code if handled (0 for success), None if should continue to full launch.
+    """
+    # --list_models: print models and exit immediately
+    if "--list_models" in sys.argv:
+        from wavedl.models import list_models
+
+        print("Available models:")
+        for name in list_models():
+            print(f"  {name}")
+        return 0
+
+    return None  # Continue to full launch
+
+
 def parse_args() -> tuple[argparse.Namespace, list[str]]:
-    """Parse HPC-specific arguments, pass remaining to wavedl.train."""
+    """Parse launcher-specific arguments, pass remaining to wavedl.train."""
     parser = argparse.ArgumentParser(
-        description="WaveDL HPC Training Launcher",
+        description="WaveDL Training Launcher (works on local machines and HPC clusters)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  # Basic training with auto-detected GPUs
-  wavedl-hpc --model cnn --data_path train.npz --epochs 100
+  # Basic training (auto-detects GPUs and environment)
+  wavedl-train --model cnn --data_path train.npz --output_dir results
 
-  # Specify GPU count and mixed precision
-  wavedl-hpc --model cnn --data_path train.npz --num_gpus 4 --mixed_precision bf16
+  # Specify GPU count explicitly
+  wavedl-train --model cnn --data_path train.npz --num_gpus 4
 
   # Full configuration
-  wavedl-hpc --model resnet18 --data_path train.npz --num_gpus 8 \\
-             --batch_size 256 --lr 1e-3 --compile --output_dir ./results
+  wavedl-train --model resnet18 --data_path train.npz --batch_size 256 \\
+               --lr 1e-3 --epochs 100 --compile --output_dir ./results
+
+  # List available models
+  wavedl-train --list_models
 
-Environment Variables:
-  WANDB_MODE          WandB mode: offline|online (default: offline)
-  SLURM_TMPDIR        Temp directory for HPC systems
+Environment Detection:
+  The launcher automatically detects your environment:
+  - HPC (SLURM, PBS, etc.): Uses local caching, offline WandB
+  - Local machine: Uses standard cache locations (~/.cache)
+
+For full training options, see: python -m wavedl.train --help
 """,
     )
 
@@ -204,7 +273,7 @@ def print_summary(
         print("Common issues:")
         print("  - Missing data file (check --data_path)")
         print("  - Insufficient GPU memory (reduce --batch_size)")
-        print("  - Invalid model name (run: python train.py --list_models)")
+        print("  - Invalid model name (run: wavedl-train --list_models)")
         print()
 
     print("=" * 40)
@@ -212,12 +281,17 @@ def print_summary(
 
 
 def main() -> int:
-    """Main entry point for wavedl-hpc command."""
+    """Main entry point for wavedl-train command."""
+    # Fast path for utility flags (avoid accelerate launch overhead)
+    exit_code = handle_fast_path_args()
+    if exit_code is not None:
+        return exit_code
+
     # Parse arguments
     args, train_args = parse_args()
 
-    # Setup HPC environment
-    setup_hpc_environment()
+    # Setup environment (smart detection)
+    setup_environment()
 
     # Check if wavedl package is importable
     try:

wavedl/models/__init__.py

@@ -77,6 +77,15 @@ from .unet import UNetRegression
 from .vit import ViTBase_, ViTSmall, ViTTiny
 
 
+# Optional RATENet (unpublished, may be gitignored)
+try:
+    from .ratenet import RATENet, RATENetLite, RATENetTiny, RATENetV2
+
+    _HAS_RATENET = True
+except ImportError:
+    _HAS_RATENET = False
+
+
 # Optional timm-based models (imported conditionally)
 try:
     from .caformer import CaFormerS18, CaFormerS36, PoolFormerS12
@@ -111,6 +120,7 @@ __all__ = [
     "MC3_18",
     "MODEL_REGISTRY",
     "TCN",
+    # Classes (uppercase first, alphabetically)
     "BaseModel",
     "ConvNeXtBase_",
     "ConvNeXtSmall",
@@ -152,6 +162,7 @@ __all__ = [
     "VimBase",
     "VimSmall",
     "VimTiny",
+    # Functions (lowercase, alphabetically)
     "build_model",
     "get_model",
     "list_models",
@@ -186,3 +197,14 @@ if _HAS_TIMM_MODELS:
             "UniRepLKNetTiny",
         ]
     )
+
+# Add RATENet models to __all__ if available (unpublished)
+if _HAS_RATENET:
+    __all__.extend(
+        [
+            "RATENet",
+            "RATENetLite",
+            "RATENetTiny",
+            "RATENetV2",
+        ]
+    )

wavedl/test.py

@@ -398,6 +398,14 @@ def load_checkpoint(
 
     if HAS_SAFETENSORS and weight_path.suffix == ".safetensors":
         state_dict = load_safetensors(str(weight_path))
+    elif weight_path.suffix == ".safetensors":
+        # Safetensors file exists but library not installed
+        raise ImportError(
+            f"Checkpoint uses safetensors format ({weight_path.name}) but "
+            f"'safetensors' package is not installed. Install it with:\n"
+            f"    pip install safetensors\n"
+            f"Or convert the checkpoint to PyTorch format (model.bin)."
+        )
     else:
         state_dict = torch.load(weight_path, map_location="cpu", weights_only=True)
 

wavedl/train.py

@@ -12,25 +12,22 @@ A modular training framework for wave-based inverse problems and regression:
   6. Deep Observability: WandB integration with scatter analysis
 
 Usage:
-    # Recommended: Using the HPC launcher (handles accelerate configuration)
-    wavedl-hpc --model cnn --batch_size 128 --mixed_precision bf16 --wandb
-
-    # Or direct training module (use --precision, not --mixed_precision)
-    accelerate launch -m wavedl.train --model cnn --batch_size 128 --precision bf16
+    # Recommended: Universal training command (works on local machines and HPC)
+    wavedl-train --model cnn --batch_size 128 --compile
 
     # Multi-GPU with explicit config
-    wavedl-hpc --num_gpus 4 --mixed_precision bf16 --model cnn --wandb
+    wavedl-train --num_gpus 4 --model cnn --output_dir results
 
     # Resume from checkpoint
-    accelerate launch -m wavedl.train --model cnn --resume best_checkpoint --wandb
+    wavedl-train --model cnn --output_dir results  # auto-resumes if interrupted
 
     # List available models
     wavedl-train --list_models
 
 Note:
-    - wavedl-hpc: Uses --mixed_precision (passed to accelerate launch)
-    - wavedl.train: Uses --precision (internal module flag)
-    Both control the same behavior; use the appropriate flag for your entry point.
+    wavedl-train automatically detects your environment:
+    - HPC clusters (SLURM, PBS, etc.): Uses local caching, offline WandB
+    - Local machines: Uses standard cache locations (~/.cache)
 
 Author: Ductho Le (ductho.le@outlook.com)
 """
@@ -429,7 +426,7 @@ def parse_args() -> argparse.Namespace:
         choices=["bf16", "fp16", "no"],
         help="Mixed precision mode",
     )
-    # Alias for consistency with wavedl-hpc (--mixed_precision)
+    # Alias for consistency with wavedl-train (--mixed_precision is passed to accelerate)
     parser.add_argument(
         "--mixed_precision",
         dest="precision",
@@ -1269,10 +1266,10 @@ def main():
                         os.path.join(args.output_dir, "best_model_weights.pth"),
                     )
 
-                    # Copy scaler to checkpoint for portability
+                    # Copy scaler to checkpoint for portability (always overwrite to stay current)
                     scaler_src = os.path.join(args.output_dir, "scaler.pkl")
                     scaler_dst = os.path.join(ckpt_dir, "scaler.pkl")
-                    if os.path.exists(scaler_src) and not os.path.exists(scaler_dst):
+                    if os.path.exists(scaler_src):
                         shutil.copy2(scaler_src, scaler_dst)
 
                     logger.info(

wavedl/utils/data.py

@@ -984,7 +984,15 @@ def load_test_data(
                 f"Available keys depend on file format. Original error: {e}"
             ) from e
 
-        # Legitimate fallback: no explicit output_key, outputs just not present
+        # Also fail-fast if explicit input_key was provided but not found
+        # This prevents silently loading a different tensor when user mistyped key
+        if input_key is not None:
+            raise KeyError(
+                f"Explicit --input_key '{input_key}' not found in file. "
+                f"Original error: {e}"
+            ) from e
+
+        # Legitimate fallback: no explicit keys, outputs just not present
         if format == "npz":
             # First pass to find keys
             with np.load(path, allow_pickle=False) as probe:
@@ -1524,21 +1532,43 @@ def prepare_data(
 
             logger.info("   ✔ Cache creation complete, synchronizing ranks...")
         else:
-            # NON-MAIN RANKS: Wait for cache creation
-            # Log that we're waiting (helps with debugging)
+            # NON-MAIN RANKS: Wait for cache creation with timeout
+            # Use monotonic clock (immune to system clock changes)
             import time
 
-            wait_start = time.time()
+            wait_start = time.monotonic()
+
+            # Robust env parsing with guards for invalid/non-positive values
+            DEFAULT_CACHE_TIMEOUT = 3600  # 1 hour default
+            try:
+                env_timeout = os.environ.get("WAVEDL_CACHE_TIMEOUT", "")
+                CACHE_TIMEOUT = (
+                    int(env_timeout) if env_timeout else DEFAULT_CACHE_TIMEOUT
+                )
+                if CACHE_TIMEOUT <= 0:
+                    CACHE_TIMEOUT = DEFAULT_CACHE_TIMEOUT
+            except ValueError:
+                CACHE_TIMEOUT = DEFAULT_CACHE_TIMEOUT
+
             while not (
                 os.path.exists(CACHE_FILE)
                 and os.path.exists(SCALER_FILE)
                 and os.path.exists(META_FILE)
             ):
                 time.sleep(5)  # Check every 5 seconds
-                elapsed = time.time() - wait_start
+                elapsed = time.monotonic() - wait_start
+
+                if elapsed > CACHE_TIMEOUT:
+                    raise RuntimeError(
+                        f"[Rank {accelerator.process_index}] Timeout waiting for cache "
+                        f"files after {CACHE_TIMEOUT}s. Rank 0 may have failed during "
+                        f"cache generation. Check rank 0 logs for errors."
+                    )
+
                 if elapsed > 60 and int(elapsed) % 60 < 5:  # Log every ~minute
                     logger.info(
-                        f"   [Rank {accelerator.process_index}] Waiting for cache creation... ({int(elapsed)}s)"
+                        f"   [Rank {accelerator.process_index}] Waiting for cache "
+                        f"creation... ({int(elapsed)}s / {CACHE_TIMEOUT}s max)"
                     )
             # Small delay to ensure files are fully written
             time.sleep(2)

{wavedl-1.6.1.dist-info → wavedl-1.6.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: wavedl
-Version: 1.6.1
+Version: 1.6.3
 Summary: A Scalable Deep Learning Framework for Wave-Based Inverse Problems
 Author: Ductho Le
 License: MIT
@@ -214,77 +214,83 @@ This installs everything you need: training, inference, HPO, ONNX export.
 ```bash
 git clone https://github.com/ductho-le/WaveDL.git
 cd WaveDL
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 > [!NOTE]
-> Python 3.11+ required. For development setup, see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+> Python 3.11+ required. For contributor setup (pre-commit hooks), see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
 ### Quick Start
 
 > [!TIP]
 > In all examples below, replace `<...>` placeholders with your values. See [Configuration](#️-configuration) for defaults and options.
 
-#### Option 1: Using wavedl-hpc (Recommended for HPC)
-
-The `wavedl-hpc` command automatically configures the environment for HPC systems:
+### Training
 
 ```bash
-# Basic training (auto-detects available GPUs)
-wavedl-hpc --model <model_name> --data_path <train_data> --batch_size <number> --output_dir <output_folder>
+# Basic training (auto-detects GPUs and environment)
+wavedl-train --model <model_name> --data_path <train_data> --output_dir <output_folder>
 
 # Detailed configuration
-wavedl-hpc --model <model_name> --data_path <train_data> --batch_size <number> \
+wavedl-train --model <model_name> --data_path <train_data> --batch_size <number> \
   --lr <number> --epochs <number> --patience <number> --compile --output_dir <output_folder>
 
-# Specify GPU count explicitly
-wavedl-hpc --num_gpus 4 --model cnn --data_path train.npz --output_dir results
-```
-
-#### Option 2: Direct Accelerate Launch
-
-```bash
-# Local - auto-detects GPUs
-accelerate launch -m wavedl.train --model <model_name> --data_path <train_data> --batch_size <number> --output_dir <output_folder>
+# Multi-GPU is automatic (uses all available GPUs)
+# Override with --num_gpus if needed
+wavedl-train --model cnn --data_path train.npz --num_gpus 4 --output_dir results
 
 # Resume training (automatic - just re-run with same output_dir)
-# Manual resume from specific checkpoint:
-accelerate launch -m wavedl.train --model <model_name> --data_path <train_data> --resume <checkpoint_folder> --output_dir <output_folder>
+wavedl-train --model <model_name> --data_path <train_data> --output_dir <output_folder>
 
 # Force fresh start (ignores existing checkpoints)
-accelerate launch -m wavedl.train --model <model_name> --data_path <train_data> --output_dir <output_folder> --fresh
+wavedl-train --model <model_name> --data_path <train_data> --output_dir <output_folder> --fresh
 
 # List available models
 wavedl-train --list_models
 ```
 
-> [!TIP]
-> **Auto-Resume**: If training crashes or is interrupted, simply re-run with the same `--output_dir`. The framework automatically detects incomplete training and resumes from the last checkpoint. Use `--fresh` to force a fresh start.
+> [!NOTE]
+> `wavedl-train` automatically detects your environment:
+> - **HPC clusters** (SLURM, PBS, etc.): Uses local caching, offline WandB
+> - **Local machines**: Uses standard cache locations (~/.cache)
 >
-> **GPU Auto-Detection**: `wavedl-hpc` automatically detects available GPUs using `nvidia-smi`. Use `--num_gpus` to override.
+> **Auto-Resume**: If training crashes or is interrupted, simply re-run with the same `--output_dir`. The framework automatically detects incomplete training and resumes from the last checkpoint.
 
-### Testing & Inference
+<details>
+<summary><b>Advanced: Direct Accelerate Launch</b></summary>
+
+For fine-grained control over distributed training, you can use `accelerate launch` directly:
 
-After training, use `wavedl.test` to evaluate your model on test data:
+```bash
+# Custom accelerate configuration
+accelerate launch -m wavedl.train --model <model_name> --data_path <train_data> --output_dir <output_folder>
+
+# Multi-node training
+accelerate launch --num_machines 2 --main_process_ip <ip> -m wavedl.train --model cnn --data_path train.npz
+```
+
+</details>
+
+### Testing & Inference
 
 ```bash
 # Basic inference
-python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data>
+wavedl-test --checkpoint <checkpoint_folder> --data_path <test_data>
 
 # With visualization, CSV export, and multiple file formats
-python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
+wavedl-test --checkpoint <checkpoint_folder> --data_path <test_data> \
   --plot --plot_format png pdf --save_predictions --output_dir <output_folder>
 
 # With custom parameter names
-python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
+wavedl-test --checkpoint <checkpoint_folder> --data_path <test_data> \
   --param_names '$p_1$' '$p_2$' '$p_3$' --plot
 
 # Export model to ONNX for deployment (LabVIEW, MATLAB, C++, etc.)
-python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
+wavedl-test --checkpoint <checkpoint_folder> --data_path <test_data> \
   --export onnx --export_path <output_file.onnx>
 
 # For 3D volumes with small depth (e.g., 8×128×128), override auto-detection
-python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
+wavedl-test --checkpoint <checkpoint_folder> --data_path <test_data> \
   --input_channels 1
 ```
 
@@ -295,7 +301,7 @@ python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
 - **Format** (with `--plot_format`): Supported formats: `png` (default), `pdf` (vector), `svg` (vector), `eps` (LaTeX), `tiff`, `jpg`, `ps`
 
 > [!NOTE]
-> `wavedl.test` auto-detects the model architecture from checkpoint metadata. If unavailable, it falls back to folder name parsing. Use `--model` to override if needed.
+> `wavedl-test` auto-detects the model architecture from checkpoint metadata. If unavailable, it falls back to folder name parsing. Use `--model` to override if needed.
 
 ### Adding Custom Models
 
@@ -339,7 +345,7 @@ class MyModel(BaseModel):
 **Step 2: Train**
 
 ```bash
-wavedl-hpc --import my_model.py --model my_model --data_path train.npz
+wavedl-train --import my_model.py --model my_model --data_path train.npz
 ```
 
 WaveDL handles everything else: training loop, logging, checkpoints, multi-GPU, early stopping, etc.
@@ -355,10 +361,10 @@ WaveDL/
 ├── src/
 │   └── wavedl/                   # Main package (namespaced)
 │       ├── __init__.py           # Package init with __version__
-│       ├── train.py              # Training entry point
+│       ├── train.py              # Training script
 │       ├── test.py               # Testing & inference script
 │       ├── hpo.py                # Hyperparameter optimization
-│       ├── hpc.py                # HPC distributed training launcher
+│       ├── launcher.py           # Training launcher (wavedl-train)
 │       │
 │       ├── models/               # Model Zoo (69 architectures)
 │       │   ├── registry.py       # Model factory (@register_model)
@@ -389,16 +395,7 @@ WaveDL/
 ## ⚙️ Configuration
 
 > [!NOTE]
-> All configuration options below work with **both** `wavedl-hpc` and direct `accelerate launch`. The wrapper script passes all arguments directly to `train.py`.
->
-> **Examples:**
-> ```bash
-> # Using wavedl-hpc
-> wavedl-hpc --model cnn --batch_size 256 --lr 5e-4 --compile
->
-> # Using accelerate launch directly
-> accelerate launch -m wavedl.train --model cnn --batch_size 256 --lr 5e-4 --compile
-> ```
+> All configuration options below work with `wavedl-train`. The wrapper script passes all arguments directly to `train.py`.
 
 <details>
 <summary><b>Available Models</b> — 69 architectures</summary>
@@ -642,7 +639,7 @@ WaveDL automatically enables performance optimizations for modern GPUs:
 </details>
 
 <details>
-<summary><b>HPC CLI Arguments (wavedl-hpc)</b></summary>
+<summary><b>Distributed Training Arguments</b></summary>
 
 | Argument | Default | Description |
 |----------|---------|-------------|
@@ -674,10 +671,10 @@ WaveDL automatically enables performance optimizations for modern GPUs:
 **Example:**
 ```bash
 # Use Huber loss for noisy NDE data
-accelerate launch -m wavedl.train --model cnn --loss huber --huber_delta 0.5
+wavedl-train --model cnn --loss huber --huber_delta 0.5
 
 # Weighted MSE: prioritize thickness (first target)
-accelerate launch -m wavedl.train --model cnn --loss weighted_mse --loss_weights "2.0,1.0,1.0"
+wavedl-train --model cnn --loss weighted_mse --loss_weights "2.0,1.0,1.0"
 ```
 
 </details>
@@ -697,10 +694,10 @@ accelerate launch -m wavedl.train --model cnn --loss weighted_mse --loss_weights
 **Example:**
 ```bash
 # SGD with Nesterov momentum (often better generalization)
-accelerate launch -m wavedl.train --model cnn --optimizer sgd --lr 0.01 --momentum 0.9 --nesterov
+wavedl-train --model cnn --optimizer sgd --lr 0.01 --momentum 0.9 --nesterov
 
 # RAdam for more stable training
-accelerate launch -m wavedl.train --model cnn --optimizer radam --lr 1e-3
+wavedl-train --model cnn --optimizer radam --lr 1e-3
 ```
 
 </details>
@@ -722,13 +719,13 @@ accelerate launch -m wavedl.train --model cnn --optimizer radam --lr 1e-3
 **Example:**
 ```bash
 # Cosine annealing for 1000 epochs
-accelerate launch -m wavedl.train --model cnn --scheduler cosine --epochs 1000 --min_lr 1e-7
+wavedl-train --model cnn --scheduler cosine --epochs 1000 --min_lr 1e-7
 
 # OneCycleLR for super-convergence
-accelerate launch -m wavedl.train --model cnn --scheduler onecycle --lr 1e-2 --epochs 50
+wavedl-train --model cnn --scheduler onecycle --lr 1e-2 --epochs 50
 
 # MultiStep with custom milestones
-accelerate launch -m wavedl.train --model cnn --scheduler multistep --milestones "100,200,300"
+wavedl-train --model cnn --scheduler multistep --milestones "100,200,300"
 ```
 
 </details>
@@ -739,16 +736,14 @@ accelerate launch -m wavedl.train --model cnn --scheduler multistep --milestones
 For robust model evaluation, simply add the `--cv` flag:
 
 ```bash
-# 5-fold cross-validation (works with both methods!)
-wavedl-hpc --model cnn --cv 5 --data_path train_data.npz
-# OR
-accelerate launch -m wavedl.train --model cnn --cv 5 --data_path train_data.npz
+# 5-fold cross-validation
+wavedl-train --model cnn --cv 5 --data_path train_data.npz
 
 # Stratified CV (recommended for unbalanced data)
-wavedl-hpc --model cnn --cv 5 --cv_stratify --loss huber --epochs 100
+wavedl-train --model cnn --cv 5 --cv_stratify --loss huber --epochs 100
 
 # Full configuration
-wavedl-hpc --model cnn --cv 5 --cv_stratify \
+wavedl-train --model cnn --cv 5 --cv_stratify \
     --loss huber --optimizer adamw --scheduler cosine \
     --output_dir ./cv_results
 ```
@@ -773,10 +768,10 @@ Use YAML files for reproducible experiments. CLI arguments can override any conf
 
 ```bash
 # Use a config file
-accelerate launch -m wavedl.train --config configs/config.yaml --data_path train.npz
+wavedl-train --config configs/config.yaml --data_path train.npz
 
 # Override specific values from config
-accelerate launch -m wavedl.train --config configs/config.yaml --lr 5e-4 --epochs 500
+wavedl-train --config configs/config.yaml --lr 5e-4 --epochs 500
 ```
 
 **Example config (`configs/config.yaml`):**
@@ -929,7 +924,7 @@ wavedl-hpo --data_path train.npz --models cnn --n_trials 50 --quick
 
 After HPO completes, it prints the optimal command:
 ```bash
-accelerate launch -m wavedl.train --data_path train.npz --model cnn --lr 3.2e-4 --batch_size 128 ...
+wavedl-train --data_path train.npz --model cnn --lr 3.2e-4 --batch_size 128 ...
 ```
 
 ---
@@ -1122,12 +1117,12 @@ 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/elasticity_prediction/best_checkpoint \
+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/elasticity_prediction/best_checkpoint \
+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
 ```

{wavedl-1.6.1.dist-info → wavedl-1.6.3.dist-info}/RECORD

@@ -1,9 +1,9 @@
-wavedl/__init__.py,sha256=tz3qpBFZ4wTNv32Nz7aKGmHCXrTFTxAEJQeJO8La38Q,1177
-wavedl/hpc.py,sha256=6rV38nozzMt0-jKZbVJNwvQZXK0wUsIZmr9lgWN_XUw,9212
-wavedl/hpo.py,sha256=6eHYV9Nzbp2YbTY52NRnW7pwzlI_DNWskN-zBR-wj24,14654
-wavedl/test.py,sha256=1UUy9phCqrr3h_lN6mGJ7Sj73skDg4KyLk2Yuq9DiKU,38797
-wavedl/train.py,sha256=PzJGARHounr6R8WUOrUwwd2hRcLsGkxes08jYKkBRIo,58003
-wavedl/models/__init__.py,sha256=8OiT2seq1qBiUzKaSkmh_VOLJlLTT9Cn-mjhMHKGFpI,5203
+wavedl/__init__.py,sha256=CdjeIFEZh4ccwPiNsUxpac5l3pxwb9e1SmCNiLiYG1I,1177
+wavedl/hpo.py,sha256=nEiy-2O_5EhxF5hU8X5TviSAiXfVrTQx0-VE6baW7JQ,14633
+wavedl/launcher.py,sha256=_CFlgpKgHrtZebl1yQbJZJEcob06Y9-fqnRYzwW7UJQ,11776
+wavedl/test.py,sha256=5MzBtEH2lWWYG23Fz-VpMFAWR5SfZbFomBbu8ptsZRU,39208
+wavedl/train.py,sha256=DizXhi9BFL8heLmO8ENiNm2QubAMm9mdpDiaBlULeKM,57824
+wavedl/models/__init__.py,sha256=hyR__h_D8PsUQCBSM5tj94yYK00uG8ABjEmj_RR8SGE,5719
 wavedl/models/_pretrained_utils.py,sha256=VPdU1DwJB93ZBf_GFIgb8-6BbAt18Phs4yorwlhLw70,12404
 wavedl/models/_template.py,sha256=J_D8taSPmV8lBaucN_vU-WiG98iFr7CJrZVNNX_Tdts,4600
 wavedl/models/base.py,sha256=bDoHYFli-aR8amcFYXbF98QYaKSCEwZWpvOhN21ODro,9075
@@ -32,15 +32,15 @@ wavedl/utils/__init__.py,sha256=s5R9bRmJ8GNcJrD3OSAOXzwZJIXZbdYrAkZnus11sVQ,3300
 wavedl/utils/config.py,sha256=MXkaVc1_zo8sDro8mjtK1MV65t2z8b1Z6fviwSorNiY,10534
 wavedl/utils/constraints.py,sha256=V9Gyi8-uIMbLUWb2cOaHZD0SliWLxVrHZHFyo4HWK7g,18031
 wavedl/utils/cross_validation.py,sha256=HfInyZ8gUROc_AyihYKzzUE0vnoPt_mFvAI2OPK4P54,17945
-wavedl/utils/data.py,sha256=5ph2Pi8PKvuaSoJaXbFIL9WsX8pTN0A6P8FdmxvXdv4,63469
+wavedl/utils/data.py,sha256=HXod6i6g76oFAjLz7xepBPQEFHRgQ7E1M-YSKwUya-I,64799
 wavedl/utils/distributed.py,sha256=7wQ3mRjkp_xjPSxDWMnBf5dSkAGUaTzntxbz0BhC5v0,4145
 wavedl/utils/losses.py,sha256=KWpU5S5noFzp3bLbcH9RNpkFPajy6fyTIh5cNjI-BYA,7038
 wavedl/utils/metrics.py,sha256=YoqiXWOsUB9Y4_alj8CmHcTgnV4MFcH5PH4XlIC13HY,40304
 wavedl/utils/optimizers.py,sha256=ZoETDSOK1fWUT2dx69PyYebeM8Vcqf9zOIKUERWk5HY,6107
 wavedl/utils/schedulers.py,sha256=K6YCiyiMM9rb0cCRXTp89noXeXcAyUEiePr27O5Cozs,7408
-wavedl-1.6.1.dist-info/LICENSE,sha256=cEUCvcvH-9BT9Y-CNGY__PwWONCKu9zsoIqWA-NeHJ4,1066
-wavedl-1.6.1.dist-info/METADATA,sha256=eS4uG6dzEVs25zYmiZZnGeHz8lUHIVKL9TpyCJt7kh8,48232
-wavedl-1.6.1.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
-wavedl-1.6.1.dist-info/entry_points.txt,sha256=f1RNDkXFZwBzrBzTMFocJ6xhfTvTmaEDTi5YyDEUaF8,140
-wavedl-1.6.1.dist-info/top_level.txt,sha256=ccneUt3D5Qzbh3bsBSSrq9bqrhGiogcWKY24ZC4Q6Xw,7
-wavedl-1.6.1.dist-info/RECORD,,
+wavedl-1.6.3.dist-info/LICENSE,sha256=cEUCvcvH-9BT9Y-CNGY__PwWONCKu9zsoIqWA-NeHJ4,1066
+wavedl-1.6.3.dist-info/METADATA,sha256=BtPoAiMwvE58b-dmR0TfPPLLBqYzaAiJ2GBUd0FBSY0,47613
+wavedl-1.6.3.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
+wavedl-1.6.3.dist-info/entry_points.txt,sha256=NuAvdiG93EYYpqv-_1wf6PN0WqBfABanDKalNKe2GOs,148
+wavedl-1.6.3.dist-info/top_level.txt,sha256=ccneUt3D5Qzbh3bsBSSrq9bqrhGiogcWKY24ZC4Q6Xw,7
+wavedl-1.6.3.dist-info/RECORD,,

{wavedl-1.6.1.dist-info → wavedl-1.6.3.dist-info}/entry_points.txt

@@ -1,5 +1,5 @@
 [console_scripts]
-wavedl-hpc = wavedl.hpc:main
+wavedl-hpc = wavedl.launcher:main
 wavedl-hpo = wavedl.hpo:main
 wavedl-test = wavedl.test:main
-wavedl-train = wavedl.train:main
+wavedl-train = wavedl.launcher:main