bdschism package

Subpackages

• bdschism.config package
  • Module contents

Submodules

bdschism.analyze_dt module

bdschism.analyze_dt.load_data(ncfile, time_step=None)

Load time step and mesh data from a SCHISM NetCDF file.

Parameters:

• ncfile (str) – Path to the NetCDF file.

• time_step (int or None) – Specific time index to select. If None, load all.

Returns:

Time step values, x-coordinates, y-coordinates.

Return type:

tuple of (np.ndarray, np.ndarray, np.ndarray)

bdschism.analyze_dt.plot_summarized_bad_actors(bad_actors, all_x, all_y, label_top=None)

bdschism.analyze_dt.summarize_elements(ncfile, top_n, min_count, ref_nth=25)

bdschism.analyze_dt.write_bad_csv(csv_out, points)

bdschism.analyze_dt.write_bad_shp(shp_out, points, all_x, all_y)

bdschism.barrier_status module

make_south_delta_barrier_status.py

Reads four barrier installation files (space-separated, #-commented) with at least:

• datetime

• install

And for Grant Line, an additional weir elevation column (accepts either ‘elev_weir’ or ‘weir_elev’).

Computes the per-barrier installation status at midnight (last known value strictly BEFORE each midnight) and writes a single CSV with per-barrier status plus an ag_count column.

Special rule for Grant Line:

If the weir-elevation column exists and is < 0 at a timestamp, treat the instantaneous ‘install’ value as 0.5 (partial). This is applied before computing the midnight state. (So daily ‘grantline’ may be 0, 0.5, or 1.0.)

ag_count:

Sum of the three ag barriers (oldr_tracy, midr, grantline) using their numeric daily values (so totals like 2.5 are possible). oldr_head is excluded from ag_count.

Output:

south_delta_barrier_install_and_count_daily.csv Columns: date, oldr_tracy, midr, grantline, oldr_head, ag_count

bdschism.barrier_status.main()

bdschism.barrier_status.read_install_series(path: str, name: str) → pandas.Series

Read a barrier file with required headers ‘datetime’ and ‘install’. For ‘grantline’, apply the weir-elevation adjustment (0.5 when elev < 0) if present. Returns a time-indexed Series of numeric install values.

bdschism.barrier_status.status_at_midnight(s: pandas.Series, days: pandas.DatetimeIndex) → pandas.Series

Status at 00:00 of each day = last known value strictly BEFORE that instant.

bdschism.calc_ndoi module

bdschism.calc_ndoi.calc_indoi(flux_file='flux.th', vsource_file='vsource.th', vsink_file='vsink.th', time_basis=None, elapsed_unit='s', flux_head='/home/runner/micromamba/envs/docs/lib/python3.12/site-packages/bdschism/../.././data/time_history/flux.th', sink_head='/home/runner/micromamba/envs/docs/lib/python3.12/site-packages/bdschism/../.././data/channel_depletion/vsink_dated.th', source_head='/home/runner/micromamba/envs/docs/lib/python3.12/site-packages/bdschism/../.././data/channel_depletion/vsource_dated.th')

Calculate an estimate of Net Delta Outflow from boundary inputs applied to SCHISM

bdschism.ccf_gate_height module

bdschism.combine_hotstart module

bdschism.combine_hotstart.combine_hot(run_dir: str = '.', outputs_dir: str = 'outputs', prefix: str = '', latest: bool = False, before: str | pandas.Timestamp | None = None, iteration: int | None = None, every: int | None = None, out_dir: str | None = None, link: bool = False, config_log: bool = False, overwrite: bool = False) → List[str]

High-level API to combine SCHISM hotstart files.

This wraps the native combine_hotstart executable (configured via bdschism settings) and schimpy.hotstart_inventory to map between iterations and datetimes.

Parameters:

• run_dir (str, optional) – SCHISM run directory. Defaults to current directory.

• outputs_dir (str, optional) – Directory containing parallel hotstart_000000_*.nc files. Default ‘outputs’. If relative, interpreted relative to run_dir.

• prefix (str, optional) – Optional prefix inserted after ‘hotstart.’ in the output filename.

• latest (bool, optional) – If True, select the most recent hotstart.

• before (str or pandas.Timestamp, optional) – Select the last hotstart on or before this date.

• iteration (int, optional) – Combine this specific iteration.

• every (int, optional) – Archive every Nth hotstart in time order (10 -> 10th, 20th, …).

• out_dir (str, optional) – Archive directory. If relative, interpreted relative to run_dir.

• link (bool, optional) – If True, create hotstart.nc in run_dir pointing to the most recently created file using bdschism.settings.create_link.

• config_log (bool, optional) – If True, log configuration source when loading settings.

• overwrite (bool, optional) – If True, allow overwriting an existing destination file.

Returns:

Absolute paths of the combined hotstart files that were created.

Return type:

list of str

bdschism.combine_nc module

bdschism.combine_nc.combine_nc(input_files, outfile)

Combines multiple NetCDF files (e.g., out2d_1.nc, out2d_2.nc, etc.) into a single NetCDF file along the time dimension.

bdschism.combine_nc.combine_uv3d(start_num, end_num, outfile, tmp_out_dir='./outputs.tropic/uv3d')

bdschism.combine_nc.compare_dataarray_all_axes(validate_da, check_da, atol=1e-06, rtol=1e-06)

Check two DataArrays match on dims, coords, shape, and values.

bdschism.combine_nc.get_selected_files(template, start_num, end_num)

Get a sorted list of files matching the template and within the specified number range.

bdschism.combine_nc.validate_time_step_consistency(time_values, atol=1e-09, max_report=20)

Validate constant time step and report exact mismatch locations.

bdschism.config_cli module

bdschism.create_sflux_links module

bdschism.diff_gr3 module

bdschism.diff_gr3.diff_congruent_gr3(fname0, fname1, fout)

bdschism.gen_elev2d module

Generate elev2D.th for a Bay-Delta SCHSIM model using tides at Point Reyes and Monterey.

2015-06-16: Customized

class bdschism.gen_elev2d.BinaryTHWriter(fpath_out, nloc, starttime)

Bases: THWriter

write_all(times, vals)

write_step(iter, time, vals)

class bdschism.gen_elev2d.NetCDFTHWriter(fpath_out, nloc, starttime, dt, slr, hgrid_fpath)

Bases: THWriter

write_all(times, vals)

write_step(iter, time, vals)

class bdschism.gen_elev2d.THWriter(path, size, starttime)

Bases: object

write_all(times, vals)

write_step(iter, time, vals)

bdschism.gen_elev2d.gen_elev2D(hgrid_fpath, outfile, pt_reyes_fpath, monterey_fpath, start, end, slr)

Generate elev2D.th or elev2D.th.nc file for Bay-Delta SCHISM model using Point Reyes and Monterey tide data.

Arguments: hgrid_fpath: Path to hgrid file (e.g. hgrid.gr3) outfile: Path to output file (e.g. elev2D.th or elev2D.th.nc) pt_reyes_fpath: Path to Point Reyes data file(s) or station code (e.g. “/path/to/noaa_pryc1_9415020_elev_*.csv”) monterey_fpath: Path to Monterey data file(s) or station code (e.g. “path/to/noaa_mtyc1_9413450_elev_*.csv”) start: Start time (e.g. “2025-8-27”) end: End time (e.g. “2026-01-04”) slr: Sea level rise increment in meters (e.g. 0.0)

Example usage: > gen_elev2D.py –outfile elev2D.th.nc –hgrid=hgrid.gr3 –stime=2025-8-27 –etime=2026-01-04 –slr 0.0 “/path/to/noaa_pryc1_9415020_elev_*.csv” “path/to/noaa_mtyc1_9413450_elev_*.csv”

bdschism.generate_realtime_elev2d module

bdschism.generate_realtime_elev2d.main()

bdschism.generate_realtime_elev2d.stitch_station(df_cur, df_past, df_pred, t_stitch=None)

Stitch the historical water lever with the prediction one

Parameters:

• df_cur (pd.DataFrame) – The current historical data

• df_past (pd.DataFrame) – The past historical data

• df_pred (pd.DataFrame) – The prediction data

• t_transition (datetime, optional) – The time of transition between the historical and prediction data

bdschism.generate_visit_filelist module

bdschism.generate_visit_filelist.visit_list(output_dir, var, start, end, filename)

Generate a file containing a list of SCHISM output files to be visualized on VisIt.

Parameters:

• output_dir (str) – Outputs directory containing SCHISM output files.

• var (str) – variable name for SCHISM output files (e.g., horizontalVelX).

• start (int) – Starting index for the file list.

• end (int) – Ending index for the file list.

• filename (str) – Filename for the list of SCHISM output files.

bdschism.hotstart_date module

bdschism.hotstart_date.set_hotstart_date(fn, run_start, restart_time, outprefix, dt)

Change timestamp and date implied by hotstart.

bdschism.hotstart_from_hotstart module

Adapted from ZZheng - generate hotstart - transfer from one grid to another

class bdschism.hotstart_from_hotstart.SafeDict

Bases: dict

Safe dictionary for string formatting.

bdschism.hotstart_from_hotstart.fmt_string_file(template_str, output_path, subs, mode='format_map')

Format a string template and write it to a file, optionally returning the formatted string.

Parameters:

• template_str (str) – The input string template. May contain placeholders for substitution.

• output_path (str) – Path where the formatted string will be written.

• subs (dict, optional) – Substitution values. Keys should match placeholders (for ‘format_map’) or be (old, new) pairs (for ‘replace’ mode).

• mode (str, optional) –

  Substitution mode:

  • ’format_map’ (default): uses Python format_map() with {placeholder} replacement.

  • ’replace’: simple text replacement; ‘subs’ should be a list of (old, new) tuples.

Returns:

The fully substituted and formatted string.

Return type:

str

bdschism.hotstart_from_hotstart.hotstart_newgrid(yaml_template_fn: str, hotstart_in, hotstart_out, src_dir, trg_dir, modules=None, crs='EPSG:26910')

Transfer hotstart data from one grid to another.

bdschism.hotstart_from_hotstart.load_template(template_path)

bdschism.hotstart_from_hotstart.str_or_path(value)

Helper function to handle string or Path inputs.

bdschism.hotstart_nudging_data module

bdschism.hotstart_nudging_data.hotstart_nudge_data(sdate, ndays, dest, repo_dir)

bdschism.nc_metadata module

bdschism.nc_metadata.nc_metadata(ncfile, attr_name, attr_value, write, read, overwrite)

Read or write NetCDF global metadata.

bdschism.parse_cu module

bdschism.plot_input_boundaries module

bdschism.port_boundary module

bdschism.profile_plot module

bdschism.profile_plot.get_index_bounds()

bdschism.profile_plot.nearest_neighbor_fill(arr)

bdschism.profile_plot.profile_plot(x, z, data, ax, context_label=None, add_labels=False, xlabel=None, xmin=None, xmax=None, max_depth=None)

UnTRIM-like profile plot of salinity xmin,xmax are the bounds (in km) of the profile max_depth is the maximum depth, data assumed to be

bdschism.profile_plot.set_index_bounds(min_station, max_station, max_depth)

bdschism.profile_plot.vertical_fill(arr)

bdschism.read_dss module

bdschism.run_sequence module

bdschism.runtime_hotstart module

class bdschism.runtime_hotstart.rst_fm_hotstart(mod_dir, param, iteration=None)

Bases: object

combine_hotstart(iteration, machine='linux', printout=False)

get_last_hotstart()

get_mirror_crash()

get_ts_info()

param_mod(iteration, param_in='param.nml.clinic')

bdschism.runtime_hotstart.tail(f, n, offset=0)

bdschism.set_mode module

exception bdschism.set_mode.ModeError

Bases: Exception

Error raised for invalid mode configurations or runtime issues.

bdschism.set_mode.set_mode(arg1, arg2=None, rundir_opt=None, dry_run=False, hard_fail=True)

Set a SCHISM run directory into a named MODE by creating configured links.

bdschism.set_nudging module

Set the nudging links for a Bay-Delta SCHSIM model

2025-02-04: Customized

bdschism.set_nudging.get_nudge_list(fname)

bdschism.set_nudging.parse_var_map(ctx, param, value)

Parse a string of key=value pairs separated by commas into a dictionary. Expected format: “key1=value1,key2=value2” Used for var_map which feeds the gr3 formats for things like TEM=temperature

bdschism.set_nudging.set_nudging(suffix: str, workdir='.', var_map={}, param_fn='param.nml')

This is a utility to set up nudging files based on a naming convention common for BayDeltaSCHISM. Assumed this is on Linux or admin-priveleged Windows machine.

Parameters:

• suffix (str) – This is the suffix used when preparing the nudging/gr files. For instance “obshycom” in SAL_nu_obshycom.nc

• workdir (str) – Directory where the links and changes are made

• var_map (str) – Unexpected mapping in key=value pairs, separated by commas. Ex: –var_map ‘TEM=temperature,SAL=salinity’

• param_fn (str) – Which param.nml file will be used to determine module list. Should be the baroclinic param file. Default is param.nml

bdschism.settings module

bdschism.settings.create_link(source, symlink, config_log=False)

Create a link between a source file and a target path based on system-specific link styles.

This function creates a symbolic link, junction, or copies the file, depending on the system settings. The link style is determined dynamically from get_settings(), which specifies the preferred linking method for the operating system.

Parameters:

• source (str) – The path to the source file that will be linked.

• symlink (str) – The target path where the link (or copy) will be created.

• config_log (bool, optional) – If True, log the configuration source being used.

Raises:

ValueError – If the link style retrieved from get_settings() is unsupported.

Notes

• If a symbolic link already exists at symlink, it is removed before creating a new one.

• On Windows, the function supports creating junction links (mklink), symbolic links, or copying the file instead.

• On Unix-based systems, it defaults to using symbolic links.

Examples

Create a symbolic link on Unix-like systems or an appropriate alternative on Windows:

>>> create_link("/path/to/source.txt", "/path/to/symlink.txt")

bdschism.settings.get_output_from_interpolate_variables(varname, config_log=False)

Get the output filename for the interpolate_variables function.

Parameters:

• varname (str) – The variable name for which to retrieve the output filename (e.g., ‘uv3d’).

• config_log (bool, optional) – If True, log the configuration source being used.

Returns:

The output filename for the interpolate_variables utility.

Return type:

str

bdschism.settings.get_settings(config_log: bool = False)

Load and return application settings from a configuration file.

This function retrieves configuration settings using a hierarchy of possible sources: 1. A package-level default configuration file (bds_config.yaml within the package). 2. A project-level configuration file (bds_config.yaml in the current working directory). 3. An environment-specific configuration file, if BDS_CONFIG is set and points to a valid file.

The function uses Dynaconf to load settings, ensuring that the highest-priority configuration (environment variable, project-level, or package default) is used.

Returns:

A Dynaconf object containing the loaded configuration settings.

Return type:

Dynaconf

Notes

• The package-level configuration file provides default settings.

• If a project-level configuration file exists in the current directory, it overrides the package default.

• If an environment variable BDS_CONFIG is set and points to a valid file, it takes the highest precedence.

• The function logs the configuration source being used.

Examples

Load settings from the highest-priority available configuration file:

>>> settings = get_settings()
Using configuration from: /path/to/highest-priority-config.yaml current env development

Access settings:

>>> settings.some_setting
'some_value'

bdschism.settings.interpolate_variables(config_log=False)

interpolate SCHISM variables from background grid to foreground grid for elevation, tracers, or uv3D

Parameters:

config_log (bool, optional) – If True, log the configuration source being used.

Raises:

ValueError – If the link style retrieved from get_settings() is unsupported.

Notes

• interpolate_variables8 is the version of interpolate_variables associated with SCHISM 5.11

Examples

Interpolate SCHISM variables on Unix-like systems or an appropriate alternative on Windows:

>>> interpolate_variables()

bdschism.smscg_log_2_schism_th module

bdschism.synthetic_copy module

bdschism.synthetic_copy.is_leap_year_manual(year)

bdschism.synthetic_sflux module

Create synthetic HRRR forcing files by copying an existing repository and shifting all dates forward by one year.

For each day in [sdate, edate], the script:

• Reads: {source_repo}/{YEAR}/hrrr_YYYYMMDD00.nc

• Writes: {dest_repo}/{YEAR+1}/hrrr_{YEAR+1}{MM}{DD}00.nc

Leap-year handling

• If the source year is a leap year but the destination year is not:

  • Feb 29 is skipped.

• If the source year is not a leap year but the destination year is:

  • Feb 29 is created by copying Feb 28 and shifting the time one day.

The script also:

• Shifts the xarray Dataset time coordinate by +1 year (or +1 year +1 day for synthetic Feb 29).

• Updates time.attrs[“base_date”] to reflect the new date.

• Adds provenance attributes:

  • “creator” = “CA DWR Delta Modeling Section”

  • “creation_method” = description of what was copied.

This is intended for creating synthetic “next-year” met forcing when you want to reuse a prior year.

bdschism.synthetic_sflux.configure_logging(verbose: bool) → None

Configure root logger.

bdschism.synthetic_sflux.is_leap_year(year: int) → bool

Return True if year is a leap year (Gregorian rules).

bdschism.three_point_linear_norm module

class bdschism.three_point_linear_norm.ThreePointLinearNorm(*args: Any, **kwargs: Any)

Bases: Normalize

autoscale(A)

Set vmin, vmax to min, max of A.

autoscale_None(A)

autoscale only None-valued vmin or vmax

inverse(value)

scaled()

return true if vmin and vmax set

bdschism.tide module

class bdschism.tide.Node(name, record_length_hours=166440)

Bases: object

add_child(child_node)

Adds a child node to this node’s children list.

add_parent(parent_node)

Adds a parent node to this node’s parent list.

get_ancestors()

retrieves the list of ancestors of this node.

get_descendants()

retrieves the list of descendants of this node.

num_ancestors()

Recursively counts the total number of ancestors of this node.

num_descendants()

Recursively counts the total number of descendants of this node.

bdschism.tide.gen_constituents_tree()

This function generates the constituent trees of Choice of constituents and Rayleigh comparison pairs It returns a list of root nodes for subtide, diurnal, semidiurnal and terdiurnal, and a list of shallow water constituents that have multiple parents. It is implementation from Table 1 to Table 5 in “MANUAL FOR TIDAL HEIGHTS ANALYSIS AND PREDICTION” by M.G.G. Foreman (1996).

bdschism.tide.get_astro_constituent_names(astro_group, record_length_hours=0)

Recursivly Retrieves the names of all constituents in the astro_group that can be analyazed by the specified record_length_hours.

Args: astro_group: list of root nodes for the main constituent groups (slow, diurnal, semidiurnal, terdiurnal). record_length_hours: the length of the record in hours, used to determine which constituents can be analyzed.

Returns: A sorted list of constituent names that can be analyzed with the given record length.

bdschism.tide.get_constituents(record_length_hours=0)

Retrieves the names of all constituents in the astro_group and shallow_group that can be analyazed by the specified record_length_hours.

Parameters:

• astro_group – list of root nodes for the main constituent groups (slow, diurnal, semidiurnal, terdiurnal).

• shallow_group – list of nodes for shallow water constituents that have multiple parents.

• record_length_hours – the length of the record in hours, used to determine which constituents can be analyzed.

Returns: A sorted list of constituent names that can be analyzed with the given record length.

bdschism.uv3d module

bdschism.uv3d.interpolate_uv3d(param_nml, bg_dir, bg_output_dir, fg_dir, hgrid_bg, hgrid_fg, vgrid_bg, vgrid_fg, interp_template, nday, output, overwrite)

Run interpolate_variables utility to generate uv3d.th.nc.

Parameters:

• param_nml (str or None) – Path to param.nml. If None, defaults to bg_dir/param.nml.

• bg_dir (str) – Background simulation directory.

• bg_output_dir (str or None) – Output directory inside bg_dir where interpolate_variables is run.

• fg_dir (str or None) – Foreground (baroclinic) run directory. Used for hgrid_fg/vgrid_fg links. If None, defaults to bg_dir.

• hgrid_bg (str) – Background hgrid filename (relative to bg_dir).

• hgrid_fg (str) – Foreground hgrid filename (relative to fg_dir).

• vgrid_bg (str) – Background vgrid filename (relative to bg_dir).

• vgrid_fg (str) – Foreground vgrid filename (relative to fg_dir).

• interp_template (str or None) – Path to interpolate_variables.in template. If None, a minimal file is written based on nday (or rnday from param.nml).

• nday (int or None) – Number of days to process when interp_template is None. If None, rnday is read from param_nml.

• output (str) – Path where the final uv3d output will be written (moved).

• overwrite (bool) – If True, overwrite an existing file in output_dir. If False, fail fast if the file already exists.

bdschism.uv3d.setup_tmp_dir(bg_output_dir, tmp_bg_output_dir, nfile)

Set up a temporary directory with links to the specific output files for uv3d interpolation.

bdschism.uv3d.single_uv3d(nfile, param_nml='param.nml', bg_dir='./', bg_output_dir='./outputs', fg_dir='./', hgrid_bg='./hgrid.gr3', hgrid_fg='./hgrid.gr3', vgrid_bg='./vgrid.in.2d', vgrid_fg='./vgrid.in.3d', out_dir='./', overwrite=True, cleanup=True)

Process a single uv3d output file for the specified nfile index.

bdschism.x2_buildpoints module

Extract station xyz from a x2 route UTM file. The resulting station file conforms to SCHISM bp station format. Stations along bay route start from 65km from San Francisco and end at confluence, Station along mzm start from 18km from Marinez end at confluence, Station along Sac starts from confluence and end 25km upstream of sac river, Station along San Joaquin route starts from confluence and end 25km upstream of San Joaquin River. Their depth are defined as relativly to surface. ONLY surface or bottom stations are available, surface station set elevation to 0 and bottom station set elevation to -10000.0. station xyz are output as Bay route, San Joaquin, Sac and MZM in order.

bdschism.x2_buildpoints.create_arg_parser()

Create an argument parser return: argparse.ArgumentParser

bdschism.x2_buildpoints.main()

Main function

bdschism.x2_buildpoints.main_fixed()

bdschism.x2_buildpoints.x2_route2_bp(x2_route_file, interval, route_id=None, bpout=None, minkm=35)

bdschism.x2_time_series module

Create x2 time series from build-point files.

This script reads x2_route.bp as well as the fort.18 resulting from SCHISM read_output9_xyz to extract salinity on X2 stations. It search along x2 stations to find two neiboring stations higher and lower than X2 criteria (bottom or surface). If X2 retreat less than the minimum stations along the transect, the X2 result will be truncated at that point.

usage: –start 2004-04-18 –x2route x2route.bp output: x2 on surface and bottom location time series in csv format, bottom_x2.csv and surface_x2.csv

bdschism.x2_time_series.create_arg_parser()

bdschism.x2_time_series.default_outname(bpname)

bdschism.x2_time_series.find_x2(transect, thresh=2.0, convert_km=0.001, distance_bias=0.0)

Given a series transect, indexed by distance, locate a distance with value is close to thresh

bdschism.x2_time_series.get_start_date_from_param(param_in)

bdschism.x2_time_series.main()

bdschism.x2_time_series.main_hardwire()

bdschism.x2_time_series.process_x2(salt_data_file, route_file, model_extract_date, output_file, param_in=None, model_start_date=None)

Process x2 into a time series

bdschism.zone_utils module

Created on Fri May 5 09:45:12 2023

@author: qshu

bdschism.zone_utils.face_aver(node_depth_average, node_num, face_num, ele_table)

bdschism.zone_utils.face_aver_inst(inst_node_depth_average, node_num, face_num, ele_table)

bdschism.zone_utils.fill_ele_area(face_num, ele_table, node_x, node_y, ele_area)

bdschism.zone_utils.fill_ele_area510(face_num, ele_table, node_x, node_y, ele_area)

bdschism.zone_utils.gen_node_neibor_ele(mesh_node, max_node_in_a_cell, num_ele, num_node)

bdschism.zone_utils.gen_node_wet_dry(node_wet_dry, ele_wet_dry, num_step, num_node, max_ele_at_node, el)

bdschism.zone_utils.quad_area(x1, y1, x2, y2, x3, y3, x4, y4)

bdschism.zone_utils.triangle_area(x1, y1, x2, y2, x3, y3)

Module contents