{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Coastline Evolution Model\n", "\n", "The Coastline Evolution Model (CEM) addresses predominately sandy, wave-dominated coastlines on time-scales ranging from years to millenia and on spatial scales ranging from kilometers to hundreds of kilometers. Shoreline evolution results from gradients in wave-driven alongshore sediment transport. \n", "At its most basic level, the model follows the standard 'one-line' modeling approach, where the cross-shore dimension is collapsed into a single data point. However, the model allows the planview shoreline to take on arbitrary local orientations, and even fold back upon itself, as complex shapes such as capes and spits form under some wave climates (distributions of wave influences from different approach angles). So the model works on a 2D grid.\n", "\n", "The model has been used to represent varying geology underlying a sandy coastline and shoreface in a simplified manner and enables the simulation of coastline evolution when sediment supply from an eroding shoreface may be constrained. CEM also supports the simulation of human manipulations to coastline evolution through beach nourishment or hard structures.\n", "\n", "CEM authors & developers: Andrew Ashton, Brad Murray, Jordan Slot, Jaap Nienhuis and others.\n", "\n", "This version is adapted from a CSDMS teaching notebook, listed below. \n", "It has been created by Irina Overeem, October 2019 for a Sedimentary Modeling course.\n", "\n", "* Link to this notebook: https://github.com/csdms/pymt/blob/master/notebooks/cem.ipynb\n", "* Install command: `$ conda install notebook pymt_cem`\n", "* Download local copy of notebook:\n", "\n", " `$ curl -O https://raw.githubusercontent.com/csdms/pymt/master/notebooks/cem.ipynb`\n", "\n", "### Key References\n", "\n", "Ashton, A.D., Murray, B., Arnault, O. 2001. Formation of coastline features by large-scale instabilities induced by high-angle waves, Nature 414.\n", "\n", "Ashton, A. D., and A. B. Murray (2006), High-angle wave instability and emergent shoreline shapes: 1. Modeling of sand waves, flying spits, and capes, J. Geophys. Res., 111, F04011, doi:10.1029/2005JF000422.\n", "\n", "\n", "### Links\n", "* [CEM source code](https://github.com/csdms/cem-old/tree/mcflugen/add-function-pointers): Look at the files that have *deltas* in their name.\n", "* [CEM description on CSDMS](http://csdms.colorado.edu/wiki/Model_help:CEM): Detailed information on the CEM model." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Interacting with the Coastline Evolution Model BMI using Python" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", "\n", "# Some magic that allows us to view images within the notebook.\n", "%matplotlib inline" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Import the `Cem` class. In Python, a model with a Basic Model Interface (BMI) will have no arguments for its constructor. Note that although the class has been instantiated, it's not yet ready to be run. We'll get to that later!" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import pymt.models\n", "\n", "cem = pymt.models.Cem()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Even though we can't run our waves model yet, we can still get some information about it. Some things we can do with our model are to get help, to get the names of the input variables or output variables." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "help(cem)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.input_var_names" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.output_var_names" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can also get information about specific variables. Here we'll look at some info about wave direction. This is the main input of the Cem model. Notice that BMI components always use [CSDMS standard names](http://csdms.colorado.edu/wiki/CSDMS_Standard_Names). The CSDMS Standard Name for wave angle is,\n", "\n", " \"sea_surface_water_wave__azimuth_angle_of_opposite_of_phase_velocity\"\n", "\n", "Quite a mouthful, I know. With that name we can get information about that variable and the grid that it is on (it's actually not a one)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "angle_name = \"sea_surface_water_wave__azimuth_angle_of_opposite_of_phase_velocity\"\n", "\n", "print(\"Data type: %s\" % cem.get_var_type(angle_name))\n", "print(\"Units: %s\" % cem.get_var_units(angle_name))\n", "print(\"Grid id: %d\" % cem.get_var_grid(angle_name))\n", "print(\"Number of elements in grid: %d\" % cem.get_grid_number_of_nodes(0))\n", "print(\"Type of grid: %s\" % cem.get_grid_type(0))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "First we initialize the model with the BMI **initialize** method. Normally we would pass it a string that represents the name of an input file. For this example we'll pass **None**, which tells Cem to use some defaults." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "args = cem.setup(number_of_rows=100, number_of_cols=200, grid_spacing=200.0)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.initialize(*args)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Before running the model, let's set a couple input parameters. These two parameters represent the wave height and wave period of the incoming waves to the coastline." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.set_value(\"sea_surface_water_wave__height\", 1.5)\n", "cem.set_value(\"sea_surface_water_wave__period\", 7.0)\n", "cem.set_value(\n", " \"sea_surface_water_wave__azimuth_angle_of_opposite_of_phase_velocity\",\n", " 0.0 * np.pi / 180.0,\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 1\n", "\n", "Let's think about the wave conditions that are the input to this CEM model run. For both assignment 1 and 2 it will help to look theory up in the paper by Ashton & Murray 2001, and/or Ashton et al, 2006.\n", "\n", "How do wave height and wave period determine sediment transport?\n", "The relationship between sediment transport and wave height and period is non-linear. What are the implications of this non-linearity for the impact of lots of small ocean storms versus a few extreme storms with much higher wave height?" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# list your answers here" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 2\n", "\n", "The other important part of the wave conditions that is input to CEM model is under what angle the waves approach the shore. It will help to read the paper by Ashton & Murray 2001, and the longer version by Ashton et al, 2006.\n", "Explain why incoming wave angle is an important control?\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# discuss wave angle here" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The CEM model operates on a grid, consisting of a number of rows and colums with values. \n", "The main output variable for this model is *water depth*, or bathymetry. In this case, the CSDMS Standard Name is much shorter:\n", "\n", " \"sea_water__depth\"\n", "\n", "First we find out which of Cem's grids contains water depth. " ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "grid_id = cem.get_var_grid(\"sea_water__depth\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With the *grid_id*, we can now get information about the grid. For instance, the number of dimension and the type of grid. This grid happens to be *uniform rectilinear*. If you were to look at the \"grid\" types for wave height and period, you would see that they aren't on grids at all but instead are scalars, or single values." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "grid_type = cem.get_grid_type(grid_id)\n", "grid_rank = cem.get_grid_ndim(grid_id)\n", "print(\"Type of grid: %s (%dD)\" % (grid_type, grid_rank))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Because this grid is uniform rectilinear, it is described by a set of BMI methods that are only available for grids of this type. These methods include:\n", "* get_grid_shape\n", "* get_grid_spacing\n", "* get_grid_origin" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "spacing = np.empty((grid_rank,), dtype=float)\n", "\n", "shape = cem.get_grid_shape(grid_id)\n", "cem.get_grid_spacing(grid_id, out=spacing)\n", "\n", "print(\"The grid has %d rows and %d columns\" % (shape[0], shape[1]))\n", "print(\n", " \"The spacing between rows is {:f} m and between columns is {:f} m\".format(\n", " spacing[0], spacing[1]\n", " )\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Allocate memory for the water depth grid and get the current values from `cem`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "z = np.empty(shape, dtype=float)\n", "cem.get_value(\"sea_water__depth\", out=z)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here I define a convenience function for plotting the water depth and making it look pretty. You don't need to worry too much about it's internals for this tutorial. It just saves us some typing later on." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "def plot_coast(spacing, z):\n", " import matplotlib.pyplot as plt\n", "\n", " xmin, xmax = 0.0, z.shape[1] * spacing[0] * 1e-3\n", " ymin, ymax = 0.0, z.shape[0] * spacing[1] * 1e-3\n", "\n", " plt.imshow(z, extent=[xmin, xmax, ymin, ymax], origin=\"lower\", cmap=\"ocean\")\n", " plt.colorbar().ax.set_ylabel(\"Water Depth (m)\")\n", " plt.xlabel(\"Along shore (km)\")\n", " plt.ylabel(\"Cross shore (km)\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "It generates plots that look like this. We begin with a flat delta (green) and a linear coastline (y = 3 km). The bathymetry drops off linearly to the top of the domain to more than 20 m water depth." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plot_coast(spacing, z)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Right now we have waves coming in but no sediment entering the ocean. To add a sediment source and specify its discharge, we need to figure out where to put it. For now we'll put it on a cell that's next to the ocean." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Allocate memory for the sediment discharge array\n", "# and set the bedload sediment flux at the coastal cell to some value.\n", "qs = np.zeros_like(z)\n", "qs[0, 100] = 750" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The CSDMS Standard Name for this variable is:\n", "\n", " \"land_surface_water_sediment~bedload__mass_flow_rate\"\n", "\n", "You can get an idea of the units based on the quantity part of the name. \"mass_flow_rate\" indicates mass per time. You can double-check this with the BMI method function **get_var_units**." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.get_var_units(\"land_surface_water_sediment~bedload__mass_flow_rate\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 3" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here, we are introducing a river mouth of one gridcell of 200 by 200m. And we just have specified a bedload flux of 750 kg/s. Is this a realistic incoming value?\n", "How much water discharge and slope would you possibly need to transport a bedload flux of that magnitude? " ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# read in the csv file of bedload measurements in the Rhine River, the Netherlands\n", "# these data were collected over different days over a season in 2004, at nearby locations.\n", "# plot how river discharge controls bedload; Q (x-axis) and Qb (y-axis) data.\n", "# label both axes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 4" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The bedload measurements were a combination of very different methods, and taken at different locations (although nearby). The data is quite scattered. But if you would fit a linear regression line through this data,\n", "you would find that the river discharge of the Rhine can be related to its bedload transport as: \n", " Qb=0.0163*Q" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# extrapolate this relationship and calculate how much river discharge, Q,\n", "# would be needed to transport the model specification Qb of 1250 kg/s" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.time_step, cem.time_units, cem.time" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Set the bedload flux and run the model." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "for time in range(3000):\n", " cem.set_value(\"land_surface_water_sediment~bedload__mass_flow_rate\", qs)\n", " cem.update_until(time)\n", "\n", "cem.get_value(\"sea_water__depth\", out=z)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.time" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cem.get_value(\"sea_water__depth\", out=z)\n", "plot_coast(spacing, z)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# this code gives you a handle on retrieving the position of the river mouth over time\n", "val = np.empty((5,), dtype=float)\n", "cem.get_value(\"basin_outlet~coastal_center__x_coordinate\", val)\n", "val / 100.0" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(val)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 5\n", "\n", "Describe what the CEM model has simulated in 3000 timesteps. How far has this wave influenced delta prograded? \n", "Recall the R-factor for fluvial dominance (Nienhuis 2015). What would the R-factor be for this simulated system? (smaller then 1, larger then 1)? Motivate." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# your run description goes here" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 6\n", "\n", "Let's add another sediment source with a different flux and update the model. remember that the Basic Model Interface allows you to update values and then continue a simulation" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# introduce a second river here\n", "qs[0, 150] = 1500\n", "for time in range(4000):\n", " cem.set_value(\"land_surface_water_sediment~bedload__mass_flow_rate\", qs)\n", " cem.update_until(time)\n", "\n", "cem.get_value(\"sea_water__depth\", out=z)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plot_coast(spacing, z)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here we shut off the sediment supply completely." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "qs.fill(0.0)\n", "for time in range(4500):\n", " cem.set_value(\"land_surface_water_sediment~bedload__mass_flow_rate\", qs)\n", " cem.update_until(time)\n", "\n", "cem.get_value(\"sea_water__depth\", out=z)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plot_coast(spacing, z)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 7\n", "Create a new CEM run (remember to create a new cem instance) with a more subdued river influx and higher waves. \n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import pymt.models\n", "\n", "cemLR = pymt.models.Cem()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "args = cemLR.setup(number_of_rows=100, number_of_cols=200, grid_spacing=200.0)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cemLR.initialize(*args)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Here you will have to change the settings to a different wave climate\n", "cemLR.set_value(\"sea_surface_water_wave__height\", 1.5)\n", "cemLR.set_value(\"sea_surface_water_wave__period\", 7.0)\n", "cemLR.set_value(\n", " \"sea_surface_water_wave__azimuth_angle_of_opposite_of_phase_velocity\",\n", " 0.0 * np.pi / 180.0,\n", ")" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "zLR = np.empty(shape, dtype=float)\n", "cemLR.get_value(\"sea_water__depth\", out=zLR)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# set your smaller river input here" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Assignment 8" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# run your new simulation for a similar time as the other first simulation\n", "qsLR = np.zeros_like(z)\n", "\n", "for time in range(3000):\n", " cemLR.set_value(\"land_surface_water_sediment~bedload__mass_flow_rate\", qsLR)\n", " cemLR.update_until(time)\n", "\n", "cemLR.get_value(\"sea_water__depth\", out=zLR)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# hypothesize how your run output would be different" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# plot the sea water depth\n", "# save out this figure" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## BONUS Assignment 9 - for graduate students\n", "Create a new CEM run (remember to create a new cem instance) that is all similar to your first simulation. \n", "In this experiment we will use a different incoming wave angle, and look at its effect without a river input first, 1000 timesteps and then with a river input for another 2000 timsteps." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# initialize CEM instance" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# set the wave angle" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# run for 1000 timesteps" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# plot intermediate output" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# save out an array of this sea water depth at t=1000" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# describe what effect you see. Is it to be expected?\n", "# What is the unique theory in the CEM model that drives this behavior?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## BONUS Assignment 9 - for graduate students\n", "Use the same CEM run that you have just started. \n", "Keep the incoming wave angle you had specified, and now run the rest of the simulation with a new river input for another 2000 timsteps. 'Place' the rivermouth out of center in the grid (although not too close to the grid boundary, that can give instability problems)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# your code to introduce new river input goes here" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# run an additional 2000 timesteps" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# plot" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# describe what effect you see. Is it to be expected?\n", "# Is this a fluvial-dominated delta or a wave-dominated delta?\n", "# Is the delta assymetric?" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# save out the array of your final sea water depth\n", "# calculate the deposition and erosion per gridcell between t=1000 and t=3000" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## NICELY DONE! " ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.12" } }, "nbformat": 4, "nbformat_minor": 2 }