init_tools

Todo

Add paragraph description of the module. What stages are defined here generally? Make a table with the main ones like in water tools?

Public API methods attached to model

The following methods are defined in the init_tools class, of the pyDeltaRCM.init_tools module.

init_tools()

class pyDeltaRCM.init_tools.init_tools

create_boundary_conditions()

Create model boundary conditions

This method is run during model initialization to determine the boundary conditions based on the initial conditions specified as model input.

However, the method also should be called when certain boundary condition variables are updated (e.g., during some custom model runs). For example, if some property of the inlet flow condition is changed, you will likely want to re-run this method (e.g., u0), because there are several other parameters that depend on the value of the inlet flow velocity (e.g., Qw0 and Qs0); of course, your scientific question may choose to leave these parameters as they are too (in which case you should not re-run this method). See Updating model boundary conditions for more information.

Note

This method is automatically called for the “named” variables used by the BMI wrapper (e.g., channel_flow_velocity, channel_width, channel_flow_depth, and influx_sediment_concentration., so you do not need to call it again if you modify the model boundary conditions that way.

create_domain()

Create the model domain.

This method initializes the model domain, including coordinate arrays, gridded fields (eta, qw, etc.) and cell type information. The method is called during initialization of the DeltaModel, and likely does not need to be called again.

Hint

If you need to modify the model domain after it has been created, it is probably safe to modify attributes directly, but take care to ensure any dependent fields are also approrpriately changed.

create_other_variables()

Model implementation variables.

Creates variables for model implementation, from specified boundary condition variables. This method is run during initial model instantition. Internally, this method calls set_constants and create_boundary_conditions.

Note

It is usually not necessary to re-run this method if you change boundary condition variables, and instead only re-run create_boundary_conditions.

determine_random_seed()

Set the random seed if given.

If a random seed is specified, set the seed to this value.

Writes the seed to the log for record.

import_files(kwargs_dict={})

Import the input files.

This method handles the parsing and validation of any options supplied via the configuration.

Parameters

kwargs_dict (dict, optional) – A dictionary with keys matching valid model parameter names that can be specified in a configuration YAML file. Keys given in this dictionary will supercede values specified in the YAML configuration.

init_logger()

Initialize a logger.

The logger is initialized regardless of the value of self.verbose. The level of information printed to the log depends on the verbosity setting.

init_metadata_list()

Populate the list of metadata information.

Sets up the dictionary object for the standard metadata.

init_output_file()

Creates a netCDF file to store output grids.

Fills with default variables.

Warning

Overwrites an existing netcdf file with the same name if clobber_netcdf is True.

init_output_infrastructure()

Initialize the output infrastructure (folder and save lists).

This method is the first called in the initialization of the DeltaModel, after the configuration variables have been imported.

init_sediment_routers()

Initialize the sediment router object here.

These are preinitialized because the “boxing” for jitted functions is expensive, so we avoid boxing up the constants on each iteration.

Important

If you change any model boundary conditions, you likely should reinitialize the sediment routers (i.e., rerun this method)

init_subsidence()

Initialize subsidence pattern.

Initializes patterns of subsidence if toggle_subsidence is True (default False). Default behavior is for the entire basin to subside at a constant rate (with the exception of the land boundary cells along the inlet boundary).

To customize the subsiding region, or even vary the subsiding region over the course of the model run, we recommend subclassing the DeltaModel class.

load_checkpoint(defer_output=False)

Load the checkpoint from the .npz file.

Uses the file at the path determined by self.prefix and a file named checkpoint.npz. There are a few pathways for loading, which depend on 1) the status of additional grid-saving options, 2) the presence of a netCDF output file at the expected output location, and 3) the status of the defer_output parameter passed to this method as an optional argument.

As a standard user, you should not need to worry about any of these pathways or options. However, if you are developing pyDeltaRCM or customizing the model in any way that involves loadind from checkpoints, you should be aware of these pathways.

For example, loading from checkpoint will succeed if no netCDF4 file is found, where one is expected (e.g., because _save_any_grids is True). In this case, a new output netcdf file will be created, after a UserWarning is issued.

Important

If you are customing the model and intend to use checkpointing and the Preprocessor parallel infrastructure, be sure that parameter defer_output is True until the load_checkpoint method can be called from the thread the model will execute on. Failure to do so may result in unexpected behavior with indexing in the output netCDF4 file.

Parameters

defer_output (bool, optional) – Whether to defer any netCDF activities at present. Manipulating this variable is critical for parallel operations. See note above. Default is False.

process_input_to_model()

Process input file to model variables.

Loop through the items specified in the model configuration and apply them to the model (i.e., self). Additionally, write the input values specified into the log file.

Note

If self.resume_checkpoint == True, then the input values are not written to the log.

set_constants()

Set the model constants.

Configure constants, including coordinates and distances, as well as environmental constants (gravity), and kernels for smoothing topography.