pyDeltaRCM.model.DeltaModel

class pyDeltaRCM.model.DeltaModel(input_file=None, defer_output=False, **kwargs)

Main model class.

Instantiating the model class is described in the __init__() method below in detail, but generally model instantiation occurs via a model run YAML configuration file. These YAML configuration files define model parameters which are used in the run; read more about creating input YAML configuration files in the User Guide.

Once the model has been instantiated, the model is updated via the update(). This method coordinates the hydrology, sediment transport, subsidence, and stratigraphic operation that must occur during each timestep. The update() should be called iteratively, to “run” the model.

Finally, after all update steps are complete, the model should be finalized (finalize()), such that files and data are appropriately closed and written to disk.

__init__(input_file=None, defer_output=False, **kwargs)

Creates an instance of the pyDeltaRCM model.

This method handles setting up the run, including parsing input files, initializing arrays, and initializing output routines.

Parameters
  • input_file (str, os.PathLike, optional) – User model run configuration file.

  • defer_output (bool, optional) – Whether to create the output netCDF file during initialization. In most cases, this can be ignored and left to default value False. However, for parallel simulations it may be necessary to defer the NetCDF file creation unitl the simualtion is assigned to the core it will compute on, so that the DeltaModel object remains pickle-able. Note, you will need to manually trigger the init_output_file, output_data, and output_checkpoint method if defer_output is True.

  • **kwargs – Optionally, any parameter typically specified in the YAML file can be passed as a keyword argument to the instantiation of the DeltaModel. Keywords will override the specification of any value in the YAML file. This functionality is intended for advanced use cases, and should not be preffered to specifying all inputs in a YAML configuration file.

Notes

For more information regarding input configuration files, see the User Guide.

Methods

__init__([input_file, defer_output])

Creates an instance of the pyDeltaRCM model.

apply_subsidence()

Apply subsidence pattern.

build_weight_array(array[, fix_edges, normalize])

Weighting array of neighbors.

check_for_boundary(inds)

Check whether parcels have reached the boundary.

check_size_of_indices_matrix(it)

Check if step path matrix needs to be made larger.

compute_free_surface()

Calculate free surface after routing all water parcels.

compute_sand_frac()

Compute the sand fraction as a continous updating data field.

create_boundary_conditions()

Create model boundary conditions

create_domain()

Create the model domain.

create_other_variables()

Model implementation variables.

determine_random_seed()

Set the random seed if given.

finalize()

Finalize the model run.

finalize_free_surface()

Finalize the water free surface.

finalize_timestep()

Finalize timestep.

finalize_water_iteration(iteration)

Finish updating flow fields.

flooding_correction()

Flood dry cells along the shore if necessary.

get_water_weight_array()

Get step direction weights for each cell.

get_wet_mask_nh()

Get wet mask.

hook_apply_subsidence()

Hook apply_subsidence.

hook_compute_free_surface()

Hook compute_free_surface.

hook_compute_sand_frac()

Hook compute_sand_frac.

hook_create_domain()

Hook create_domain.

hook_create_other_variables()

Hook create_other_variables.

hook_finalize_timestep()

Hook finalize_timestep.

hook_finalize_water_iteration(iteration)

Hook finalize_water_iteration.

hook_import_files()

Hook import_files.

hook_init_output_file()

Hook init_output_file.

hook_init_sediment_iteration()

Hook init_sediment_iteration.

hook_init_water_iteration()

Hook init_water_iteration.

hook_load_checkpoint()

Hook load_checkpoint.

hook_output_checkpoint()

Hook output_checkpoint.

hook_output_data()

Hook output_data.

hook_process_input_to_model()

Hook process_input_to_model.

hook_route_all_mud_parcels()

Hook route_all_mud_parcels.

hook_route_all_sand_parcels()

Hook route_all_sand_parcels.

hook_route_sediment()

Hook route_sediment.

hook_route_water()

Hook route_water.

hook_run_water_iteration()

Hook run_water_iteration.

hook_solve_water_and_sediment_timestep()

Hook solve_water_and_sediment_timestep.

hook_topo_diffusion()

Hook topo_diffusion.

import_files([kwargs_dict])

Import the input files.

init_logger()

Initialize a logger.

init_metadata_list()

Populate the list of metadata information.

init_output_file()

Creates a netCDF file to store output grids.

init_output_infrastructure()

Initialize the output infrastructure (folder and save lists).

init_sediment_iteration()

Init the water iteration routine.

init_sediment_routers()

Initialize the sediment router object here.

init_subsidence()

Initialize subsidence pattern.

init_water_iteration()

Init the water iteration routine.

load_checkpoint([defer_output])

Load the checkpoint from the .npz file.

log_info(message[, verbosity])

Log message dependent on verbosity settings.

log_model_time()

Log the time of the model.

make_figure(var, timestep)

Create a figure.

output_checkpoint()

Output checkpoint if needed.

output_data()

Output grids and figures if needed.

process_input_to_model()

Process input file to model variables.

route_all_mud_parcels()

Route mud parcels.

route_all_sand_parcels()

Route sand parcels; topo diffusion.

route_sediment()

Sediment routing main method.

route_water()

Water routing main method.

run_one_timestep()

Deprecated, since v1.3.1.

run_water_iteration()

Run a single iteration of travel paths for all water parcels.

save_figure(fig, directory, filename_root, …)

Save a figure.

save_grids(var_name, var, ts)

Save a grid into an existing netCDF file.

save_grids_and_figs()

Save grids and figures.

save_the_checkpoint()

Save checkpoint files.

sed_route()

Deprecated, since v1.3.1.

set_constants()

Set the model constants.

show_attribute(attribute, **kwargs)

Show an attribute over the model domain.

show_ind(ind, *args, **kwargs)

Show points within the model domain.

show_line(ind, *args[, multiline, nozeros])

Show line within the model domain.

solve_water_and_sediment_timestep()

Run water and sediment operations for one timestep.

topo_diffusion()

Diffuse topography after routing.

update()

Run the model for one full timestep.

update_Q(dist, current_inds, next_inds, …)

Update discharge field values.

update_flow_field(iteration)

Update water discharge.

update_velocity_field()

Update flow velocity fields.

Attributes

C0_percent

C0_percent is the sediment concentration in the input water supply.

Csmooth

Csmooth is a free surface smoothing parameter.

H_SL

H_SL sets the sea level elevation in meters.

If

Intermittency factor converting model time to real-world time.

L0_meters

L0_meters defines the thickness of the land along the coast.

Length

Length sets the total length of the domain.

N0_meters

N0_meters defines the width of the inlet channel in meters.

Np_sed

Np_sed is the number of sediment parcels simulated.

Np_water

Np_water is the number of water parcels simulated.

Nsmooth

Nsmooth defines the number of times the water surface is smoothed.

S0

S0 is the characteristic slope for the delta.

SLR

SLR is the sea level rise rate.

Width

Width sets the total width of the domain.

active_layer_thickness

Active layer thickness for sand fraction.

alpha

alpha is the topographic diffusion coefficient.

bed_elevation

Get bed elevation.

bedload_fraction

Get bedload fraction.

beta

beta is the bedload transport capacity exponent.

channel_flow_depth

Get channel flow depth.

channel_flow_velocity

Get channel flow velocity.

channel_width

Get channel width.

checkpoint_dt

checkpoint_dt defines the interval to create checkpoint information.

clobber_netcdf

Allows overwriting (clobbering) of an existing netCDF output file.

coeff_U_dep_mud

coeff_U_dep_mud is the threshold velocity for mud sediment deposition.

coeff_U_ero_mud

coeff_U_ero_mud is the mud erosion velocity threshold coefficient.

coeff_U_ero_sand

coeff_U_ero_sand is the sand erosion velocity threshold coefficient.

coeff_theta_mud

coeff_theta_mud is the coefficient applied to theta for mud routing.

coeff_theta_sand

coeff_theta_sand is the coefficient applied to theta for sand routing.

dt

The time step.

dx

dx is the length of the individual cell faces.

f_bedload

f_bedload is the bedload fraction of the input sediment.

h0

h0 is the reference or characteristic water depth in meters.

hb

hb is the basin depth in meters.

influx_sediment_concentration

Get influx sediment concentration.

itermax

itermax sets the number of flow routing/free surface iterations.

omega_flow

omega_flow is a flow velocity underrelaxation parameter.

omega_sfc

omega_sfc is a water surface underrelaxation parameter.

out_dir

out_dir sets the output directory for the simulation results.

resume_checkpoint

resume_checkpoint controls loading of a checkpoint if run is resuming.

sand_frac_bc

Sand fraction boundary condition.

save_checkpoint

save_checkpoint controls saving of model checkpoint information.

save_depth_figs

save_depth_figs controls saving of water depth figures.

save_depth_grids

save_depth_grids controls whether or not depth information is saved.

save_discharge_components

save_discharge_components controls saving of x-y discharge components.

save_discharge_figs

save_discharge_figs controls saving of water discharge figures.

save_discharge_grids

save_discharge_grids controls saving of water discharge information.

save_dt

save_dt defines the saving interval in seconds.

save_eta_figs

save_eta_figs controls whether or not figures of topography are saved.

save_eta_grids

save_eta_grids controls whether or not topography information is saved.

save_figs_sequential

save_figs_sequential sets how figures are to be saved.

save_iter

Number of times data has been saved.

save_metadata

save_metadata explicit control on whether or not metadata is saved.

save_sandfrac_figs

save_sandfrac_figs controls whether or not figures of the sediment surface (i.e., the bed) sand fraction are saved.

save_sandfrac_grids

save_sandfrac_grids controls whether or not the sediment surface (i.e., the bed) sand fraction is saved.

save_sedflux_figs

save_sedflux_figs controls saving of sediment flux figures.

save_sedflux_grids

save_sedflux_grids controls saving of sediment discharge information.

save_stage_figs

save_stage_figs controls whether or not stage figures are saved.

save_stage_grids

save_stage_grids controls whether or not stage information is saved.

save_time_since_checkpoint

Time since last data checkpoint was saved.

save_time_since_data

Time since data last output.

save_velocity_components

save_velocity_components controls saving of x-y velocity components.

save_velocity_figs

save_velocity_figs controls saving of water velocity figures.

save_velocity_grids

save_velocity_grids controls saving of water velocity information.

sea_surface_elevation

Get stage.

sea_surface_elevation_change

Get rate of change of sea surface elevation, per timestep.

sea_surface_mean_elevation

Get sea surface mean elevation.

sed_lag

sed_lag is a “sedimentation lag” parameter.

seed

seed defines the random number seed used for the simulation.

start_subsidence

start_subsidence defines the start time at which subsidence begins.

stepmax

stepmax is the maximum number of jumps a parcel can make.

subsidence_rate

subsidence_rate defines the maximum rate of subsidence.

theta_water

theta_water is the exponent of depth dependence for weighted routing.

time

Elapsed model time in seconds.

time_iter

Number of time iterations.

time_step

Alias for dt.

toggle_subsidence

toggle_subsidence controls whether subsidence is turned on or off.

u0

u0 is a reference velocity value.

verbose

verbose controls the degree of information printed to the log.

water_depth

Get depth.

property C0_percent

C0_percent is the sediment concentration in the input water supply.

C0_percent is the prescribed sediment concentration in the input water as a percentage (must be equal to or greater than 0).

property Csmooth

Csmooth is a free surface smoothing parameter.

property H_SL

H_SL sets the sea level elevation in meters.

property If

Intermittency factor converting model time to real-world time.

Important

This parameter has no effect on model operations. It is used in determining model run duration.

property L0_meters

L0_meters defines the thickness of the land along the coast.

L0 meters is either an integer or a float. Thickness of the land adjacent to the inlet in meters. This can also be thought of as the length of the inlet channel.

property Length

Length sets the total length of the domain.

Length is either an integer or a float. This is the length of the domain (dimension parallel to the inlet channel), in meters.

property N0_meters

N0_meters defines the width of the inlet channel in meters.

N0_meters defines the width of the inlet channel in meters. Therefore, this parameter must be a positive integer or float.

property Np_sed

Np_sed is the number of sediment parcels simulated.

Np_sed represents the number of “parcels” to split the input sediment discharge into for the reduced-complexity sediment routing. This parameter must be an integer

property Np_water

Np_water is the number of water parcels simulated.

Np_water represents the number of “parcels” to split the input water discharge into for the reduced-complexity flow routing. This parameter must be an integer

property Nsmooth

Nsmooth defines the number of times the water surface is smoothed.

property S0

S0 is the characteristic slope for the delta.

S0 is either an integer or a float. This sets the characteristic slope for the delta topset. This parameter is dimensionless.

property SLR

SLR is the sea level rise rate.

SLR is a parameter for defining the sea level rise rate. SLR is specified in units of m/s. When prescribing a SLR rate, it is important to remember that pyDeltaRCM simulates bankfull discharge conditions. Depending on the flood intermittancy intervals you assume, the conversion from “model time” into “real time simulated” may vary.

property Width

Width sets the total width of the domain.

Width is either an integer or a float. This is the width of the domain (dimension perpendicular to the inlet channel), in meters.

property active_layer_thickness

Active layer thickness for sand fraction.

The active layer thickness is the depth to which the sand fraction values are maintained in the event of erosion from one timestep to the next. When erosion exceeds the depth of the active layer, the boundary condition is to fill that cell with a value of 0 (maybe this should be -1 so that it is clear which cells are not truly mud but unknown sediment content based on the active layer thickness?)

property alpha

alpha is the topographic diffusion coefficient.

alpha is the coefficient used for topographic diffusion. It controls both the cross-slope sediment flux as well as bank erodability.

property bed_elevation

Get bed elevation.

property bedload_fraction

Get bedload fraction.

property beta

beta is the bedload transport capacity exponent.

beta is an exponent on the bedload transport terms that is applied to the local velocity and threshold velocity terms.

property channel_flow_depth

Get channel flow depth.

property channel_flow_velocity

Get channel flow velocity.

property channel_width

Get channel width.

property checkpoint_dt

checkpoint_dt defines the interval to create checkpoint information.

property clobber_netcdf

Allows overwriting (clobbering) of an existing netCDF output file.

Default behavior, clobber_netcdf: False, is for the model to raise an error during initialization if a netCDF output file is found in the location specified by out_dir. If the clobber_netcdf parameter is instead set to True, then if there is an existing netCDF output file in the target folder, it will be “clobbered” or overwritten.

property coeff_U_dep_mud

coeff_U_dep_mud is the threshold velocity for mud sediment deposition.

coeff_U_dep_mud sets the threshold velocity for mud to be depoisted. The smaller this parameter is, the longer a mud parcel can travel before losing all of its mud volume.

property coeff_U_ero_mud

coeff_U_ero_mud is the mud erosion velocity threshold coefficient.

coeff_U_ero_mud sets the threshold velocity for erosion of the mud (suspended load) sediment. The higher this value is, the more difficult it is to erode mud deposits.

property coeff_U_ero_sand

coeff_U_ero_sand is the sand erosion velocity threshold coefficient.

coeff_U_ero_sand sets the threshold velocity for sediment erosion of the sand (bedload) sediment. The higher this value is, the more difficult it is to erode the bed.

property coeff_theta_mud

coeff_theta_mud is the coefficient applied to theta for mud routing.

coeff_theta_mud is a coefficient applied to the theta_water attribute to define the value of theta for mud routing. Theta is the exponent applied to the local water depth and is used to weight the random walk. For mud and sand these weighting rules vary, which is why the theta_water term is multiplied by these coefficients: coeff_theta_mud and coeff_theta_sand.

property coeff_theta_sand

coeff_theta_sand is the coefficient applied to theta for sand routing.

coeff_theta_sand is a coefficient applied to the theta_water attribute to define the value of theta for sand routing. Theta is the exponent applied to the local water depth and is used to weight the random walk. For mud and sand these weighting rules vary, which is why the theta_water term is multiplied by these coefficients: coeff_theta_mud and coeff_theta_sand.

property dt

The time step.

The value of the timestep (\Delta t) is a balance between computation efficiency and model stability 1. The Reference Volume, which characterizes the volume of an inlet-channel cell, and the sediment discharge to the model domain scale the timestep as:

\Delta t = \dfrac{0.1 {N_0}^2 V_0}{Q_{s0}}

where Q_{s0} is the sediment discharge into the model domain (m:sup:3/s), V_0 is the reference volume, and N_0 is the number of cells across the channel (determined by N0_meters and dx).

1

A reduced-complexity model for river delta formation – Part 1: Modeling deltas with channel dynamics, M. Liang, V. R. Voller, and C. Paola, Earth Surf. Dynam., 3, 67–86, 2015. https://doi.org/10.5194/esurf-3-67-2015

Raises

UserWarning – If a very small timestep is configured.

property dx

dx is the length of the individual cell faces.

dx is either an integer or a float. This parameter specifies the length of the cell faces in the grid in meters.

property f_bedload

f_bedload is the bedload fraction of the input sediment.

f_bedload is the fraction of input sediment that is bedload material. In pyDeltaRCM, bedload material is coarse grained “sand”, and suspended load material is fine grained “mud”. This parameter must be a value between 0 and 1, inclusive.

finalize()

Finalize the model run.

Finalization includes saving output stratigraphy, closing relevant files on disk and clearing variables.

property h0

h0 is the reference or characteristic water depth in meters.

h0 is the reference or characteristic water depth in meters. This parameter must be an integer or float. h0 defines the depth of water in the inlet channel. One-tenth of the value of h0 defines the “dry-depth” or the depth at which cells are considered to be non-wet (dry).

property hb

hb is the basin depth in meters.

hb is the basin depth in meters. This parameter must be an integer or float, or None. If no value is supplied for this parameter, then the value of h0 is used to determine the basin depth (i.e., they are the same).

property influx_sediment_concentration

Get influx sediment concentration.

property itermax

itermax sets the number of flow routing/free surface iterations.

property omega_flow

omega_flow is a flow velocity underrelaxation parameter.

property omega_sfc

omega_sfc is a water surface underrelaxation parameter.

property out_dir

out_dir sets the output directory for the simulation results.

out_dir is a string type parameter, specifying the name of the output directory in which the model outputs should be saved.

property resume_checkpoint

resume_checkpoint controls loading of a checkpoint if run is resuming.

When setting this option in the YAML or command line, you can specify a bool (e.g., resume_checkpoint: True) which will search in the out_dir directory for a file named checkpoint.npz. Alternatively, you can specify an alternative folder to search for the checkpoint as a string (e.g., resume_checkpoint: ‘/some/other/path’).

property sand_frac_bc

Sand fraction boundary condition.

property save_checkpoint

save_checkpoint controls saving of model checkpoint information.

property save_depth_figs

save_depth_figs controls saving of water depth figures.

property save_depth_grids

save_depth_grids controls whether or not depth information is saved.

property save_discharge_components

save_discharge_components controls saving of x-y discharge components.

property save_discharge_figs

save_discharge_figs controls saving of water discharge figures.

property save_discharge_grids

save_discharge_grids controls saving of water discharge information.

property save_dt

save_dt defines the saving interval in seconds.

property save_eta_figs

save_eta_figs controls whether or not figures of topography are saved.

property save_eta_grids

save_eta_grids controls whether or not topography information is saved.

property save_figs_sequential

save_figs_sequential sets how figures are to be saved.

save_figs_sequential is a boolean parameter that can be set to True or False. If True, then for each figure saving parameter set to True (e.g. save_velocity_figs) a new figure will be saved at an inteval of save_dt. The file names of the figures will correspond to the model timestep at which they were saved. If instead, the save_figs_sequential parameter is set to False, then only the latest figure will be kept, and at each save_dt time, the figure file will be overwritten using the current model status.

property save_iter

Number of times data has been saved.

property save_metadata

save_metadata explicit control on whether or not metadata is saved.

save_metadata is a boolean that can be manually togged on (True) to ensure metadata is saved to disk even if no other output information is being saved. If any grids or strata are being saved, then metadata saving will be turned on automatically, even if this parameter is set to False. Metadata associated with pyDeltaRCM are 1-D arrays (vectors) and 0-D arrays (floats and integers) primarily containing information about the domain and the inlet conditions for a given model run.

property save_sandfrac_figs

save_sandfrac_figs controls whether or not figures of the sediment surface (i.e., the bed) sand fraction are saved.

property save_sandfrac_grids

save_sandfrac_grids controls whether or not the sediment surface (i.e., the bed) sand fraction is saved.

property save_sedflux_figs

save_sedflux_figs controls saving of sediment flux figures.

property save_sedflux_grids

save_sedflux_grids controls saving of sediment discharge information.

property save_stage_figs

save_stage_figs controls whether or not stage figures are saved.

property save_stage_grids

save_stage_grids controls whether or not stage information is saved.

property save_time_since_checkpoint

Time since last data checkpoint was saved.

property save_time_since_data

Time since data last output.

The elapsed time (seconds) since data was output with output_data.

property save_velocity_components

save_velocity_components controls saving of x-y velocity components.

property save_velocity_figs

save_velocity_figs controls saving of water velocity figures.

property save_velocity_grids

save_velocity_grids controls saving of water velocity information.

property sea_surface_elevation

Get stage.

property sea_surface_elevation_change

Get rate of change of sea surface elevation, per timestep.

property sea_surface_mean_elevation

Get sea surface mean elevation.

property sed_lag

sed_lag is a “sedimentation lag” parameter.

sed_lag influences the properties of mud deposition by controlling how much mud is deposited when the flow velocity is below the threshold for mud deposition (coeff_U_dep_mud).

property seed

seed defines the random number seed used for the simulation.

seed is an integer type parameter specifying the random seed value to be used for this model run. If unspecified, a random seed is generated and used.

property start_subsidence

start_subsidence defines the start time at which subsidence begins.

property stepmax

stepmax is the maximum number of jumps a parcel can make.

stepmax is the maximum number of jumps a parcel (water or sediment) can make. If the parcel reaches the oceanic boundary before stepmax is reached, then this condition is not invoked. However if the parcel does not reach the oceaninc bounary but does reach “stepmax” jumps, then the parcel will just stop moving and disappear.

If stepmax is not specified in the yaml, the default value assigned is 2 times the perimeter of the domain (2 * (self.L + self.W)).

Note

If stepmax is set too low and many parcels reach the stepmax condition during routing, then there may be a considerable amount of sediment ‘missing’ from the system as any sediment in a parcel that hits the stepmax threshold disappears from the simulation.

property subsidence_rate

subsidence_rate defines the maximum rate of subsidence.

property theta_water

theta_water is the exponent of depth dependence for weighted routing.

For the routing of the water parcels, the dependence of the random walk on local water depth can be modulated by varying this parameter value. As theta_water gets larger, the importance of the water depth to the weighting scheme grows.

Note

The value of theta_water also influences the values of coeff_theta_sand and coeff_theta_mud which are coefficients that are multiplied by theta_water to set the theta values for the sand and mud routing respectively.

property time

Elapsed model time in seconds.

property time_iter

Number of time iterations.

The number of times the update method has been called.

property time_step

Alias for dt.

property toggle_subsidence

toggle_subsidence controls whether subsidence is turned on or off.

If toggle_subsidence is set to True then subsidence is turned on. Otherwise if toggle_subsidence is set to False (the default) then no subsidence will occur.

property u0

u0 is a reference velocity value.

u0 is the characteristic or reference velocity value in units of m/s. u0 influences the values of other model parameters such as the maximum flow velocity, gamma, and the velocities at which sediments deposit and erode. This parameter must be an integer or a float.

update()

Run the model for one full timestep.

This method handles the input/output from the model, orchestrating the various morphodynamic and basin-scale processes (from sub-methods), and incrementing the model time-tracking attributes. This method calls, in sequence:

If you attempt to override the update routine, you must implement these operations at a minimum. More likely, you can implement what you need to by utilizing a model hook, or overriding one of the methods called by update. For more information on customizing the model, see the complete guide.

Raises

RuntimeError – If model has already been finalized via finalize().

property verbose

verbose controls the degree of information printed to the log.

verbose is an integer type parameter, which controls the verbosity of the information saved in the log file. A value of 0, the default, is the least informative. A value of 1 saves and prints a bit of information, and a value of 2 increases the verbosity further.

property water_depth

Get depth.