Merge pull request #246 from amoodie/docs_init

add some initialization documentation, reogranize files.

Author: amoodie

docs/source/info/index.rst

@@ -14,6 +14,7 @@ All of these questions and more are answered here!
 .. toctree::
    :maxdepth: 1
 
+   initialization
    yamlparameters
    modeltime
    hydrodynamics

docs/source/info/initialization.rst

@@ -0,0 +1,78 @@
+**************
+Initialization
+**************
+
+.. currentmodule:: pyDeltaRCM.init_tools
+
+There are many built-in parameters for setting up pyDeltaRCM runs.
+
+
+Domain configuration
+====================
+
+The domain configuration is controlled by a series of input configuration parameters. 
+Conceptually, we can consider the domain of pyDeltaRCM to be made up of an *inlet* along the top edge of the model domain and bounded by a strip of land, and the *basin*.
+
+.. plot:: init_tools/domain_parameters.py
+
+By default, the basin and inlet are both flat and have the same depth. However these characteristics can be controlled by a variety of input parameters explained below. 
+Moreover, any complex initial geometry can be configured by the use of hooks; see an example here :doc:`../examples/slight_slope`.
+
+Domain size
+-----------
+
+The domain size is controlled by the `Length` and `Width` YAML parameters. 
+
+.. plot:: init_tools/domain_size_compare.py
+
+.. hint:: 
+
+       The size of the computational domain is determined by the size of the smallest size of the domain. The value for `Width` should almost always be 2 times `Length` to minimize unecessary calcualtions outside the valid computational domain.
+
+Importantly, the number of cells in the domain is then a function of the domain size in meters and the grid spacing :obj:`dx`. 
+Because the number of grid cells is inverse nonlinearly related to the grid spacing (:math:`numcells = 1/dx^2`), the model runtime is sensitive to the choice of `dx` relative to `Length` and `Width`.
+
+
+Basin depth and inlet depth
+---------------------------
+
+Inlet depth is controlled by :obj:`h0`.
+If no argument is given in the configuration for the parameter :obj:`hb`, then the basin depth is determined to be the same as the inlet depth. 
+However, these depths can be controlled independently.
+
+.. plot:: init_tools/domain_basin_inlet_depth.py
+
+
+Inlet width and length
+----------------------
+
+The inlet length and width are controlled by an inlet length parameter :obj:`L0_meters` and an inlet width parameter :obj:`N0_meters`. 
+In implementation, the input length and width are rounded to the nearest grid location (a function of :obj:`dx`).
+
+.. plot:: init_tools/domain_inlet_geometry.py
+
+
+
+Input water and sediment
+========================
+
+The input flow velocity is determined by :obj:`u0`.
+
+The input water discharge is thus fully constrained by the inlet geometry and the inlet flow velocity as:
+
+.. math::
+       Q_{w0} = h_0 \times N_0 \times u_0
+
+.. hint::
+       Keep in mind that :math:`N_0` is specified in meters as :obj:`N0_meters` in the input configuration. Ditto for the inlet length (:obj:`L0_meters`).
+
+
+Input sediment discharge is then determined by a **percentage concentration** of sediment in the flow :obj:`C0_percent`.
+
+.. math::
+       Q_{s0} = Q_{w0} \times (C_{0percent}/100)
+
+The volume of each parcel of water to be routed is then determined by the total water discharge divided by the number of parcels :obj:`Np_water`.
+The volume of each parcel of sediment to be routed is then determined by the total sediment discharge divided by the number of parcels :obj:`Np_sed`.
+
+The number of sand and mud parcels are then determined as `Np_sed` times :obj:`f_bedload` and `Np_sed` times (1-:obj:`f_bedload`), respectively.

docs/source/info/yamlparameters.rst

@@ -22,8 +22,6 @@ Model Settings
 
 :attr:`pyDeltaRCM.model.DeltaModel.verbose`
 
-:attr:`pyDeltaRCM.model.DeltaModel.seed`
-
 
 .. _model-domain-parameters:
 
@@ -38,18 +36,20 @@ Model Domain Parameters
 
 :attr:`pyDeltaRCM.model.DeltaModel.L0_meters`
 
+:attr:`pyDeltaRCM.model.DeltaModel.N0_meters`
+
 :attr:`pyDeltaRCM.model.DeltaModel.S0`
 
 :attr:`pyDeltaRCM.model.DeltaModel.u0`
 
-:attr:`pyDeltaRCM.model.DeltaModel.N0_meters`
-
 :attr:`pyDeltaRCM.model.DeltaModel.h0`
 
 :attr:`pyDeltaRCM.model.DeltaModel.hb`
 
 :attr:`pyDeltaRCM.model.DeltaModel.H_SL`
 
+:attr:`pyDeltaRCM.model.DeltaModel.seed`
+
 :attr:`pyDeltaRCM.model.DeltaModel.SLR`
 
 :attr:`pyDeltaRCM.model.DeltaModel.f_bedload`
@@ -65,6 +65,44 @@ Model Domain Parameters
 :attr:`pyDeltaRCM.model.DeltaModel.start_subsidence`
 
 
+Reduced-Complexity Routing Parameters
+=====================================
+
+:attr:`pyDeltaRCM.model.DeltaModel.Np_water`
+
+:attr:`pyDeltaRCM.model.DeltaModel.Np_sed`
+
+:attr:`pyDeltaRCM.model.DeltaModel.omega_sfc`
+
+:attr:`pyDeltaRCM.model.DeltaModel.omega_flow`
+
+:attr:`pyDeltaRCM.model.DeltaModel.Nsmooth`
+
+:attr:`pyDeltaRCM.model.DeltaModel.Csmooth`
+
+:attr:`pyDeltaRCM.model.DeltaModel.theta_water`
+
+:attr:`pyDeltaRCM.model.DeltaModel.coeff_theta_sand`
+
+:attr:`pyDeltaRCM.model.DeltaModel.coeff_theta_mud`
+
+:attr:`pyDeltaRCM.model.DeltaModel.beta`
+
+:attr:`pyDeltaRCM.model.DeltaModel.sed_lag`
+
+:attr:`pyDeltaRCM.model.DeltaModel.coeff_U_dep_mud`
+
+:attr:`pyDeltaRCM.model.DeltaModel.coeff_U_ero_mud`
+
+:attr:`pyDeltaRCM.model.DeltaModel.coeff_U_ero_sand`
+
+:attr:`pyDeltaRCM.model.DeltaModel.alpha`
+
+:attr:`pyDeltaRCM.model.DeltaModel.itermax`
+
+:attr:`pyDeltaRCM.model.DeltaModel.stepmax`
+
+
 Output Settings
 ===============
 
@@ -113,41 +151,3 @@ Output Settings
 :attr:`pyDeltaRCM.model.DeltaModel.clobber_netcdf`
 
 :attr:`pyDeltaRCM.model.DeltaModel.legacy_netcdf`
-
-
-Reduced-Complexity Routing Parameters
-=====================================
-
-:attr:`pyDeltaRCM.model.DeltaModel.Np_sed`
-
-:attr:`pyDeltaRCM.model.DeltaModel.Np_water`
-
-:attr:`pyDeltaRCM.model.DeltaModel.omega_sfc`
-
-:attr:`pyDeltaRCM.model.DeltaModel.omega_flow`
-
-:attr:`pyDeltaRCM.model.DeltaModel.itermax`
-
-:attr:`pyDeltaRCM.model.DeltaModel.Nsmooth`
-
-:attr:`pyDeltaRCM.model.DeltaModel.Csmooth`
-
-:attr:`pyDeltaRCM.model.DeltaModel.theta_water`
-
-:attr:`pyDeltaRCM.model.DeltaModel.coeff_theta_sand`
-
-:attr:`pyDeltaRCM.model.DeltaModel.coeff_theta_mud`
-
-:attr:`pyDeltaRCM.model.DeltaModel.beta`
-
-:attr:`pyDeltaRCM.model.DeltaModel.sed_lag`
-
-:attr:`pyDeltaRCM.model.DeltaModel.coeff_U_dep_mud`
-
-:attr:`pyDeltaRCM.model.DeltaModel.coeff_U_ero_mud`
-
-:attr:`pyDeltaRCM.model.DeltaModel.coeff_U_ero_sand`
-
-:attr:`pyDeltaRCM.model.DeltaModel.alpha`
-
-:attr:`pyDeltaRCM.model.DeltaModel.stepmax`

docs/source/pyplots/init_tools/domain_basin_inlet_depth.py

@@ -0,0 +1,66 @@
+import warnings
+
+import matplotlib
+import matplotlib.pyplot as plt
+
+import pyDeltaRCM
+
+
+# filter out the warning raised about no netcdf being found
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+n = 1
+cm = matplotlib.colormaps.get_cmap("tab10")
+
+param_dict = {"timesteps": 0}
+_matrix = {"h0": [2, 5], "hb": [2, 5]}
+param_dict["matrix"] = _matrix
+param_dict["L0_meters"] = 500
+param_dict["N0_meters"] = 500
+
+# init delta models with preprocessor
+with pyDeltaRCM.shared_tools._docs_temp_directory() as output_dir:
+    param_dict.update({"out_dir": output_dir})
+
+    pp = pyDeltaRCM.preprocessor.Preprocessor(param_dict)
+
+    pp.run_jobs()
+
+
+fig, ax = plt.subplots(
+    2, 2, figsize=(6, 4), subplot_kw=dict(aspect="equal"), sharex=True, sharey=True
+)
+
+ax = ax.ravel()
+for i in range(4):
+    ax[i].imshow(
+        pp.job_list[i].deltamodel.eta,
+        interpolation="none",
+        extent=[
+            0,
+            pp.job_list[i].deltamodel.Width,
+            pp.job_list[i].deltamodel.Length,
+            0,
+        ],
+    )
+    ax[i].text(
+        0.05,
+        0.05,
+        f"h0: {pp.job_list[i].deltamodel.h0}\nhb: {pp.job_list[i].deltamodel.hb}",
+        ha="left",
+        va="bottom",
+        color="white",
+        fontsize=8,
+        transform=ax[i].transAxes,
+    )
+
+for i, axi in enumerate(ax.ravel()):
+    axi.tick_params(labelsize=7)
+    if i % 2 == 0:
+        axi.set_ylabel("Length", fontsize=8)
+    if i > 2:
+        axi.set_xlabel("Width", fontsize=8)
+
+plt.tight_layout()
+plt.show()

docs/source/pyplots/init_tools/domain_inlet_geometry.py

@@ -0,0 +1,64 @@
+import warnings
+
+import matplotlib
+import matplotlib.pyplot as plt
+
+import pyDeltaRCM
+
+
+# filter out the warning raised about no netcdf being found
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+n = 1
+cm = matplotlib.colormaps.get_cmap("tab10")
+
+param_dict = {"timesteps": 0}
+_matrix = {"L0_meters": [200, 500, 1000], "N0_meters": [200, 500, 1000]}
+param_dict["matrix"] = _matrix
+
+# init delta models with preprocessor
+with pyDeltaRCM.shared_tools._docs_temp_directory() as output_dir:
+    param_dict.update({"out_dir": output_dir})
+
+    pp = pyDeltaRCM.preprocessor.Preprocessor(param_dict)
+
+    pp.run_jobs()
+
+
+fig, ax = plt.subplots(
+    3, 3, figsize=(9, 5), subplot_kw=dict(aspect="equal"), sharex=True, sharey=True
+)
+
+ax = ax.ravel()
+for i in range(9):
+    ax[i].imshow(
+        pp.job_list[i].deltamodel.eta,
+        interpolation="none",
+        extent=[
+            0,
+            pp.job_list[i].deltamodel.Width,
+            pp.job_list[i].deltamodel.Length,
+            0,
+        ],
+    )
+    ax[i].text(
+        0.05,
+        0.05,
+        f"L0_meters: {pp.job_list[i].deltamodel.L0_meters}\nN0_meters: {pp.job_list[i].deltamodel.N0_meters}",
+        ha="left",
+        va="bottom",
+        color="white",
+        fontsize=8,
+        transform=ax[i].transAxes,
+    )
+
+for i, axi in enumerate(ax.ravel()):
+    axi.tick_params(labelsize=7)
+    if i % 3 == 0:
+        axi.set_ylabel("Length", fontsize=8)
+    if i > 6:
+        axi.set_xlabel("Width", fontsize=8)
+
+plt.tight_layout()
+plt.show()