# GLoOD paper supporting data

This repository contains compressed datasets, model checkpoints, inference
outputs, and post-processing results supporting the GLoOD paper, *Generating
fLOws frOm Data*. It is a public, reduced-size counterpart of the complete
supporting-evidence repository used during the study.

Archives are distributed as `tar.bz2` files. Extract one with:

```bash
tar -xjf path/to/archive.tar.bz2
```

## Contents

```text
datasets/                 Dataset examples and train/test data
inference/                Identity, Swin, and UNet inference outputs
analysis/                  Profile, field-wise, drag-force, and lag analyses
kfold/                     Cross-validation material
models-checkpoints/        Trained model checkpoints
```

The archive names identify the model family, physical case, baseline, or
assessment protocol. The full list of archives is part of this release.

## Code releases used to generate the material

The data-generation and machine-learning workflows used two versioned public
code releases:

* [GLoOD-dataset-generator v1.0.0](https://github.com/dav-dap/GLoOD-dataset-generator/releases/tag/v1.0.0)
  — lattice-Boltzmann/OpenLB flow-field generation;
* [GLoOD v1.0.0](https://github.com/dav-dap/GLoOD/releases/tag/v1.0.0)
  — dataset preparation, model training, inference, checkpoint handling,
  plotting, and assessment.

The commands below document the command families used to produce the released
material. For installation, compilation, dependencies, and system-specific
settings, follow the README in each corresponding code release rather than
duplicating those instructions here.

### 1. Generate flow snapshots with the lattice-Boltzmann code

The `GLoOD-dataset-generator v1.0.0` release contains the OpenLB-based
generator used to produce the raw CFD snapshots. Follow its README to install
and compile the code, configure the target platform and compiler, and run the
case-specific generator. The resulting snapshots are the inputs to the GLoOD
dataset-preparation step.

Conceptually, the workflow is:

```text
GLoOD-dataset-generator v1.0.0
  -> lattice-Boltzmann/OpenLB simulation
  -> raw flow snapshots
```

The exact geometry, flow parameters, sampling settings, and output paths are
case-specific and belong to the generator release documentation and run
configuration.

### 2. Prepare datasets with GLoOD

The `GLoOD v1.0.0` release parses raw CFD snapshots into sharded PyTorch
tensors, creates the dataset index, and produces diagnostic plots. After
following the GLoOD README for installation, representative commands are:

```bash
# Sequential data for next-step prediction:
hslur config=config/dataset_seq.yaml

# Case-specific dataset preparation:
hslur config=config/build_dataset_cavity_matnum.yaml
hslur config=config/build_dataset_circles.yaml
hslur config=config/build_dataset_vonkarman.yaml
```

The selected Hydra configuration determines input paths, parser, sequence
length, channel count, output shards, and diagnostics.

### 3. Train models and create checkpoints

```bash
hslur config=config/train_glood_one_run.yaml
hslur config=config/train_glood_swin_one_run.yaml
hslur config=config/train_glood_unet.yaml

# K-fold variants:
hslur config=config/train_glood_kfold.yaml
hslur config=config/train_glood_swin_kfold.yaml
hslur config=config/train_glood_unet_kfold.yaml
```

The resolved Hydra configuration, optimizer and scheduler state, and model
weights are saved with each run. The extracted run metadata is authoritative
for exact hyperparameters.

### 4. Run inference

```bash
hslur config=config/infer_matnum.yaml
hslur config=config/infer_matnum_identity.yaml
hslur config=test_config/infer_glood_unet.yaml
```

These runs produce predicted field sequences and metadata in the layout used
by the assessment scripts. The `id-*`, `swin-*`, and `unet-*` archives in
`inference/` correspond to these baseline and model-family runs.

### 5. Produce analyses and figures

```bash
hslur config=config/assess_profiles_remote_matnum.yaml
hslur config=config/assess_fieldwise_remote_matnum.yaml
hslur config=config/assess_drag_force_remote_matnum.yaml
hslur config=config/assess_vonkarman_lag_remote_matnum.yaml
hslur config=config/assess_vonkarman_vtkp06_lag_remote_matnum.yaml

# Aggregate independent or k-fold training histories:
hslur config=config/process_stats.yaml
hslur config=config/process_stats_kfold.yaml
```

These commands generate profile errors, whole-field diagnostics, drag-force
statistics, von Kármán lag comparisons, and aggregated training statistics.

## Data conventions

The primary field-channel order is `(p, ux, uy)`. Sequence examples
conventionally have layout `(L, H, W, C)`. For next-step training, inputs
contain timesteps `t0..t(L-2)` and targets contain the shifted sequence
`t1..t(L-1)`. Some datasets and diagnostics may also contain a material-map
(`matnum`) channel; when present, it is auxiliary and is not one of the three
primary flow channels.

## Reproducibility

When reporting results, record the archive name, the source-code release
(`GLoOD-dataset-generator v1.0.0` and/or `GLoOD v1.0.0`), and the extracted
directory. The commands above are workflow recipes; exact reruns additionally
require the resolved Hydra configuration, run metadata, input paths, and any
case-specific generator settings stored with the relevant material.

## Citation

If you use these data, checkpoints, or generated results, please cite the
accompanying GLoOD paper and acknowledge this supporting-data release. The
formal bibliographic citation and persistent repository identifier should be
added here when the paper and data release receive their final metadata.

## License

Unless a different notice accompanies a particular component, the contents of
this repository are released under the **Creative Commons Attribution 4.0
International (CC BY 4.0)** license. See [LICENSE](LICENSE) or the [full legal
code](https://creativecommons.org/licenses/by/4.0/legalcode).