wavedl 1.4.6__tar.gz → 1.5.1__tar.gz

{wavedl-1.4.6/src/wavedl.egg-info → wavedl-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: wavedl
-Version: 1.4.6
+Version: 1.5.1
 Summary: A Scalable Deep Learning Framework for Wave-Based Inverse Problems
 Author: Ductho Le
 License: MIT
@@ -99,6 +99,7 @@ The framework handles the engineering challenges of large-scale deep learning
 
 ## ✨ Features
 
+<div align="center">
 <table width="100%">
 <tr>
 <td width="50%" valign="top">
@@ -113,14 +114,12 @@ Train on datasets larger than RAM:
 </td>
 <td width="50%" valign="top">
 
-**🧠 One-Line Model Registration**
+**🧠 Models? We've Got Options**
 
-Plug in any architecture:
-```python
-@register_model("my_net")
-class MyNet(BaseModel): ...
-```
-Design your model. Register with one line.
+38 architectures, ready to go:
+- CNNs, ResNets, ViTs, EfficientNets...
+- All adapted for regression
+- [Add your own](#adding-custom-models) in one line
 
 </td>
 </tr>
@@ -137,12 +136,12 @@ Multi-GPU training without the pain:
 </td>
 <td width="50%" valign="top">
 
-**📊 Publish-Ready Output**
+**🔬 Physics-Constrained Training**
 
-Results go straight to your paper:
-- 11 diagnostic plots with LaTeX styling
-- Multi-format export (PNG, PDF, SVG, ...)
-- MAE in physical units per parameter
+Make your model respect the laws:
+- Enforce bounds, positivity, equations
+- Simple expression syntax or Python
+- [Custom constraints](#physical-constraints) for various laws
 
 </td>
 </tr>
@@ -191,6 +190,7 @@ Deploy models anywhere:
 </td>
 </tr>
 </table>
+</div>
 
 ---
 
@@ -279,6 +279,10 @@ python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
 # Export model to ONNX for deployment (LabVIEW, MATLAB, C++, etc.)
 python -m 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> \
+  --input_channels 1
 ```
 
 **Output:**
@@ -374,6 +378,7 @@ WaveDL/
 │       └── utils/                # Utilities
 │           ├── data.py           # Memory-mapped data pipeline
 │           ├── metrics.py        # R², Pearson, visualization
+│           ├── constraints.py    # Physical constraints for training
 │           ├── distributed.py    # DDP synchronization
 │           ├── losses.py         # Loss function factory
 │           ├── optimizers.py     # Optimizer factory
@@ -383,7 +388,7 @@ WaveDL/
 ├── configs/                      # YAML config templates
 ├── examples/                     # Ready-to-run examples
 ├── notebooks/                    # Jupyter notebooks
-├── unit_tests/                   # Pytest test suite (704 tests)
+├── unit_tests/                   # Pytest test suite (725 tests)
 │
 ├── pyproject.toml                # Package config, dependencies
 ├── CHANGELOG.md                  # Version history
@@ -727,6 +732,104 @@ seed: 2025
 
 </details>
 
+<details>
+<summary><b>Physical Constraints</b> — Enforce Physics During Training</summary>
+
+Add penalty terms to the loss function to enforce physical laws:
+
+```
+Total Loss = Data Loss + weight × penalty(violation)
+```
+
+### Expression Constraints
+
+```bash
+# Positivity
+--constraint "y0 > 0"
+
+# Bounds
+--constraint "y0 >= 0" "y0 <= 1"
+
+# Equations (penalize deviations from zero)
+--constraint "y2 - y0 * y1"
+
+# Input-dependent constraints
+--constraint "y0 - 2*x[0]"
+
+# Multiple constraints with different weights
+--constraint "y0 > 0" "y1 - y2" --constraint_weight 0.1 1.0
+```
+
+### Custom Python Constraints
+
+For complex physics (matrix operations, implicit equations):
+
+```python
+# my_constraint.py
+import torch
+
+def constraint(pred, inputs=None):
+    """
+    Args:
+        pred:   (batch, num_outputs)
+        inputs: (batch, features) or (batch, C, H, W) or (batch, C, D, H, W)
+    Returns:
+        (batch,) — violation per sample (0 = satisfied)
+    """
+    # Outputs (same for all data types)
+    y0, y1, y2 = pred[:, 0], pred[:, 1], pred[:, 2]
+
+    # Inputs — Tabular: (batch, features)
+    # x0 = inputs[:, 0]                    # Feature 0
+    # x_sum = inputs.sum(dim=1)            # Sum all features
+
+    # Inputs — Images: (batch, C, H, W)
+    # pixel = inputs[:, 0, 3, 5]           # Pixel at (3,5), channel 0
+    # img_mean = inputs.mean(dim=(1,2,3))  # Mean over C,H,W
+
+    # Inputs — 3D Volumes: (batch, C, D, H, W)
+    # voxel = inputs[:, 0, 2, 3, 5]        # Voxel at (2,3,5), channel 0
+
+    # Example constraints:
+    # return y2 - y0 * y1                                    # Wave equation
+    # return y0 - 2 * inputs[:, 0]                           # Output = 2×input
+    # return inputs[:, 0, 3, 5] * y0 + inputs[:, 0, 6, 7] * y1  # Mixed
+
+    return y0 - y1 * y2
+```
+
+```bash
+--constraint_file my_constraint.py --constraint_weight 1.0
+```
+
+---
+
+### Reference
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--constraint` | — | Expression(s): `"y0 > 0"`, `"y0 - y1*y2"` |
+| `--constraint_file` | — | Python file with `constraint(pred, inputs)` |
+| `--constraint_weight` | `0.1` | Penalty weight(s) |
+| `--constraint_reduction` | `mse` | `mse` (squared) or `mae` (linear) |
+
+#### Expression Syntax
+
+| Variable | Meaning |
+|----------|---------|
+| `y0`, `y1`, ... | Model outputs |
+| `x[0]`, `x[1]`, ... | Input values (1D tabular) |
+| `x[i,j]`, `x[i,j,k]` | Input values (2D/3D: images, volumes) |
+| `x_mean`, `x_sum`, `x_max`, `x_min`, `x_std` | Input aggregates |
+
+**Operators:** `+`, `-`, `*`, `/`, `**`, `>`, `<`, `>=`, `<=`, `==`
+
+**Functions:** `sin`, `cos`, `exp`, `log`, `sqrt`, `sigmoid`, `softplus`, `tanh`, `relu`, `abs`
+
+</details>
+
+
+
 <details>
 <summary><b>Hyperparameter Search (HPO)</b></summary>
 
@@ -766,7 +869,7 @@ accelerate launch -m wavedl.train --data_path train.npz --model cnn --lr 3.2e-4
 | Schedulers | [all 8](#learning-rate-schedulers) | `--schedulers X Y` |
 | Losses | [all 6](#loss-functions) | `--losses X Y` |
 | Learning rate | 1e-5 → 1e-2 | (always searched) |
-| Batch size | 64, 128, 256, 512 | (always searched) |
+| Batch size | 16, 32, 64, 128 | (always searched) |
 
 **Quick Mode** (`--quick`):
 - Uses minimal defaults: cnn + adamw + plateau + mse
@@ -938,12 +1041,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/elastic_cnn_example/best_checkpoint \
-  --data_path ./examples/elastic_cnn_example/Test_data_100.mat \
+  --data_path ./examples/elastic_cnn_example/Test_data_500.mat \
   --plot --save_predictions --output_dir ./examples/elastic_cnn_example/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_100.mat \
+  --data_path ./examples/elastic_cnn_example/Test_data_500.mat \
   --export onnx --export_path ./examples/elastic_cnn_example/model.onnx
 ```
 
@@ -952,7 +1055,7 @@ python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoin
 | File | Description |
 |------|-------------|
 | `best_checkpoint/` | Pre-trained CNN checkpoint |
-| `Test_data_100.mat` | 100 sample test set (500×500 dispersion curves → *h*, √(*E*/ρ), *ν*) |
+| `Test_data_500.mat` | 500 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 |
@@ -963,7 +1066,7 @@ python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoin
 
 <p align="center">
   <img src="examples/elastic_cnn_example/training_curves.png" alt="Training curves" width="600"><br>
-  <em>Training and validation loss over 162 epochs with learning rate schedule</em>
+  <em>Training and validation loss over 227 epochs with <code>onecycle</code> learning rate schedule</em>
 </p>
 
 **Inference Results:**

{wavedl-1.4.6 → wavedl-1.5.1}/README.md

@@ -54,6 +54,7 @@ The framework handles the engineering challenges of large-scale deep learning
 
 ## ✨ Features
 
+<div align="center">
 <table width="100%">
 <tr>
 <td width="50%" valign="top">
@@ -68,14 +69,12 @@ Train on datasets larger than RAM:
 </td>
 <td width="50%" valign="top">
 
-**🧠 One-Line Model Registration**
+**🧠 Models? We've Got Options**
 
-Plug in any architecture:
-```python
-@register_model("my_net")
-class MyNet(BaseModel): ...
-```
-Design your model. Register with one line.
+38 architectures, ready to go:
+- CNNs, ResNets, ViTs, EfficientNets...
+- All adapted for regression
+- [Add your own](#adding-custom-models) in one line
 
 </td>
 </tr>
@@ -92,12 +91,12 @@ Multi-GPU training without the pain:
 </td>
 <td width="50%" valign="top">
 
-**📊 Publish-Ready Output**
+**🔬 Physics-Constrained Training**
 
-Results go straight to your paper:
-- 11 diagnostic plots with LaTeX styling
-- Multi-format export (PNG, PDF, SVG, ...)
-- MAE in physical units per parameter
+Make your model respect the laws:
+- Enforce bounds, positivity, equations
+- Simple expression syntax or Python
+- [Custom constraints](#physical-constraints) for various laws
 
 </td>
 </tr>
@@ -146,6 +145,7 @@ Deploy models anywhere:
 </td>
 </tr>
 </table>
+</div>
 
 ---
 
@@ -234,6 +234,10 @@ python -m wavedl.test --checkpoint <checkpoint_folder> --data_path <test_data> \
 # Export model to ONNX for deployment (LabVIEW, MATLAB, C++, etc.)
 python -m 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> \
+  --input_channels 1
 ```
 
 **Output:**
@@ -329,6 +333,7 @@ WaveDL/
 │       └── utils/                # Utilities
 │           ├── data.py           # Memory-mapped data pipeline
 │           ├── metrics.py        # R², Pearson, visualization
+│           ├── constraints.py    # Physical constraints for training
 │           ├── distributed.py    # DDP synchronization
 │           ├── losses.py         # Loss function factory
 │           ├── optimizers.py     # Optimizer factory
@@ -338,7 +343,7 @@ WaveDL/
 ├── configs/                      # YAML config templates
 ├── examples/                     # Ready-to-run examples
 ├── notebooks/                    # Jupyter notebooks
-├── unit_tests/                   # Pytest test suite (704 tests)
+├── unit_tests/                   # Pytest test suite (725 tests)
 │
 ├── pyproject.toml                # Package config, dependencies
 ├── CHANGELOG.md                  # Version history
@@ -682,6 +687,104 @@ seed: 2025
 
 </details>
 
+<details>
+<summary><b>Physical Constraints</b> — Enforce Physics During Training</summary>
+
+Add penalty terms to the loss function to enforce physical laws:
+
+```
+Total Loss = Data Loss + weight × penalty(violation)
+```
+
+### Expression Constraints
+
+```bash
+# Positivity
+--constraint "y0 > 0"
+
+# Bounds
+--constraint "y0 >= 0" "y0 <= 1"
+
+# Equations (penalize deviations from zero)
+--constraint "y2 - y0 * y1"
+
+# Input-dependent constraints
+--constraint "y0 - 2*x[0]"
+
+# Multiple constraints with different weights
+--constraint "y0 > 0" "y1 - y2" --constraint_weight 0.1 1.0
+```
+
+### Custom Python Constraints
+
+For complex physics (matrix operations, implicit equations):
+
+```python
+# my_constraint.py
+import torch
+
+def constraint(pred, inputs=None):
+    """
+    Args:
+        pred:   (batch, num_outputs)
+        inputs: (batch, features) or (batch, C, H, W) or (batch, C, D, H, W)
+    Returns:
+        (batch,) — violation per sample (0 = satisfied)
+    """
+    # Outputs (same for all data types)
+    y0, y1, y2 = pred[:, 0], pred[:, 1], pred[:, 2]
+
+    # Inputs — Tabular: (batch, features)
+    # x0 = inputs[:, 0]                    # Feature 0
+    # x_sum = inputs.sum(dim=1)            # Sum all features
+
+    # Inputs — Images: (batch, C, H, W)
+    # pixel = inputs[:, 0, 3, 5]           # Pixel at (3,5), channel 0
+    # img_mean = inputs.mean(dim=(1,2,3))  # Mean over C,H,W
+
+    # Inputs — 3D Volumes: (batch, C, D, H, W)
+    # voxel = inputs[:, 0, 2, 3, 5]        # Voxel at (2,3,5), channel 0
+
+    # Example constraints:
+    # return y2 - y0 * y1                                    # Wave equation
+    # return y0 - 2 * inputs[:, 0]                           # Output = 2×input
+    # return inputs[:, 0, 3, 5] * y0 + inputs[:, 0, 6, 7] * y1  # Mixed
+
+    return y0 - y1 * y2
+```
+
+```bash
+--constraint_file my_constraint.py --constraint_weight 1.0
+```
+
+---
+
+### Reference
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--constraint` | — | Expression(s): `"y0 > 0"`, `"y0 - y1*y2"` |
+| `--constraint_file` | — | Python file with `constraint(pred, inputs)` |
+| `--constraint_weight` | `0.1` | Penalty weight(s) |
+| `--constraint_reduction` | `mse` | `mse` (squared) or `mae` (linear) |
+
+#### Expression Syntax
+
+| Variable | Meaning |
+|----------|---------|
+| `y0`, `y1`, ... | Model outputs |
+| `x[0]`, `x[1]`, ... | Input values (1D tabular) |
+| `x[i,j]`, `x[i,j,k]` | Input values (2D/3D: images, volumes) |
+| `x_mean`, `x_sum`, `x_max`, `x_min`, `x_std` | Input aggregates |
+
+**Operators:** `+`, `-`, `*`, `/`, `**`, `>`, `<`, `>=`, `<=`, `==`
+
+**Functions:** `sin`, `cos`, `exp`, `log`, `sqrt`, `sigmoid`, `softplus`, `tanh`, `relu`, `abs`
+
+</details>
+
+
+
 <details>
 <summary><b>Hyperparameter Search (HPO)</b></summary>
 
@@ -721,7 +824,7 @@ accelerate launch -m wavedl.train --data_path train.npz --model cnn --lr 3.2e-4
 | Schedulers | [all 8](#learning-rate-schedulers) | `--schedulers X Y` |
 | Losses | [all 6](#loss-functions) | `--losses X Y` |
 | Learning rate | 1e-5 → 1e-2 | (always searched) |
-| Batch size | 64, 128, 256, 512 | (always searched) |
+| Batch size | 16, 32, 64, 128 | (always searched) |
 
 **Quick Mode** (`--quick`):
 - Uses minimal defaults: cnn + adamw + plateau + mse
@@ -893,12 +996,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/elastic_cnn_example/best_checkpoint \
-  --data_path ./examples/elastic_cnn_example/Test_data_100.mat \
+  --data_path ./examples/elastic_cnn_example/Test_data_500.mat \
   --plot --save_predictions --output_dir ./examples/elastic_cnn_example/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_100.mat \
+  --data_path ./examples/elastic_cnn_example/Test_data_500.mat \
   --export onnx --export_path ./examples/elastic_cnn_example/model.onnx
 ```
 
@@ -907,7 +1010,7 @@ python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoin
 | File | Description |
 |------|-------------|
 | `best_checkpoint/` | Pre-trained CNN checkpoint |
-| `Test_data_100.mat` | 100 sample test set (500×500 dispersion curves → *h*, √(*E*/ρ), *ν*) |
+| `Test_data_500.mat` | 500 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 |
@@ -918,7 +1021,7 @@ python -m wavedl.test --checkpoint ./examples/elastic_cnn_example/best_checkpoin
 
 <p align="center">
   <img src="examples/elastic_cnn_example/training_curves.png" alt="Training curves" width="600"><br>
-  <em>Training and validation loss over 162 epochs with learning rate schedule</em>
+  <em>Training and validation loss over 227 epochs with <code>onecycle</code> learning rate schedule</em>
 </p>
 
 **Inference Results:**

{wavedl-1.4.6 → wavedl-1.5.1}/src/wavedl/__init__.py

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

{wavedl-1.4.6 → wavedl-1.5.1}/src/wavedl/hpo.py

@@ -89,7 +89,8 @@ def create_objective(args):
         # Suggest hyperparameters
         model = trial.suggest_categorical("model", models)
         lr = trial.suggest_float("lr", 1e-5, 1e-2, log=True)
-        batch_size = trial.suggest_categorical("batch_size", [64, 128, 256, 512])
+        batch_sizes = args.batch_sizes or [16, 32, 64, 128]
+        batch_size = trial.suggest_categorical("batch_size", batch_sizes)
         optimizer = trial.suggest_categorical("optimizer", optimizers)
         scheduler = trial.suggest_categorical("scheduler", schedulers)
         loss = trial.suggest_categorical("loss", losses)
@@ -317,6 +318,13 @@ Examples:
         default=None,
         help=f"Losses to search (default: {DEFAULT_LOSSES})",
     )
+    parser.add_argument(
+        "--batch_sizes",
+        type=int,
+        nargs="+",
+        default=None,
+        help="Batch sizes to search (default: 16 32 64 128)",
+    )
 
     # Training settings for each trial
     parser.add_argument(

{wavedl-1.4.6 → wavedl-1.5.1}/src/wavedl/models/vit.py

@@ -54,6 +54,16 @@ class PatchEmbed(nn.Module):
         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
             self.proj = nn.Conv1d(
                 1, embed_dim, kernel_size=patch_size, stride=patch_size
@@ -61,6 +71,17 @@ class PatchEmbed(nn.Module):
         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)
             self.proj = nn.Conv2d(
                 1, embed_dim, kernel_size=patch_size, stride=patch_size

{wavedl-1.4.6 → wavedl-1.5.1}/src/wavedl/test.py

@@ -166,6 +166,13 @@ def parse_args() -> argparse.Namespace:
         default=None,
         help="Parameter names for output (e.g., 'h' 'v11' 'v12')",
     )
+    parser.add_argument(
+        "--input_channels",
+        type=int,
+        default=None,
+        help="Explicit number of input channels. Bypasses auto-detection heuristics "
+        "for ambiguous 4D shapes (e.g., 3D volumes with small depth).",
+    )
 
     # Inference options
     parser.add_argument(
@@ -235,6 +242,7 @@ def load_data_for_inference(
     format: str = "auto",
     input_key: str | None = None,
     output_key: str | None = None,
+    input_channels: int | None = None,
 ) -> tuple[torch.Tensor, torch.Tensor | None]:
     """
     Load test data for inference using the unified data loading pipeline.
@@ -278,7 +286,11 @@ def load_data_for_inference(
 
     # Use the unified loader from utils.data
     X, y = load_test_data(
-        file_path, format=format, input_key=input_key, output_key=output_key
+        file_path,
+        format=format,
+        input_key=input_key,
+        output_key=output_key,
+        input_channels=input_channels,
     )
 
     # Log results
@@ -452,7 +464,12 @@ def run_inference(
         predictions: Numpy array (N, out_size) - still in normalized space
     """
     if device is None:
-        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        if torch.cuda.is_available():
+            device = torch.device("cuda")
+        elif torch.backends.mps.is_available():
+            device = torch.device("mps")
+        else:
+            device = torch.device("cpu")
 
     model = model.to(device)
     model.eval()
@@ -463,7 +480,7 @@ def run_inference(
         batch_size=batch_size,
         shuffle=False,
         num_workers=num_workers,
-        pin_memory=device.type == "cuda",
+        pin_memory=device.type in ("cuda", "mps"),
     )
 
     predictions = []
@@ -919,8 +936,13 @@ def main():
     )
     logger = logging.getLogger("Tester")
 
-    # Device
-    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    # Device (CUDA > MPS > CPU)
+    if torch.cuda.is_available():
+        device = torch.device("cuda")
+    elif torch.backends.mps.is_available():
+        device = torch.device("mps")
+    else:
+        device = torch.device("cpu")
     logger.info(f"Using device: {device}")
 
     # Load test data
@@ -929,6 +951,7 @@ def main():
         format=args.format,
         input_key=args.input_key,
         output_key=args.output_key,
+        input_channels=args.input_channels,
     )
     in_shape = tuple(X_test.shape[2:])