HMC-PINN HydroShare Resource Package

This folder contains the curated code and data package for the HMC-PINN / HMC-XPINN research workflow, prepared for public release on HydroShare.

1. Project overview

This repository provides a reproducible research package for coupled hydro-mechanical-chemical modeling and parameter inversion with physics-informed neural networks (PINNs).

The project includes three main components:

• Forward modeling with HMC-PINN
• Homogeneous cases
• Continuously heterogeneous cases
• Forward modeling with HMC-XPINN
• Layered cases
• Inverse modeling with HMC-PINN
• Inversion of k_h or D_0 for the homogeneous case

The package is organized to support:

• model reproduction
• data sharing
• future extension
• HydroShare publication

2. Package structure

text hydroshare_HMC-PINN/ ├─ README.md ├─ metadata/ │ ├─ file_manifest.csv │ └─ data_dictionary.csv ├─ code/ │ ├─ forward_model/ │ │ ├─ HMC-PINN/ │ │ │ ├─ homogeneous/ │ │ │ │ └─ pinn_forward_homogeneous.py │ │ │ ├─ continuous_heterogeneous/ │ │ │ │ └─ pinn_forward_continuous_heterogeneous.py │ │ │ └─ common/ │ │ └─ HMC-XPINN/ │ │ ├─ layered/ │ │ │ └─ xpinn_layered.py │ │ └─ common/ │ ├─ inverse_model/ │ │ └─ hmc_pinn_inverse_kh_D0.py │ └─ requirements.txt └─ data/ ├─ inverse/ │ └─ Chapter6_Origin_v5.xlsx └─ forward/ ├─ extracted/ └─ summary_tables/

3. What is included

3.1 Code

Forward modeling

• code/forward_model/HMC-PINN/homogeneous/pinn_forward_homogeneous.py
• HMC-PINN forward model for homogeneous media
• code/forward_model/HMC-PINN/continuous_heterogeneous/pinn_forward_continuous_heterogeneous.py
• HMC-PINN forward model for continuously varying heterogeneous media
• code/forward_model/HMC-XPINN/layered/xpinn_layered.py
• HMC-XPINN forward model for layered media

Inverse modeling

• code/inverse_model/hmc_pinn_inverse_kh_D0.py
• Inverse model used to estimate k_h or D_0 in the homogeneous case

3.2 Data

Inverse data

• data/inverse/Chapter6_Origin_v5.xlsx
• Core inverse-analysis data file

Forward data

• data/forward/
• Processed forward-model data extracted from the original experiment results
• This folder is intended to contain curated, publication-ready data products rather than the full raw training outputs

3.3 Metadata

• metadata/file_manifest.csv
• File inventory and description
• metadata/data_dictionary.csv
• Variable and column definitions for the shared data

4. Forward-model data policy

The original project contains many experiment outputs and intermediate files. For HydroShare release, the forward-model data should be curated into compact, reusable tables.

Recommended content for data/forward/:

• representative prediction profiles
• summary metrics
• validation tables
• key comparison tables for the paper
• extracted forward-model results only

Large raw training directories, temporary logs, and environment folders should not be uploaded unless they are necessary for reproduction.

5. Software requirements

The codebase is written in Python and uses the following major packages:

• deepxde
• torch
• numpy
• pandas
• matplotlib
• scipy

A complete dependency list should be placed in code/requirements.txt.

6. Running the models

6.1 Inverse model

Example:

bash python code/inverse_model/hmc_pinn_inverse_kh_D0.py --target kh

Common options:

• --target kh : invert hydraulic conductivity
• --target d0 : invert molecular diffusion coefficient
• --target joint : invert both parameters jointly
• --noise 0.05 : use 5% observation noise
• --data-file <path> : specify the observation data file

The script automatically creates an outputs/ directory under the inverse-model folder.

6.2 Forward models

Run the forward scripts directly from the relevant subfolders.

Examples:

bash python code/forward_model/HMC-PINN/homogeneous/pinn_forward_homogeneous.py python code/forward_model/HMC-PINN/continuous_heterogeneous/pinn_forward_continuous_heterogeneous.py python code/forward_model/HMC-XPINN/layered/xpinn_layered.py

If the scripts depend on shared configuration modules, keep them in the corresponding common/ folders.

7. Notes on the current release

• The repository has been cleaned for public sharing.
• The inverse dataset is stored as a single Excel file: Chapter6_Origin_v5.xlsx.
• Forward data are still being curated into compact shared tables.
• Some original local experiment outputs may exist outside this release package and are not intended for upload.

8. Reproducibility tips

To reproduce the results reliably:

1. Install the dependencies listed in code/requirements.txt.
2. Keep the folder structure unchanged.
3. Place the inverse input file in data/inverse/.
4. Use the curated forward data in data/forward/.
5. Run the forward or inverse scripts from their own directories if relative paths are used.

9. Suggested citation

Please add the final citation format in metadata/ before publication.

10. Contact

Add the corresponding author and project contact information here before the HydroShare release.