Underground facies (= kind of sediment) modeling with GANs.
Disclaimer: This repository is a work in progress. This code aims to be the official implementation of a not already published research paper. It provides a complete code to train and evaluate some GANs for facies modeling as well as unit tests and a small ready-to-use dataset (see below).
Date: 2022-07-20
Author: github@Valentingol
Work during my 5 months internship at IFPEN, supervised by UVSQ and financed by DATAIA Paris Saclay.
Copyright ยฉ 2022 Goldite Valentin
MIT License (see here)
2D Models:
-
sagan
- Unconditional SAGAN (based on Self-Attention Generative Adversarial Networks and Modeling of subsurface sedimentary facies using SAGANs) -
cond_sagan
- Conditional SAGAN (based on papers above for SAGAN part and GANSim: Conditional Facies Simulation Using an Improved Progressive Growing of GANS for conditional part) that also reconstructs input pixel maps
Note that you can disable self-attention in the configurations (similar to DCGAN architecture).
Install the module and dependencies in a virtual environment with Python 3.7-3.10. Using Linux or WSL is recommended to use JAX for faster metrics computation but it is not mandatory.
pip install -e .
pip install -r requirements.txt
# dependencies without JAX (windows users):
pip install -r requirements-nojax.txt
# for developers:
pip install -r requirements-dev.txt
A small dataset is available by default in this repository. It contains 2000 synthesized images representing some channels and 3 kind of facies and was generated in the GANSim project (under MIT license).
You can simply run a train on the default dataset with unconditional SAGAN
model using the following command in gan_facies
folder:
python gan_facies/apps/train.py
You can see the progress of the training in the terminal and the resulted
images and trained networks in the res
folder.
More data are available in this repository. Simply extract datasets/datasets.zip
in the datasets
folder. It contains a bigger version of the GANSim dataset as
well as Rongier et al. (2016) dataset
and Stanford VI-E dataset.
If you use this dataset in your work, please cite the original authors.
Of course, you can use your own dataset. Simply drop it in the datasets
folder.
The dataset should be a Numpy file (.npy
) containing a 3D ndarray with format
(z/depth/n_samples, y, x) of type uint8
with a different number for each
facies, starting from 0. The number of facies is then dataset.max() + 1
.
Now tou can run the training adding the --dataset_path=<mypath>
argument.
You can also change the dataset path via configuration files. The next section
explains how to do that.
It is always interesting to customize the training with your own configurations. This repository contains a lot of configuration organized in multiple sub-configurations. The management of the configurations is simply done thanks to the smart configuration manager YAECS.
The default sub-configurations (for models, training, ...) are organized in
different json files in configs/default
. You can launch your own experiment by
writing a new .yaml
file that will be merged with the default configuration.
Some examples are available in configs/exp
. For example, the following file
will override the default value of the name of the run as well as discriminator
learning rate to 0.001:
# >> file 'configs/exp/my_config.yaml'
run_name: my_experiment
training.d_lr: 0.001
Then you can run the experiment by adding the configuration in command line.
python gan_facies/apps/train.py --config gan_facies/configs/exp/my_config.yaml
Note: The space between the --config
and the configuration file is important.
Moreover you can override parameters also by adding them in the command line. For example this will override the default configuration with your experiment configuration, then set the generator learning rate to 0.001 and the generator random input dimension to 64:
python gan_facies/apps/train.py --config gan_facies/configs/exp/my_config.yaml --training.g_lr=0.001\
--model.z_dim=64
Note: The =
between the --param
and the value is important.
To use conditional model you can check the configs/exp/conditional.yaml
file
and adapt it to your needs. An other way is to use the merging of configurations
in cascade provided by yaecs. In fact, if you can put list of configuration
file for --configs
, they will be merge together (from the begin of the list
to the end). Example:
python gan_facies/apps/train.py --config [gan_facies/configs/exp/models/cond_sagan.yaml,gan_facies/configs/exp/my_config.yaml]
First configs/exp/models/cond_sagan.yaml
will be merged (changing model configuration)
then configs/exp/my_config
(overwriting model configuration if needed).
You can create your own specific configurations (for data, models, metric, ...)
and merge as many of them as you want.
Finally, the configurations will be automatically saved (by default in res/configs
)
to ensure that you can always recover the exact configuration used for the runs.
The "hierarchy of merging" is also saved to understand quickly how the configuration
was merged (with what experiment file(s) and what command line parameters).
A description of all configuration parameters is available in CONFIG_SUMMARY.md
.
Weights and Biases (WandB) and ClearML are two very popular platform of ML experience tracking, used to visualize the logs of a training session (curves, generated images, ...), compare the results of different runs and different configurations, reveal the more interesting parameters and many utilities to explore parameters space (collaboratively or not), etc.
This repository allows to use WandB and ClearML very simply. You can check the default
configuration implying WandB and ClearML in configs/default/experiment_tracking.yaml
.
To use Wandb or ClearML you first need to install them, create an account if
you don't have one and set the configuration wandb.use_wandb: True
or
clearml.use_clearml: True
in addition to the parameters for initialize
the WandB run or ClearML task.
Plus, you can explore the parameters space using wandb.sweep
. To do so, you
simply need to create a sweep config such as in configs/sweep/ex_sweep.yaml
and set wandb.sweep_config_path: <path/to/sweep/file>
.
Some examples (using wandb without and with sweep and ClearML) are available
in configs/exp
.
Note:
- It is currently not possible to use both ClearML and WandB at the same time
- It is currently not possible to use hyperparameter search with ClearML
(only with wandb sweep). But we welcome any contribution to add this feature
(see
CONTRIBUTE.md
)
![]() |
---|
Real Images |
![]() |
---|
Generated Images (128 |
![]() |
---|
Real Images |
![]() |
---|
Generated Images (128 |
![]() |
---|
Real Images |
![]() |
---|
Generated Images (128 |
- Add test for generator in
apps/train.py
- Add generated results on GANSim dataset and Stanford VI dataset
- Add conditional SAGAN
- Add images generated by conditional model and metrics in README
- Add 3D models
We welcome any contribution to improve this repository. Please have a look on CONTRIBUTE.md. Thank you very much! ๐