update docs, cleanup, add another tests

docs/source/guides/10min.rst

@@ -8,31 +8,33 @@ Use pyDeltaRCM in ten minutes!
 You can get a model running with three simple lines of code.
 First, we instantiate the main :obj:`~pyDeltaRCM.deltaRCM_driver.pyDeltaRCM` model object.
 
-.. code:: 
+.. doctest:: 
 
     >>> import pyDeltaRCM
 
-    >>> delta = pyDeltaRCM.deltaRCM_driver.pyDeltaRCM()
+    >>> delta = pyDeltaRCM.DeltaModel()
 
 Next, since this is just a simple demo, we will run for a few short timesteps.
-The delta model is run forward with a call to the :meth:`~pyDeltaRCM.deltaRCM_driver.pyDeltaRCM.update()` method of the delta model.
-So we loop a few times and then finalize the model:
+The delta model is run forward with a call to the :meth:`~pyDeltaRCM.DeltaModel.update()` method of the delta model.
+So we loop the update function, and then finalize the model:
 
-.. code::
+.. doctest::
 
-    >>> for _t in range(0, 1):
-    >>>     delta.update()
+    >>> for _ in range(0, 2):
+    ...     delta.update()
 
     >>> delta.finalize()
 
-That's it! You ran the pyDeltaRCM model for one timestep. 
+That's it! You ran the pyDeltaRCM model for two timesteps. 
 
-We can visualize the delta bed elevation, though it's not very exciting after only one timestep...
+We can visualize the delta bed elevation, though it's not very exciting after only two timestep...
 
 .. code::
 
+    >>> import matplotlib.pyplot as plt
+
     >>> fig, ax = plt.subplots()
-    >>> ax.imshow(delta.bed_elevation, vmax=-4.5)
+    >>> ax.imshow(delta.bed_elevation, vmax=-4)
     >>> plt.show()
 
 .. plot:: 10min/model_run_visual.py

docs/source/guides/userguide.rst

@@ -18,7 +18,7 @@ Inside this file you can specify parameters for your run, with each parameter on
     S0: 0.005
     seed: 42
 
-then a :obj:`~pyDeltaRCM.model.DeltaModel` model instance initialized with this file specified as ``input_file`` will have a slope of 0.005, and will use a random seed of 42.
+then a :obj:`~pyDeltaRCM.DeltaModel` model instance initialized with this file specified as ``input_file`` will have a slope of 0.005, and will use a random seed of 42.
 Multiple parameters can be specified line by line.
 
 Default values are substituted for any parameter not explicitly given in the ``input_file`` ``.yml`` file.
@@ -30,7 +30,7 @@ Starting model runs
 ===================
 
 There are two API levels at which you can interact with the pyDeltaRCM model.
-There is a "high-level" model API, which takes as argument a YAML configuration file, and will compose a list as jobs as indicated in the YAML file; the setup can be configured to automatically execute the job list, as well.
+There is a "high-level" model API, which takes as argument a YAML configuration file, and will compose a list of jobs as indicated in the YAML file; the setup can be configured to automatically execute the job list, as well.
 The "low-level" API consists of creating a model instance from a YAML configuration file and manually handling the timestepping, or optionally, augmenting operations of the model to implement new features.
 
 
@@ -51,8 +51,8 @@ For the following high-level API demonstrations, consider a YAML input file name
 Command line API
 ----------------
 
-To invoke a model run from the command line using the YAML file ``model_configuration.yml``, 
-we would simply invoke:
+To invoke a model run from the command line using the YAML file ``model_configuration.yml`` defined above, 
+we would simply call:
 
 .. code:: bash
     
@@ -64,8 +64,8 @@ or equivalently:
     
     python -m pyDeltaRCM --config model_configuration.yml
 
-These invokations will run the pyDeltaRCM :obj:`preprocessor <pyDeltaRCM.preprocessor.PreprocessorCLI>` model with the parameters specified in the ``model_configuration.yml`` file. 
-If the YAML configuration indicated multiple jobs (:ref:`via matrix expansion or ensemble specification <configuring_multiple_jobs>`), the jobs will each be run automatically by calling :obj:`~pyDeltaRCM.model.DeltaModel.update` on the model 500 times.
+These invokations will run the pyDeltaRCM :obj:`preprocessor <pyDeltaRCM.preprocessor.PreprocessorCLI>` with the parameters specified in the ``model_configuration.yml`` file. 
+If the YAML configuration indicates multiple jobs (:ref:`via matrix expansion or ensemble specification <configuring_multiple_jobs>`), the jobs will each be run automatically by calling :obj:`~pyDeltaRCM.DeltaModel.update` on the model 500 times.
 
 
 
@@ -84,12 +84,12 @@ iinteract with the model by creating your own script, and manipulating model out
 
     delta = DeltaModel(input_file='model_configuration.yml')
 
-    for time in range(0,1):
+    for _ in range(0, 1):
         delta.update()
 
     delta.finalize()
 
-However, you can also inspect/modify the :obj:`~pyDeltaRCM.model.DeltaModel.update` method, and change the order or add operations as desired.
+However, you can also inspect/modify the :obj:`~pyDeltaRCM.DeltaModel.update` method, and change the order of operations, or add operations, as desired.
 
 
 =============================

docs/source/pyplots/10min/model_run_visual.py

@@ -1,6 +1,6 @@
 import sys
 import os
-sys.path.append(os.path.realpath(os.getcwd() + "/../../../../"))
+# sys.path.append(os.path.realpath(os.getcwd() + "/../../../../"))
 
 import matplotlib.pyplot as plt
 
@@ -9,12 +9,12 @@
 
 delta = pyDeltaRCM.DeltaModel()
 
-for _t in range(0, 1):
+for _t in range(0, 2):
     delta.update()
 
 delta.finalize()
 
 
 fig, ax = plt.subplots()
-ax.imshow(delta.bed_elevation, vmax=-4.5)
+ax.imshow(delta.bed_elevation, vmax=-4)
 plt.show()

pyDeltaRCM/preprocessor.py

@@ -154,6 +154,8 @@ def __init__(self, input_file, yaml_timesteps, arg_timesteps):
                                  'argument, in order to use the high-level API.')
             self.timesteps = _timesteps
 
+            self._is_completed = False
+
         def run_job(self):
             """Loop the model.
 
@@ -168,6 +170,7 @@ def finalize_model(self):
             """Finalize the job.
             """
             self.deltamodel.finalize()
+            self._is_completed = True
 
 
 class PreprocessorCLI(BasePreprocessor):

tests/test_initialization.py

@@ -14,7 +14,7 @@
 from utilities import test_DeltaModel
 
 
-# test yaml parsing 
+# test yaml parsing
 
 def test_override_from_testfile(test_DeltaModel):
     out_path = test_DeltaModel.out_dir.split('/')
@@ -196,7 +196,7 @@ def test_entry_point_python_main_call_dryrun(tmp_path):
     exp_path_nc = os.path.join(tmp_path / 'test', 'pyDeltaRCM_output.nc')
     exp_path_png = os.path.join(tmp_path / 'test', 'eta_0.0.png')
     assert os.path.isfile(exp_path_nc)
-    assert not os.path.isfile(exp_path_png) # does not exist because --dryrun
+    assert not os.path.isfile(exp_path_png)  # does not exist because --dryrun
 
 
 def test_entry_point_python_main_call_timesteps(tmp_path):
@@ -233,12 +233,13 @@ def test_error_if_no_timesteps(tmp_path):
 
 import pyDeltaRCM as _pyimportedalias
 
+
 def test_version_call():
     """
     test calling the command line feature to query the version.
     """
     encoding = locale.getpreferredencoding()
-    printed1 = subprocess.run(['pyDeltaRCM', '--version'], 
+    printed1 = subprocess.run(['pyDeltaRCM', '--version'],
                               stdout=subprocess.PIPE, encoding=encoding)
     assert printed1.stdout == 'pyDeltaRCM ' + _pyimportedalias.__version__ + '\n'
     printed2 = subprocess.run(
@@ -264,6 +265,38 @@ def test_python_highlevelapi_call_without_timesteps(tmp_path):
         pp = preprocessor.Preprocessor(p)
 
 
+def test_python_highlevelapi_call_with_timesteps_yaml_init_types(tmp_path):
+    file_name = 'user_parameters.yaml'
+    p, f = utilities.create_temporary_file(tmp_path, file_name)
+    utilities.write_parameter_to_file(f, 'out_dir', tmp_path / 'test')
+    utilities.write_parameter_to_file(f, 'timesteps', 2)
+    f.close()
+    pp = preprocessor.Preprocessor(p)
+    assert type(pp.job_list) is list
+    assert len(pp.job_list) == 1
+    assert type(pp.job_list[0]) is preprocessor.Preprocessor._Job
+    assert type(pp.job_list[0].deltamodel) is DeltaModel
+    assert pp.job_list[0]._is_completed == False
+
+
+def test_python_highlevelapi_call_with_timesteps_yaml_runjobs(tmp_path):
+    file_name = 'user_parameters.yaml'
+    p, f = utilities.create_temporary_file(tmp_path, file_name)
+    utilities.write_parameter_to_file(f, 'Length', 10.0)
+    utilities.write_parameter_to_file(f, 'Width', 10.0)
+    utilities.write_parameter_to_file(f, 'dx', 1.0)
+    utilities.write_parameter_to_file(f, 'L0_meters', 1.0)
+    utilities.write_parameter_to_file(f, 'N0_meters', 2.0)
+    utilities.write_parameter_to_file(f, 'out_dir', tmp_path / 'test')
+    utilities.write_parameter_to_file(f, 'timesteps', 2)
+    f.close()
+    pp = preprocessor.Preprocessor(p)
+    assert len(pp.job_list) == 1
+    assert pp.job_list[0]._is_completed == False
+    pp.run_jobs()
+    assert pp.job_list[0]._is_completed == True
+
+
 def test_python_highlevelapi_call_with_args(tmp_path):
     """
     test calling the python hook command line feature with a config file.
@@ -283,13 +316,16 @@ def test_python_highlevelapi_call_with_args(tmp_path):
     pp = preprocessor.Preprocessor(input_file=p, timesteps=2)
     assert type(pp.job_list) is list
     assert len(pp.job_list) == 1
-    pp.run_jobs()
     assert type(pp.job_list[0]) is preprocessor.Preprocessor._Job
     assert type(pp.job_list[0].deltamodel) is DeltaModel
     assert pp.job_list[0].deltamodel.Length == 10.0
     assert pp.job_list[0].deltamodel.Width == 10.0
     assert pp.job_list[0].deltamodel.dx == 1.0
     assert pp.job_list[0].deltamodel.seed == 0
+    assert pp.job_list[0]._is_completed == False
+    pp.run_jobs()
+    assert len(pp.job_list) == 1
+    assert pp.job_list[0]._is_completed == True
     exp_path_nc = os.path.join(tmp_path / 'test', 'pyDeltaRCM_output.nc')
     exp_path_png = os.path.join(tmp_path / 'test', 'eta_0.0.png')
     exp_path_png1 = os.path.join(tmp_path / 'test', 'eta_1.0.png')
@@ -300,8 +336,8 @@ def test_python_highlevelapi_call_with_args(tmp_path):
     assert not os.path.isfile(exp_path_png3)
 
 
-import pyDeltaRCM
-
 def test_Preprocessor_toplevelimport():
+    import pyDeltaRCM
+
     assert 'Preprocessor' in dir(pyDeltaRCM)
     assert pyDeltaRCM.Preprocessor is pyDeltaRCM.preprocessor.Preprocessor