Model Interfaces
This section provides interfaces for different ocean models.
SCHISM Model
The SCHISM class provides an interface for handling SCHISM model outputs.
ocstrack.Model.model.SCHISM
SCHISM model interface
Handles selection, filtering, and loading of model outputs from a SCHISM run directory. Also parses the model mesh (hgrid.gr3) for spatial queries. This assumes a run directory structure where: . ├── RunDir ├── hgrid.gr3 ├── ... ├── outputs ├── out2d_.nc └── .nc
Methods
load_variable(path) Load model variable from a NetCDF file and extract surface layer if 3D
files
property
Return the list of selected model output files.
mesh_depth
property
Return mesh node depths.
mesh_x
property
writable
Return mesh longitudes.
mesh_y
property
writable
Return mesh latitudes.
time
property
Return the concatenated time array for all selected files.
The time array is cached after the first call.
__init__(rundir, model_dict, start_date, end_date, output_subdir='outputs')
Initialize a SCHISM model run
Parameters
rundir : str Path to the SCHISM model run directory model_dict : dict Dictionary with keys: 'startswith', 'var', 'var_type' start_date : np.datetime64 Start of the time range for selecting model files end_date : np.datetime64 End of the time range for selecting model files output_subdir : str, optional Name of the subdirectory containing output NetCDF files (default: "outputs")
load_3d_file_pair(f_main_path)
Loads a single 3D variable file and its matching z-coordinate file.
This is the memory-efficient method for 3D collocation.
Parameters
f_main_path : str The full path to the main variable file (e.g., "temperature_84.nc").
Returns
xr.Dataset A single, in-memory dataset containing the 3D variable and its 'zcor' variable for the time steps in that file.
load_variable(path)
Load the specified variable from a model NetCDF file.
Parameters
path : str Path to the NetCDF file to open
Returns
xr.DataArray The requested variable, , surface-only if var_type is '3D_Surface'
Notes
For 3D variables, this method extracts the surface layer (last index of vertical layers).
ADCSWAN Model
The ADCSWAN class provides an interface for handling ADCIRC+SWAN model outputs.
ocstrack.Model.model.ADCSWAN
ADCIRC+SWAN model interface.
Handles selection and loading of model outputs from a single ADCIRC+SWAN NetCDF file. This class locates a single file based on 'startswith' and validates its time range against the requested start/end dates. It reads mesh coordinates (x, y, depth) directly from this file.
This class mimics the SCHISM interface for compatibility in the collocation workflow.
files
property
Return the model file path (a list with 0 or 1 item).
mesh_depth
property
Return mesh node depths.
mesh_x
property
writable
Return mesh longitudes.
mesh_y
property
writable
Return mesh latitudes.
__init__(rundir, model_dict, start_date, end_date, **kwargs)
Initialize an ADCIRC+SWAN model run
Parameters
rundir : str Path to the directory containing the model output NetCDF file model_dict : dict Dictionary with keys: 'startswith', 'var'. 'startswith' is the prefix of the NetCDF file (e.g., "swan_HS.63") 'var' is the variable to be loaded (e.g., "swan_HS") start_date : np.datetime64 Start of the time range for validation and slicing (if needed) end_date : np.datetime64 End of the time range for validation and slicing (if needed) **kwargs : Ignored. Added for interface compatibility with SCHISM (e.g., output_subdir).
load_variable(path)
Load the specified variable from the model NetCDF file.
Parameters
path : str Path to the NetCDF file to open (should be the one in self.files)
Returns
xr.DataArray The requested variable, sliced by time.
Notes
For compatibility with the SCHISM class pattern, this method loads the variable from the given path.
Utility Functions
These are helper functions used by the model interfaces.
ocstrack.Model.model.natural_sort_key(filename)
Generate a key for natural sorting of filenames (e.g., file10 comes after file2).
Parameters
filename : str Filename to generate sorting key for
Returns
List[Union[int, str]] List of numeric and string parts to be used for sorting
ocstrack.Model.model._parse_gr3_mesh(filepath)
Parse a SCHISM hgrid.gr3 mesh file to extract node coordinates and depth.
Parameters
filepath : str Path to the hgrid.gr3 mesh file
Returns
Tuple[np.ndarray, np.ndarray, np.ndarray] Tuple of (lon, lat, depth) arrays for each mesh node
Notes
Assumes the hgrid.gr3 file contains node-based data with the expected format. This was added so we don't need OCSMesh as a requirement anymore.