A Scale-Aware Framework for Characterizing Multiscale Aquifer Heterogeneity by Coordinating Machine Learning and Stochastic Modeling

Scale-aware aquifer heterogeneity workflow

The files include the four-stage workflow code, de-identified restricted inputs, and public run outputs for scale-aware aquifer heterogeneity characterization. Raw borehole records and full processed geological input tables are not redistributed because reuse of the source records is restricted. The included input tables are randomized and de-identified, and are sufficient to run the same model structure used in the manuscript.

Contents

- `code/run_four_stage_workflow.py`: four-stage workflow entry point.- `code/external_geost_engine/ZXDZ.exe`: GEOST executable used by the transition-probability workflow.- `data/sample_inputs/`: de-identified and randomly shuffled sample inputs.- `outputs/`: output directory created by the workflow script.- `docs/`: metadata, data dictionary, and data-availability text.- `tests/`: verification test for the runnable workflow.- `requirements.txt`: Python packages required by the workflow.

Quick start

Create a Python environment with the required packages:

```bashpip install -r requirements.txt```

Run the four-stage workflow from the root directory of this package:

```bashpython code/run_four_stage_workflow.py```

The workflow writes outputs to:

```textoutputs/four_stage_workflow_run/```

Expected output files:

- `stage1_domain_ensemble.csv`: sediment-bedrock ensemble output.- `stage2_weathering_ensemble.csv`: weathered-unweathered bedrock ensemble output.- `stage3_structural_realizations.csv`: clay, sand, weathered bedrock, and unweathered bedrock structural realizations.- `stage3_geost_indicator_points.csv`: clay-sand conditioning indicators for the GEOST-style facies module.- `stage3_reference_transition_probabilities.csv`: reference transition-probability curves from the restricted input.- `stage3_geost_parameter_samples.csv`: facies proportion and mean-length parameters used by each public structural realization.- `stage3_external_geost_engine.json`: record of the archived external GEOST executable and public run mode.- `stage4_k_field_realizations.csv`: facies-conditioned prior log10(K) realizations.- `stage4_k_pilot_points.csv`: pilot-point values used by the workflow.- `stage4_class_statistics.csv`: class-wise statistics for the generated prior K-field realizations.- `four_stage_section.png`: section-style visualization of one structural and K-field realization.- `four_stage_summary.json`: run metadata and basic diagnostics.

Workflow summary

The four-stage workflow uses de-identified grid points and conditioning lithology labels. It first trains a five-classifier ensemble to separate sediment and bedrock domains. It then trains a second ensemble to separate weathered and unweathered bedrock. Within the predicted sediment domain, it uses a GEOST-style transition-probability module to generate conditional clay-sand facies realizations from facies proportions and directional mean lengths. The archived `ZXDZ.exe` file records the external GEOST engine used by the manuscript workflow; the public Python entry point writes the corresponding GEOST-style indicator, parameter, and transition-probability files so the model structure is transparent under restricted public inputs. Finally, the workflow generates facies-conditioned pilot-point prior log10(K) realizations within the four structural classes. Pilot-point values are generated and interpolated only within the same structural class, preserving clay-sand and weathered-unweathered boundaries.

The public run preserves the manuscript model structure. Numerical outputs differ from the manuscript-scale Pearl River Delta results because the full borehole-derived input tables are restricted and are not redistributed.

Input-data policy

The input files in `data/sample_inputs/` are randomized and de-identified subsets. Original borehole identifiers, borehole coordinates, and raw lithology descriptions have been removed. The sample inputs document the file structure and modeling conventions without redistributing the full restricted geological input data.

Expected use

Use these files to check file formats, run the workflow, and reproduce the public structural and prior K-field outputs generated from the de-identified restricted inputs. The full restricted borehole database is not required and is not included.

License

Unless otherwise stated by the authors, the data and documentation may be released under CC BY 4.0. The Python scripts may be released under an open-source software license selected by the authors. The included executable `ZXDZ.exe` is archived as the GEOST engine used by the transition-probability workflow; users should cite or acknowledge its source according to the authors' instructions.