subsettools.parflow_run

Functions to get and customize a ParFlow runscript.

Functions

get_template_runscript(grid, mode, input_file_type, ...)

Get a ParFlow template runscript.

edit_runscript_for_subset(ij_bounds, runscript_path[, ...])

Modify a ParFlow run script for a new subdomain run.

copy_files(read_dir, write_dir)

Copy all files from read_dir to write_dir.

change_filename_values(runscript_path[, write_dir, ...])

Change the filenames of input files in the ParFlow runscript.

dist_run(topo_p, topo_q, runscript_path[, ...])

Distribute ParFlow input files for parallel computing.
subsettools.parflow_run.get_template_runscript(grid, mode, input_file_type, write_dir)[source]

Get a ParFlow template runscript.

The runscript is selected based on the grid, mode and input file type and is copied to write_dir.

Parameters:

  • grid (str) – The spatial grid that the ij indices are calculated relative to and that the subset data will be returned on. Possible values: “conus1” or “conus2”

  • mode (str) – The type of simulation you would like to do. Possible values: “spinup” (run ParFlow with a constant recharge forcing at the upper boundary) and “transient” (coupled ParFlow-CLM run)

  • input_file_type (str) – The type of domain you will run. Possible values: “box” or “solid”

  • write_dir (str) – directory where the template runscript file will be copied

Returns:

A path to the template runscript.

Example:

runscript_path = get_template_runscript(
    grid="conus1",
    mode="spinup",
    input_file_type="solid",
    write_dir="/path/to/your/chosen/directory"
)
subsettools.parflow_run.edit_runscript_for_subset(ij_bounds, runscript_path, write_dir=None, runname=None, forcing_dir=None)[source]

Modify a ParFlow run script for a new subdomain run.

This function is designed to start from a national ParFlow runscript template and perform the following three modifications.

  1. Modify the geometry to reflect the bounds of the desired ij_bounds (i.e. the number of grid cells in the x and y direction and the upper bounds of the geometry)

  2. Update the runname to for the desired new run.

  3. Update the location of the climate forcings for the new run.

If the runname is None and write_dir is the directory containing the runscript file, the runscript file will be overwritten.

Parameters:

  • ij_bounds (tuple[int]) – bounding box for subset. This should be given as i,j index values where 0,0 is the lower left hand corner of a domain. ij_bounds are given relative to whatever grid is being used for the subset.

  • runscript_path (str) – absolute path to the template parflow runscript file

  • write_dir (str) – directory where the new template file will be written. If it is None, defaults to the directory containing the runscript.

  • runname (str) – name for the new parflow run. If it is None, defaults to the runscript’s previous runname.

  • forcing_dir (str) – path to the directory containing the subset forcing files. If it is None, defaults to the runscript’s previous forcing directory path.

Returns:

A path to the new runscript file that will be created.

Example:

runscript_path = edit_runscript_for_subset(
    ij_bounds=(375, 239, 487, 329),
    runscript_path="/path/to/your/original/runscript",
    runname="my_conus1_run",
    forcing_dir="/path/to/your/forcing/directory"
)
subsettools.parflow_run.copy_files(read_dir, write_dir)[source]

Copy all files from read_dir to write_dir.

Parameters:

  • read_dir (str) – read-from directory path

  • write_dir (str) – write-to directory path

Example:

copy_files(
    read_dir="/path/to/read-from/directory",
    write_dir="/path/to/write-to/directory"
)
subsettools.parflow_run.change_filename_values(runscript_path, write_dir=None, runname=None, slopex=None, slopey=None, solidfile=None, init_press=None, indicator=None, depth_to_bedrock=None, mannings=None, evap_trans=None)[source]

Change the filenames of input files in the ParFlow runscript.

This function will update the paths to input files in a ParFlow runscript. The provided arguments will reset the corresponding parflow keys to match the user specified paths to input files. File names can be specified with or without relative or absolute file paths. If no path is provided ParFlow will expect the input files to be present in the run directory at the time of simulation.

Note that this will only change paths for keys that already exist in the template ParFlow run script you are starting from and will not reconfigure a run to use new keys (for example if you are not starting from a run script that uses a solid file, adding a new solid file path will not configure the run to use a solid file).

Refer to the ParFlow manual for additional information on any of the keys listed above.

If the runname is None and write_dir is the directory containing the runscript file, the runscript file will be overwritten.

Parameters:

  • runscript_path (str) – path to the runscript file (yaml or pfidb)

  • write_dir (str) – directory where the new template file will be written. If it is None, defaults to the directory containing the runscript file.

  • runname (str) – name of the new parflow run

  • slopex (str) – new slopex filename (and path)

  • slopey (str) – new slopey filename (and path)

  • solidfile (str) – new solidfile filename (and path)

  • init_press (str) – new initial pressure filename (and path)

  • indicator (str) – new indicator input filename (and path)

  • depth_to_bedrock (str) – new depth to bedrock filename (and path)

  • mannings (str) – new mannings filename (and path)

  • evap_trans (str) – new evapotranspiration filename (and path)

Returns:

A path to the new runscript file that will be created.

Example:

runscript_path = change_filename_values(
    runscript_path="/path/to/your/original/runscript",
    runname="my_conus1_run",
    init_press="/filename/of/initial/pressure/pfb/file"
)
subsettools.parflow_run.dist_run(topo_p, topo_q, runscript_path, working_dir=None, dist_clim_forcing=True)[source]

Distribute ParFlow input files for parallel computing.

This function will distribute input files to topo_p grids in the x direction and topo_q grids in the y direction. If dist_clim_forcing is true, forcing files will be distributed as well according to the same topology. If working_dir is different that the directory containing the runscript file, the edited runscipt file will be written to working_dir.

Parameters:

  • topo_p (int) – number of grids (processes) to create in the x direction

  • topo_q (int) – number of grids (processes) to create in the y direction

  • runscript_path (str) – path to the runscript file (yaml or pfidb)

  • working_dir (str) – directory containing the files to be distributed. If it is None, it defaults to the directory containing the runscript file.

  • dist_clim_forcing (bool) – if true, distribute forcing files

Returns:

Path to the edited runscript file that will be created.

Return type:

str

Example:

runscript_path = dist_run(
    topo_p=2,
    topo_q=2,
    runscript_path="/path/to/your/original/runscript",
    dist_clim_forcing=False
)