First stable release 1.0.0; Add scripts for initializing input files,…

… executing simulation, and analyzing model results.

Merge branch 'dev' into HR2022

.gitignore

@@ -1,6 +1,10 @@
+### system ###
+__pycache__
+*.code-workspace
+
+### code ###
 src/*.o
 src/*.mod
-util/__pycache__
 src/flac
 src/*.diff
 *.0
@@ -9,4 +13,9 @@ area.dat
 *.save
 vbc.s
 sys.msg
-output.asc
+output.asc
+
+### HR2022 ###
+analysis
+models
+pbs

CITATION.cff

@@ -11,7 +11,7 @@ authors:
   given-names: "Luc L."
   orcid: "https://orcid.org/0000-0001-7839-4263"
 title: "geoflac"
-version: 0.1.1
+version: 1.0.0
 doi: 10.5281/zenodo.7353424
-date-released: 2022-11-24
+date-released: 2022-12-18
 url: "https://doi.org/10.5281/zenodo.7353424"

HR2022/README.md

@@ -0,0 +1,273 @@
+## HR2022: Geoflac for thermochronology
+
+Authors: [Chase J. Shyu](https://orcid.org/0000-0002-7144-1394), [Eh Tan](https://orcid.org/0000-0002-1815-9613), and [Lavier, Luc L.](https://orcid.org/0000-0001-7839-4263)
+
+[![DOI](https://zenodo.org/badge/243178476.svg)](https://zenodo.org/badge/latestdoi/243178476)
+
+### Description:
+This repository demostrates and enables open access of the thermochronological data and model results in Shyu et al. (2022). The repository contents the scripts which can generate the input files of up to 70000 models and analyze the model results presented in the paper.
+1. For directory sturcture and individual file description, please go to [File tree](#file-tree).
+2. For introduction, please go to [How to use HR2022](#how-to-use-hr2022).
+3. For reconstruction of result figures in HR20222, please go to [How to reconstruct HR2022](#how-to-plot-the-result-figures-in-the-hr2022)
+4. For advanced instruction, please go to [Examples](#examples) and [src/params.py](/HR2022/src/params.py#L70).
+<br/>
+
+---
+## How to use HR2022?
+
+#### Part I: Installation
+
+0. [Download and checkout HR2022](#0-download-and-checkout-hr2022-only-when-using-github) 
+   (Only when using github)
+1. [Compile geoflac](#1-compile-geoflac)
+2. [Install Python package](#2-install-python-package)
+
+#### Part II: Simulation of best-fit models
+
+3. [Initialize the input files of 124 best-fit models](#3-initialize-the-input-files-of-124-best-fit-models)
+4. [Execute simulation of best-fit models](#4-execute-simulation-of-best-fit-models)
+5. [Analyze model results to get figures of statistic analysis](#5-analyze-model-results-to-get-figures-of-statistic-analysis)
+
+#### Part III: Simulation of series models
+
+6. [Initialize the input files of 572 models in selected series](#6-initialize-the-input-files-of-572-models-in-selected-series)
+7. [Execute simulation of series models](#7-execute-simulation-of-series-models)
+8. [Analyze model results to get misfit maps for model series](#8-analyze-model-results-to-get-misfit-maps-for-model-series)
+
+**_NOTE:_** The simulations are divided into two parts: best-fit models and series models. Two parts of simulation generate model results for different statistic analysis.
+
+
+### Part I: Installation
+
+#### 0. Download and checkout HR2022
+(Only when using github)
+```sh
+$ git clone https://github.com/chaseshyu/geoflac.git
+$ cd geoflac/
+$ git checkout HR2022
+```
+The data and scripts of HR2022 is on branch HR2022. Please use git command to checkout the branch HR2022.
+
+#### 1. Compile geoflac
+```sh
+$ cd path/to/geoflac/src/
+$ make
+```
+**geoflac** requires fortran compiler. The default compiler is [gfortran](https://gcc.gnu.org/wiki/GFortran). An executable file **flac** will be created in `src/`. Please go to [/README.md](/README.md) for more information about **geoflac**.
+
+#### 2. Install python package
+```sh
+$ cd path/to/geoflac/HR2022/
+$ pip install -r requirements.txt # install required packages listed in requirements.txt
+```
+The python analysis tools require **python >= 3.7**. and [**pip**](https://pypi.org) to extract the package information in [`requirements.txt`](/HR2022/requirements.txt).
+</br>
+
+---
+### Part II: Simulation of best-fit models
+The model input files is generated by [`begin.py`](/HR2022/begin.py) with the information in [`data/simulation/information.csv`](/HR2022/data/simulation/information.csv) and files in [`data/simulation/template/`](/HR2022/data/simulation/template/). The input files of the best-fit model in each model series are stored in `HR2022/models/`.
+
+#### 3. Initialize the input files of 124 best-fit models
+```sh
+$ ./begin.py init # create the inputfiles of 124 best-fit models
+```
+Add number after `init` to select the range for initialization (ex. `./begin.py init 1 10`)
+
+#### 4. Execute simulation of best-fit models
+```sh
+$ ./begin.py run # run 124 best-fit models
+```
+This execution contents 124 best-fit models , which would take up to 660 hours coretime to finish.
+
+#### 5. Analyze model results to get figures of statistic analysis
+```sh
+$ ./begin.py ana -set  # analyze and visualize all best-fit models
+$ ./begin.py ana -info # print detail information of best-fit models and
+                       # ensemble information, surface average geotherm
+```
+Plot figure set of relative erosion rate, erosion rate, cooling rate, and repesentative age-elevation relationships (AER) (Fig. 7 in the paper). The figure would be created in `HR2022/analysis/`.
+</br>
+
+---
+### Part III: Simulation of series models
+
+#### 6. Initialize the input files of 572 models in selected series
+
+```sh
+$ ./begin.py init 1 -series # initialize input file of series #001
+```
+The input files of series models are created in the folder `models/001/`.
+#### 7. Execute simulation of series models
+```sh
+$ ./begin.py run 1 -series # simulate 572 models of series #001
+```
+One series has 572 models and would take up to 3000 hours coretime to finish simulations.
+#### 8. Analyze model results to get misfit maps for model series
+```sh
+$ ./begin.py ana 1 -series -sigma # Plot misfit map of series #001 
+```
+The script visualizes the misfit of 572 series models. The figure is storaged in `analysis/sigma/`.
+<br/>
+
+Please go to [`src/params.py`](/HR2022/src/params.py) for more options and arguments.
+</br>
+
+---
+## How to plot the result figures in the HR2022?
+Figures in the HR2022 can be reconstructed with following instructions.
+
+#### AER regression (Fig. 3)
+Analyze thermochrologcial data in the repository.
+```sh
+$ ./begin.py ana -aer_reg
+```
+#### Model informaion (Table 3)
+Initialize, execute and analyze 124 best-fit models.
+```sh
+$ ./begin.py init
+$ ./begin.py run
+$ ./begin.py ana -info
+```
+#### Misfit map of series#001 and #006 (Fig. 6)
+Initialize, execute and analyze all models in series #001 and #006.
+```sh
+$ ./begin.py init 1 6 5 -series       # init series #001 and #006
+$ ./begin.py run 1 6 5 -series        # run series #001 and #006
+$ ./begin.py ana -sigma_set -formal   # plot misfit map of series #001 and #006
+```
+#### Figure set (Fig. 7)
+Initialize, execute and analyze 124 best-fit models.
+```sh
+$ ./begin.py init
+$ ./begin.py run  
+$ ./begin.py ana -set
+```
+#### Detail exposure history (Fig. 8)
+Initialize, execute and analyze the best-fit model in series #006 with 0.005 Myr time interval.
+```sh
+$ ./begin.py init 6 -out_interval 50000 # init best-fit model of series#006 with output interval 50000 yrs (0.005 Myr)
+$ ./begin.py run 6                      # run best-fit model of series#006
+$ ./begin.py ana -evol -update          # read and update cache
+```
+<br/>
+
+---
+## Examples
+
+#### Help of `begin.py` with `help`
+```sh
+$ ./begin.py help        # get help of function
+$ ./begin.py help init   # get help of initialization
+$ ./begin.py help run    # get help of executtion
+$ ./begin.py help ana    # get help of analysis
+``` 
+
+#### Initialize and execute specific models with numbers
+Template: `./begin.py init|run # # # -series # # #`
+```sh
+$ ./begin.py init 120                # init best-fit models in series #120
+$ ./begin.py init 10 30 10           # init best-fit models in series #010 - #030 with interval 10
+$ ./begin.py init 1 -series 10       # init model 10 in series #001
+$ ./begin.py init 1 -series 10 30 2  # init model 10-30 with 2 interval in series #001
+$ ./begin.py init 50 -1 -series      # init all models in series #050 to end(#124)
+$ ./begin.py run 25 30               # run best-fit models in series #025 - #030
+$ ./begin.py run 40 50 5 -series     # run all models in series #040 - #050 with interval 5
+```
+#### Analyze specific models with numbers
+Template: `./begin.py ana # # # -series`
+```sh
+$ ./begin.py ana 6 -series # read model results in series #006
+$ ./begin.py ana 1 50 -series # read model results in series #001 - #050
+$ ./begin.py ana 1 6 5 -series # read model results in series #001 - #006 with interval 5
+```
+#### Update old model data in cache with `-update`
+```sh
+$ ./being.py ana -update # fetch all best-fit model data no matter cache exist or not
+
+```
+#### Output image with PDF format with `-pdf`
+```sh
+$ ./begin.py ana -set -pdf     # Output figure set with PDF format
+```
+#### Clean input files, model result, cache of model with `-clean`
+```sh
+$ ./begin.py init 50 100 -clean  # clean model input files in best-fit model of series #050-#100
+$ ./begin.py run 50 100 -clean   # clean model result of best-fit models in series #050 - #100
+$ ./begin.py ana 50 100 -clean   # clean cache of best-fit models in series #050 - #100
+```
+#### Preview potential command outcomes with `-status`
+```sh
+$ ./begin.py init -status   # check out the status of input files of all best-fit models.
+$ ./begin.py run -status   # check out the status of model result of all best-fit models.
+$ ./begin.py ana -status   # check out the status of catch of all best-fit models.
+$ ./begin.py run 6 -series 50 100 # check out the status of model results of seris #006 model 50-100
+```
+#### Submit jobs to cluster pbs with `-pbs`
+```sh
+$ ./begin.py init 1 10 -series    # init series#1-10 572*10=5720 models.
+$ ./begin.py run 1 10 -pbs <queue_name> -core 4 -divide 20 -status # preview
+$ ./begin.py run 1 10 -pbs <queue_name> -core 4 -divide 20 # divide into 20 jobs with 4 cores (286 models for each job)
+```
+#### Only simulate models around best-fit model with `-around`
+```sh
+$ ./begin.py init 6 -series -around  # init models around best-fit model of series #006
+$ ./begin.py run 6 -series -around   # run models around best-fit model
+$ ./begin.py ana 6 -series -around   # ana models around best-fit model
+```
+The surround models are within an oblique ellipse along trade-off line of average erosion rate and initial geotherm gradient with given long and short axes assigned in [`src/params.py`](/HR2022/src/params.py#L29).
+
+#### Store and operate model in specific directory with `-dir`
+```sh
+$ ./begin.py -dir ~/data/test init # init 124 best-fit models in ~/data/test
+$ ./begin.py -dir ~/data/test run # run 124 best-fit models in ~/data/test
+$ ./begin.py -dir ~/data/test ana # ana 124 best-fit models in ~/data/test
+```
+#### Force initialize or execute models no matter model status with `-force`
+```sh
+$ ./begin.py init -force # init input files not matter file is exist or not
+$ ./begin.py run -force # run model no matter model result is exist or not
+```
+The target files would be deleted first before force init or run.
+
+<br/>
+
+---
+## File tree
+The [`begin.py`](/HR2022/begin.py) is the entrance for initializing, executing, and analyzing models. The folder `models/` is the default directory for the input files and simulation results of models.  `analysis/` is the default directory for figure, csv tables, and cache. Both `models/` and  `analysis/` will be created after command `begin.py init` and `begin.py ana`, respectively.
+```sh
+HR2022/
+├── begin.py # entrance for initializing, executing, and analyzing models.
+├── README.md # instruction (this file)
+├── requirements.txt # requirements for begin.py
+├── models/ # create after init
+├── analysis/ # create after ana; general .png files
+│   ├── cache/ # .npy cache for accelerating repeatly plotting
+│   ├── csv/ # information of models
+│   └── sigma/ # sigma .png files
+├── data/ # information required by simulation and anlysis
+│   ├── simulation/
+│   │   ├── information.csv # series setting
+│   │   ├── template/ # template for input files of model
+│   │   │   ├── create_proftemp_template.py
+│   │   │   └── model_template.inp
+│   │   ├── thermochron.inp # data set for cooling simulation in model
+│   │   └── thermochronology.csv # data set for calculating aer misfit
+│   └── zft/ # zircon fission track counts data
+│       ├── AM02.csv
+│       ├── BG01.csv
+│       ├── BG02.csv
+│       ├── DC01.csv
+│       └── SP01.csv
+└── src/ # source code for begin.py
+    ├── __init__.py
+    ├── abstraction.py
+    ├── analysis.py
+    ├── execute.py
+    ├── initialize.py
+    ├── params.py # parameters and argvs documents of model simulation
+    └── tools.py
+```
+---
+
+## License
+[The MIT License (MIT)](/LICENSE.md)