init_tools

The model initialization is managed by __init__, but the actual initialization is mostly handled by routines in init_tools. The major steps of initialization are:

init_tools.import_files([kwargs_dict])	Import the input files.
init_tools.init_logger()	Initialize a logger.
init_tools.process_input_to_model()	Process input file to model variables.
init_tools.determine_random_seed()	Set the random seed if given.
init_tools.create_other_variables()	Model implementation variables.
init_tools.create_domain()	Create the model domain.
init_tools.init_sediment_routers()	Initialize the sediment router object here.
init_tools.init_subsidence()	Initialize subsidence pattern.

and then depending on the checkpointing configuration, the following methods may be called:

init_tools.load_checkpoint([defer_output])	Load the checkpoint from the .npz file.
init_tools.init_output_file()	Creates a netCDF file to store output grids.
pyDeltaRCM.iteration_tools.iteration_tools.output_data()	Output grids and figures if needed.
pyDeltaRCM.iteration_tools.iteration_tools.output_checkpoint()	Output checkpoint if needed.
pyDeltaRCM.iteration_tools.iteration_tools.log_model_time()	Log the time of the model.

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

_load_past_etas(checkpoint)

Handler for new fields in checkpoint file.

This function was added to allow for old checkpoint files to be loaded without breaking the checkpoint functionality. If the fields are not found a warning is raised, and an array of nan is returned.

The two fields added in version 2.1.5 are eta0 and eta_init.

NOTE: This function and warnings will be removed in a future version.

create_boundary_conditions() → None

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() → None

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 appropriately changed.

create_other_variables() → None

Model implementation variables.

Creates variables for model implementation, from specified boundary condition variables. This method is run during initial model instantiation. 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() → None

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={}) → None

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() → None

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() → None

Populate the list of metadata information.

Sets up the dictionary object for the standard metadata.

init_output_file() → None

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() → None

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() → None

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() → None

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: bool = False) → None

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 loading 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 customizing 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() → None

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() → None

Set the model constants.

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

Some of the constants defined herein:

• self.g, gravitational acceleration

• self.distances, distance from cell i,j to neighbors (and self) # noqa: E501

• self.iwalk, step distance cross domain to cell in indexed direction

• self.jwalk, step distance down domain to cell in indexed direction

• self.ravel_walk, flattened index distance to cell in indexed direction

Each of these attributes also has a self.xxxxx_flat sibling attribute, which is simply the flattened version of that attribute.