10-minute tutorial

Use pyDeltaRCM in ten minutes! This simple guide will show you the absolute basics of getting a pyDeltaRCM model running, and give you some direction on where to go from there.

Important

If you haven’t already, be sure to follow the installation guide to get pyDeltaRCM set up properly on your computer.

A default model

You can get a model running with five simple lines of Python code. Note that you can run pyDeltaRCM in either a standalone script or part of an interactive session. First, we instantiate the main DeltaModel model object.

>>> import pyDeltaRCM

>>> default_delta = pyDeltaRCM.DeltaModel()

Instantiating the DeltaModel() without any arguments will use a set of default parameters to configure the model run. The default options are a reasonable set for exploring some controls of the model, and would work perfectly well for a simple demonstration here.

The delta model is run forward with a call to the update() method. So, we simply create a for loop, and call the update function, and then wrap everything up with a call to finalize() the model:

>>> for _ in range(0, 5):
...     default_delta.update()

>>> default_delta.finalize()

Note

Additional calls to update the model can be called up until the model is finalized.

That’s it! You ran the pyDeltaRCM model for five timesteps, with just five lines of code.

We can visualize the delta bed elevation, though it’s not very exciting after only five timesteps…

>>> import matplotlib.pyplot as plt

>>> fig, ax = plt.subplots()
>>> ax.imshow(default_delta.bed_elevation, vmax=-3)
>>> plt.show()

(png, hires.png)

../_images/10min_demo.png

The model with set parameters

To run a simulation with a non-default set of parameters, we use a configuration file written in the YAML markup language named 10min_tutorial.yaml. The markup file allows us to specify model boundary conditions and input and output settings, where anything set in the file will override the default parameters for the model, and anything not specified will take the default value.

Important

The best practice for model configurations is to create a YAML file with only the settings you want to change specified.

The YAML configuration file is central to managing pyDeltaRCM simulations, so we did not create this file for you; you will need to create the YAML file yourself. To create the YAML file, open up your favorite plain-text editing application (e.g., gedit, notepad). YAML syntax is pretty simple for basic configurations, essentially amounting to each line representing a parameter-value pair, separated by a colon. For this example, let’s specify three simulation controls: where we want the output file to be placed via the out_dir parameter, we will ensure that our simulation is easily reproducible by setting the random seed parameter, and we can examine what is the effect of a high fraction of bedload with the f_bedload parameter. Enter the following in your text editor, and save the file as 10min_tutorial.yaml, making sure to place the file in a location accessible to your interpreter.

out_dir: '10min_tutorial'
seed: 451220118313
f_bedload: 0.9

Now, we can create a second instance of the DeltaModel(), this time using the input yaml file.

>>> second_delta = pyDeltaRCM.DeltaModel(input_file='10min_tutorial.yaml')

and repeat the same for loop operation as above:

>>> for _ in range(0, 5):
...     second_delta.update()

>>> second_delta.finalize()

Resources

Consider reading through the User Guide as a first action, and determine how to set up the model to complete your experiment, including tutorials and examples for customizing the model to achieve any arbitrary behavior you need!