Merge pull request #12 from gregtucker/gt/add-gh-run-script-and-examples

Gt/add gh run script and examples

README.md

@@ -1,32 +1,81 @@
 # Grain Hill Model
 
+
 ## About
 
 This repository contains source code for the Grain Hill cellular automaton model.
  Grain Hill simulates the morphology and evolution of a hypothetical hillslope cross-sectional profile. The model builds on [CellLab-CTS](https://github.com/landlab/landlab/wiki/CellLab-CTS-2015-Users-Manual) framework, which is an element of the [Landlab Toolkit](http://landlab.github.io).  The package includes the Grain Facet model, which is a variant of Grain Hill that models the cross-sectional profile evolution of a normal-fault facet, with slip on a 60-degree dipping normal fault. The Grain Hill and Grain Facet models, their underlying continuous-time stochastic algorithms, and the Landlab framework on which they are built, are described in several journal articles. Tucker et al. (2016) present the general CellLab-CTS framework and its algorithms. Tucker et al. (2018) describe the Grain Hill model, and use the model to analyze a range of different types of hillslope landform. Tucker et al. (in review) present the Grain Facet model and use it to analyze the necessary and sufficient conditions to account for observed facet landforms and their variations. The Landlab Toolkit itself is described by Hobley et al. (2017) and Barnhart et al. (in review).
 
+
 ## Dependencies
 
-Grain Hill requires [Landlab](https://landlab.github.io) version 2.0.0beta or higher.
+Grain Hill requires [Landlab](https://landlab.github.io) version 2.0.0beta or higher, and [bmipy](https://github.com/csdms/bmi-python).
+
 
 ## Installation
 
 Clone or fork this repository. To install, navigate to the `grain_hills` folder and run `python setup.py`.
 
+
 ## How to Run
 
-(include an example)
+The simplest usage is to navigate to the `grain_hills` folder in a terminal window, and run:
+
+`python run_grain_hill.py <input file>`
+
+A good starting example, available in the `examples` folder, is:
+
+`python run_grain_hill.py examples/small_regolith_hill.txt`
+
+GrainHill can also be run using [Basic Model Interface (BMI)](https://bmi.readthedocs.org) functions executed in a Python script, shell, or notebook. Because the GrainHill (and BlockHill and GrainFacetSimulator) models are implemented as classes, they can be directly instantiated and initialized in a Python script, with parameters passed as individual arguments to the `__init__` method, or in a dictionary (passed using `**` preceding the name of the dictionary).
+
 
 ## Input and Output Files
 
+The `run_grain_hill.py` script reads parameters from a text file in `yaml` format. An example is:
+
+    # GrainHill input file:
+    #
+    # small_regolith_hill: runs a simulation with steady uplift and
+    # all regolith material (no rock)
+    #
+    number_of_node_rows: 40
+    number_of_node_columns: 92
+    cell_size: 0.1
+    grav_accel: 9.8
+    friction_coef: 1.0
+    run_duration: 3000.0
+    uplift_interval: 100.0
+    disturbance_rate: 0.01
+    weathering_rate: 0.001
+    rock_state_for_uplift: 7
+    opt_rock_collapse: 0
+    opt_track_grains: False
+    save_plots: True
+    plot_filename: 'small_hill'
+    plot_filetype: '.png'
+    plot_interval: 500.0
+    output_interval: 1.0e20
+    report_interval: 5.0
+
+GrainHill output is saved in Landlab native format, and can be opened and read using the Landlab `load_grid` function (`from landlab.io.native_landlab import load_grid`). This saves the Landlab grid object along with all of its fields, including the `node_state` field that encodes the current state code for each node in the grid. For information on the native Landlab format, see the documentation for the [`save_grid`](https://landlab.readthedocs.io/en/master/reference/io/native_landlab.html#landlab.io.native_landlab.save_grid) and [`load_grid`](https://landlab.readthedocs.io/en/master/reference/io/native_landlab.html#landlab.io.native_landlab.load_grid) functions.
+
+In addition, if `save_plots` is `True` and the `plot_interval` is less than the `run_duration`, plots will be saved to files in addition to being displayed on screen (the default format is .png; this can be changed using the `plot_filetype` parameter).
+
 
 ## Examples
 
+Several example input files can be found in the `examples` folder.
+
 
 ## How to Cite
 
+Recommended citations:
 
-## Licensing
+- GrainHill package: Tucker et al. (2018)
+- GrainFacet package: Tucker et al. (in review)
+- CellLab-CTS : Tucker et al. (2016)
+- Landlab Toolkit: Hobley et al. (2017), Barnhart et al. (in review)
 
 
 ## References:

examples/dissolution_fast.txt

@@ -0,0 +1,25 @@
+# GrainHill input file:
+#
+# dissolution_fast: runs a simulation with steady fault slip and
+# dissolution (only), with a relatively high dissolution efficiency.
+# Reproduces the run in Figure 7d in Tucker et al. (2020). 
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0 
+output_interval: 1.0e99
+dissolution_rate: 4.4e-4
+disturbance_rate: 0.0
+weathering_rate: 0.0
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'dissolve_dr44_'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: -0.01 
+

examples/dissolution_slow.txt

@@ -0,0 +1,25 @@
+# GrainHill input file:
+#
+# dissolution_slow: runs a simulation with steady fault slip and
+# dissolution (only), with a relatively low dissolution efficiency.
+# Reproduces the run in Figure 7a in Tucker et al. (2020). 
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0 
+output_interval: 1.0e99
+dissolution_rate: 8.0e-5
+disturbance_rate: 0.0
+weathering_rate: 0.0
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'dissolve_dr8_'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: -0.01 
+

examples/facet_high_w_high_d.txt

@@ -0,0 +1,25 @@
+# GrainHill input file:
+#
+# facet_high_w_high_d: runs a simulation with steady fault slip, and relatively 
+# high rates of weathering and disturbance. Reproduces the run in upper right
+# corner of Figure 9 in Tucker et al. (2020). 
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0 
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.1
+weathering_rate: 0.1
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_high_w_high_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: -0.01 
+

examples/facet_high_w_low_d.txt

@@ -0,0 +1,25 @@
+# GrainHill input file:
+#
+# facet_high_w_low_d: runs a simulation with steady fault slip, a relatively 
+# high weathering rate, and a relatively low disturbance rate. Reproduces the
+# run in upper left corner of Figure 9 in Tucker et al. (2020). 
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0 
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.0001
+weathering_rate: 0.1
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_high_w_low_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: -0.01 
+

examples/facet_low_w_high_d.txt

@@ -0,0 +1,25 @@
+# GrainHill input file:
+#
+# facet_low_w_high_d: runs a simulation with steady fault slip, a relatively 
+# low weathering rate, and a relatively high disturbance rate. Reproduces the 
+# run in lower right corner of Figure 9 in Tucker et al. (2020). 
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0 
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.1
+weathering_rate: 0.0001
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_low_w_high_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: -0.01 
+

examples/facet_low_w_low_d.txt

@@ -0,0 +1,24 @@
+# GrainHill input file:
+#
+# facet_low_w_low_d: runs a simulation with steady fault slip, and relatively
+# low rates of weathering and disturbance. Reproduces the run in lower left
+# corner of Figure 9 in Tucker et al. (2020).
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.0001
+weathering_rate: 0.0001
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_low_w_low_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: -0.01

examples/facet_with_wedge_blrise_high_w_high_d.txt

@@ -0,0 +1,27 @@
+# GrainHill input file:
+#
+# facet_with_wedge_blrise_high_w_high_d: runs a simulation with steady fault
+# slip, and relatively high rates of weathering and disturbance. Fault is
+# positioned at x=23, allowing the formation of a colluvial wedge. Baselevel
+# rise is imposed at left model boundary. Reproduces the run in upper right
+# corner of Figure 13 in Tucker et al. (2020).
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.1
+weathering_rate: 0.1
+uplift_interval: 866.0
+baselevel_rise_interval: 4000.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_with_wedge_blrise_high_w_high_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: 23.0

examples/facet_with_wedge_blrise_high_w_low_d.txt

@@ -0,0 +1,27 @@
+# GrainHill input file:
+#
+# facet_with_wedge_blrise_high_w_low_d: runs a simulation with steady fault
+# slip, a relatively high weathering rate, and a relatively low disturbance
+# rate. Fault is positioned at x=23, allowing the formation of a colluvial
+# wedge. Baselevel rise is imposed at left model boundary. Reproduces the run
+# in upper left corner of Figure 13 in Tucker et al. (2020).
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.0001
+weathering_rate: 0.1
+uplift_interval: 866.0
+baselevel_rise_interval: 4000.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_with_wedge_blrise_high_w_low_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: 23.0

examples/facet_with_wedge_blrise_low_w_high_d.txt

@@ -0,0 +1,27 @@
+# GrainHill input file:
+#
+# facet_with_wedge_blrise_low_w_high_d: runs a simulation with steady fault
+# slip, a relatively low weathering rate, and a relatively high disturbance
+# rate. Fault is positioned at x=23, allowing the formation of a colluvial
+# wedge. Baselevel rise is imposed at left model boundary. Reproduces the run
+# in lower right corner of Figure 13 in Tucker et al. (2020).
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.1
+weathering_rate: 0.0001
+uplift_interval: 866.0
+baselevel_rise_interval: 4000.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_with_wedge_blrise_low_w_high_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: 23.0

examples/facet_with_wedge_blrise_low_w_low_d.txt

@@ -0,0 +1,27 @@
+# GrainHill input file:
+#
+# facet_with_wedge_blrise_low_w_low_d: runs a simulation with steady fault slip,
+# and relatively low rates of weathering and disturbance. Fault is positioned at
+# x=23, allowing the formation of a colluvial wedge. Baselevel rise is imposed
+# at left model boundary. Reproduces the run in lower left corner of Figure 13
+# in Tucker et al. (2020).
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.0001
+weathering_rate: 0.0001
+uplift_interval: 866.0
+baselevel_rise_interval: 4000.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_with_wedge_blrise_low_w_low_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: 23.0

examples/facet_with_wedge_high_w_high_d.txt

@@ -0,0 +1,25 @@
+# GrainHill input file:
+#
+# facet_with_wedge_high_w_high_d: runs a simulation with steady fault slip,
+# and relatively high rates of weathering and disturbance. Fault is positioned
+# at x=23, allowing the formation of a colluvial wedge. Reproduces the run in
+# upper right corner of Figure 12 in Tucker et al. (2020).
+#
+model_type: 'facet'
+number_of_node_rows: 111
+number_of_node_columns: 81
+cell_width: 0.5
+grav_accel: 9.8
+report_interval: 5.0
+run_duration: 130000.0
+output_interval: 1.0e99
+dissolution_rate: 0.0
+disturbance_rate: 0.1
+weathering_rate: 0.1
+uplift_interval: 866.0
+plot_interval: 26000.0
+save_plots: True
+plot_filename: 'facet_with_wedge_high_w_high_d'
+plot_filetype: '.png'
+friction_coef: 1.0
+fault_x: 23.0