Merge pull request #54 from mhpi/dev

Update to package nomenclature

Author: leoglonz

.github/workflows/lint.yaml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - master
-      - dmg_dev
+      - dev
   pull_request:
     branches:
       - master
@@ -19,15 +19,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v4.2.2
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v5.6.0
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Cache pip
-        uses: actions/cache@v4
+        uses: actions/cache@v4.2.3
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}

.github/workflows/pytest.yaml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - master
-      - dmg_dev
+      - dev
   pull_request:
     branches:
       - master 
@@ -18,15 +18,15 @@ jobs:
         python-version: ['3.12', '3.13']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v4.2.2
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v5.6.0
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: Cache uv
-      uses: actions/cache@v4
+      uses: actions/cache@v4.2.3
       with:
         path: ~/.cache/uv
         key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}

.gitignore

@@ -178,3 +178,6 @@ tmp/
 # Other Directories
 archive/
 validation/
+
+# Model optimization config with RayTune
+!tune/

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        exclude: "mkdocs.*\\.yml$"  # Exclude mkdocs YAML files
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.5  # Use whatever version you're currently using
+    hooks:
+      - id: ruff
+        args: [--fix]
+        exclude: "hooks/.*\\.py$"  # Exclude the hooks directory from ruff
+      - id: ruff-format

README.md

@@ -40,10 +40,10 @@ This work is mantained by [MHPI](http://water.engr.psu.edu/shen/) and advised by
 
 To install 𝛿MG, clone the repo and install in developer mode with [Astral UV](https://docs.astral.sh/uv/):
 
-```bash
-git clone [email protected]:mhpi/generic_deltamodel.git
-uv pip install -e ./generic_deltamodel
-```
+    ```bash
+    git clone [email protected]:mhpi/generic_deltamodel.git
+    uv pip install -e ./generic_deltamodel
+    ```
 
 Pip and Conda are also supported, though UV is recommended. See [setup](./docs/setup.md) for further details.
 
@@ -55,49 +55,49 @@ See [how to run](./docs/how_to_run.md).
 
 **Example -- Differentiable Parameter Learning**: Use an LSTM to learn parameters for the [HBV](https://en.wikipedia.org/wiki/HBV_hydrology_model) hydrological model.
 
-```python
-from hydroDL2.models.hbv.hbv import HBV
+    ```python
+    from hydrodl2.models.hbv.hbv import Hbv
 
-from dMG.core.data.loaders import HydroLoader
-from dMG.core.utils import load_nn_model, print_config, set_randomseed
-from dMG.models.delta_models import DplModel
-from example import load_config, take_data_sample
+    from dmg.core.data.loaders import HydroLoader
+    from dmg.core.utils import load_nn_model, print_config, set_randomseed
+    from dmg.models.delta_models import DplModel
+    from example import load_config, take_data_sample
 
-CONFIG_PATH = '../example/conf/config_dhbv_1_0.yaml'
+    CONFIG_PATH = '../example/conf/config_dhbv_1_0.yaml'
 
 
-# Model configuration
-config = load_config(CONFIG_PATH)
+    # Model configuration
+    config = load_config(CONFIG_PATH)
 
-# Initialize physical model and NN.
-phy_model = HBV(config['delta_model']['phy_model'])
-nn = load_nn_model(phy_model, config['delta_model'])
+    # Initialize physical model and NN.
+    phy_model = Hbv(config['delta_model']['phy_model'])
+    nn = load_nn_model(phy_model, config['delta_model'])
 
-# Create differentiable model dHBV: a torch.nn.Module that describes how 
-# the NN is linked to the physical model HBV.
-dpl_model = DplModel(phy_model=phy_model, nn_model=nn)
+    # Create differentiable model dHBV: a torch.nn.Module that describes how 
+    # the NN is linked to the physical model HBV.
+    dpl_model = DplModel(phy_model=phy_model, nn_model=nn)
 
-# Load dataset of NN and HBV inputs.
-dataset = HydroLoader(config).dataset
-dataset_sample = take_data_sample(config, dataset, days=730, basins=100)
+    # Load dataset of NN and HBV inputs.
+    dataset = HydroLoader(config).dataset
+    dataset_sample = take_data_sample(config, dataset, days=730, basins=100)
 
-output = dpl_model(dataset_sample)
-```
+    output = dpl_model(dataset_sample)
+    ```
 
 This exposes a key characteristic of the differentiable model `DplModel`: composition of a physical model, `phy_model`, and a neural network, `nn`. Internally, `DplModel` looks like
 
-```python
-# NN forward
-parameters = self.nn_model(dataset_sample['xc_nn_norm'])        
+    ```python
+    # NN forward
+    parameters = self.nn_model(dataset_sample['xc_nn_norm'])        
 
-# Physics model forward
-predictions = self.phy_model(
-    dataset_sample,
-    parameters,
-)
-```
+    # Physics model forward
+    predictions = self.phy_model(
+        dataset_sample,
+        parameters,
+    )
+    ```
 
-Check out [examples](https://github.com/mhpi/generic_deltamodel/tree/master/example/hydrology) to see model training/testing/simulation in detail. We recommend starting [here](./example/hydrology/example_dhbv_1_0.ipynb), which is a continuation of the above. A [Colab Notebook](https://colab.research.google.com/drive/19PRLrI-L7cGeYzkk2tOetULzQK8s_W7v?usp=sharing) for this δHBV example is also available.
+Check out [examples](https://github.com/mhpi/generic_deltamodel/tree/master/example/hydrology) to see model training/testing/simulation in detail. We recommend starting with the [δHBV 1.0 tutorial](./example/hydrology/example_dhbv_1_0.ipynb), which can also be run in a [Colab Notebook](https://colab.research.google.com/drive/19PRLrI-L7cGeYzkk2tOetULzQK8s_W7v?usp=sharing) to leverage online compute.
 
 </br>
 
@@ -129,7 +129,7 @@ Currently in development. Find more details and results in [Aboelyazeed et al. (
 
 ## Ecosystem Integration
 
-- **HydroDL 2.0 ([`hydroDL2`](https://github.com/mhpi/hydroDL2))**: Home to MHPI's suite of process-based hydrology models and differentiable model augmentations.
+- **HydroDL 2.0 ([`hydrodl2`](https://github.com/mhpi/hydrodl2))**: Home to MHPI's suite of process-based hydrology models and differentiable model augmentations.
 <!-- - **HydroData ([`hydro_data_dev`](https://github.com/mhpi/hydro_data_dev))**: Data extraction, processing, and management tools optimized for geospatial datasets. (In development) -->
 <!-- - **Config GUI ([`GUI-Config-builder`](https://mhpi-spatial.s3.us-east-2.amazonaws.com/mhpi-release/config_builder_gui/Config+Builder+GUI.zip))([Source](https://github.com/mhpi/GUI-Config-builder))**: An intuitive, user-friendly tool designed to simplify the creation and editing of configuration files for model setup and development. -->
 - **Differentiable Ecosystem Modeling ([`diffEcosys (dev version only)`](https://github.com/hydroPKDN/diffEcosys/))**: A physics-informed machine learning system for ecosystem modeling, demonstrated using the photosynthesis process representation within the Functionally Assembled Terrestrial Ecosystem Simulator (FATES) model. This model is coupled to NNs that learn parameters from observations of photosynthesis rates.
@@ -151,8 +151,8 @@ Currently in development. Find more details and results in [Aboelyazeed et al. (
 
     ```text
     .
-    ├── src/dMG/
-    │   ├── __main__.py                 # Runs 𝛿MG; models, experiments
+    ├── src/dmg/
+    │   ├── __main__.py                 # Runs dMG; models, experiments
     │   ├── core/                       
     │   │   ├── calc/                   # Calculation utilities
     │   │   ├── data/                   # Data loaders and samplers

conf/config.py

@@ -148,6 +148,7 @@ def validate_dataset_times(cls, values):
 class Config(BaseModel):
     """Configuration class for the model."""
     mode: ModeEnum = Field(default=ModeEnum.train_test)
+    do_tune: bool = False
     multimodel_type: str = 'none'
     random_seed: int = 0
     device: str = 'cpu'
@@ -242,7 +243,7 @@ def check_device(cls, values):
                     'learning_rate': 1.0,
                     'forcings': ['x1_var', 'x2_var'],
                     'attributes': ['attr1', 'attr2'],
-                }
+                },
             },
             observations={
                 'name': 'example',

conf/hydra/settings.yaml

@@ -13,7 +13,7 @@ help:
 job:
     chdir: False  # Changes working dir to run.dir below.
 run:
-    dir: ../output/logs/${now:%Y-%m-%d_%H-%M-%S}
+    dir: ./output/logs/${now:%Y-%m-%d_%H-%M-%S}
 sweep:
     dir: multirun
     subdir: ${hydra.job.override_dirname}

conf/tune/raytune.yaml

@@ -0,0 +1,23 @@
+# Basic config for model tuning.
+# Tuning options and search space rules belong here. Keys should match those in
+# master config.
+name: raytune
+
+metric: mean_accuracy  # val_loss, mean_accuracy
+mode: min
+num_samples: 20
+scheduler: ASHAScheduler
+search_alg: OptunaSearch
+search_alg_params:
+  n_trials: 10
+  time_budget: 60
+  metric: mean_accuracy
+  mode: min
+
+save_epoch: 1
+
+rules:
+  delta_model:
+    nn_model:
+      hidden_size: [128, 256, 512]
+      learning_rate: [1.0, 0.5]

docs/configuration_files.md

@@ -57,7 +57,7 @@ If you wish to use additional configuration files to store distinguished setting
 
 Configuration file managment is handled by the Hydra config manager (see above). Essentially, at the start of a model experiment, Hydra will load configs into a single Python dictionary object of all settings that can be accessed throughout the framework.
 
-You can see this demonstrated in the main dMG run file, `./generic_deltamodel/src/dMG/__main__.py`, at the start of the main function we call the decorator
+You can see this demonstrated in the main dMG run file, `./generic_deltamodel/src/dmg/__main__.py`, at the start of the main function we call the decorator
 
 ```python
 @hydra.main(

docs/configuration_glossary.md

@@ -50,11 +50,11 @@ The settings are broken down as they appear in the YAML configuration files, wit
 
 **gpu_id**: [0] If `device = cuda`, the index of the GPU in your system to run models on. Index 0 will always be available.
 
-**data_loader**: Class name of the data loader to use. E.g., *HydroLoader* located in `./generic_deltamodel/src/dMG/core/data/loaders/hydro_loader.py`. Note class name must be Camel-case w/o spaces corresponding to the file name.
+**data_loader**: Class name of the data loader to use. E.g., *HydroLoader* located in `./generic_deltamodel/src/dmg/core/data/loaders/hydro_loader.py`. Note class name must be Camel-case w/o spaces corresponding to the file name.
 
-**data_sampler**: Class name of the data sampler used in training/inference. E.g., *HydroSampler* located in `./generic_deltamodel/src/dMG/core/data/samplers/hydro_sampler.py`. Follows same convention as data_loader.
+**data_sampler**: Class name of the data sampler used in training/inference. E.g., *HydroSampler* located in `./generic_deltamodel/src/dmg/core/data/samplers/hydro_sampler.py`. Follows same convention as data_loader.
 
-**trainer**: Class name of the trainer used in training/inference. E.g., *Trainer* located in `./generic_deltamodel/src/dMG/trainers/trainer.py`. Follows same convention as data_loader.
+**trainer**: Class name of the trainer used in training/inference. E.g., *Trainer* located in `./generic_deltamodel/src/dmg/trainers/trainer.py`. Follows same convention as data_loader.
 
 **save_path**: [./output] root path to which model weights, outputs, statistics, and metrics will be saved.
 
@@ -116,7 +116,7 @@ The settings are broken down as they appear in the YAML configuration files, wit
 
 **loss_function**:
 
-- **model**: [KgeBatchLoss, KgeNormBatchLoss, MseLoss, NseBatchLoss, NseSqrtBatchLoss, RmseCombLoss, RmseLoss] Loss function for training. See `./generic_deltamodel/src/dMG/models/criterion/` for all available loss functions. You can add custom criterion, but they must follow Class-File convention as illustrated for `data_loader`, etc.
+- **model**: [KgeBatchLoss, KgeNormBatchLoss, MseLoss, NseBatchLoss, NseSqrtBatchLoss, RmseCombLoss, RmseLoss] Loss function for training. See `./generic_deltamodel/src/dmg/models/criterion/` for all available loss functions. You can add custom criterion, but they must follow Class-File convention as illustrated for `data_loader`, etc.
 
 </br>
 
@@ -132,7 +132,7 @@ The settings are broken down as they appear in the YAML configuration files, wit
     - `HBV_adj`: δHBV with adjoint method.
     - `HBV_1_1p`: δHBV 1.1p
     - `HBV_2_0`: δHBV 2.0
-    - `custom_model`: If you create and add a physical to [phy_model/](../src/dMG/models/phy_models/), this will be the class name. Note it must follow the Class-File convention as illustrated for `data_loader`, etc.
+    - `custom_model`: If you create and add a physical to [phy_model/](../src/dmg/models/phy_models/), this will be the class name. Note it must follow the Class-File convention as illustrated for `data_loader`, etc.
 
   - *nmul*: Number of parallel parameter sets to use. These will be averaged for single physical model output.
 
@@ -214,7 +214,7 @@ The settings are broken down as they appear in the YAML configuration files, wit
 
 - *scaling_function*: [sigmoid, softmax] Method to use for scaling learned weights.
 
-- *loss_function*: [KgeBatchLoss, KgeNormBatchLoss, MseLoss, NseBatchLoss, NseSqrtBatchLoss, RmseCombLoss, RmseLoss] Loss function for training. See `./generic_deltamodel/src/dMG/models/criterion/` for all available loss functions. You can add custom criterion, but they must follow Class-File convention as illustrated for `data_loader`, etc.
+- *loss_function*: [KgeBatchLoss, KgeNormBatchLoss, MseLoss, NseBatchLoss, NseSqrtBatchLoss, RmseCombLoss, RmseLoss] Loss function for training. See `./generic_deltamodel/src/dmg/models/criterion/` for all available loss functions. You can add custom criterion, but they must follow Class-File convention as illustrated for `data_loader`, etc.
 
 - *use_rb_loss*: [bool] If True, include range-bound loss regularization. Penalize learned weights when their sum exceeds specific bounds.