src.io#

Input/Output routines

Functions

fn_gen(params)

Automatically generates HDF5 output filename from src.var.params.

Classes

`ncdata`([read_merit, padding, padding_tol])	Helper class to read NetCDF4 topographic data
`reader`(fn)	Simple reader class to read HDF5 output written by `src.io.writer`
`writer`(fn, idxs[, sfx, debug])	HDF5 writer class

class src.io.ncdata(read_merit=False, padding=0, padding_tol=50)#

Helper class to read NetCDF4 topographic data

__init__(read_merit=False, padding=0, padding_tol=50)#

Parameters#

read_meritbool, optional: toggles between the MERIT DEM and USGS GMTED 2010 data files. By default False, i.e., read USGS GMTED 2010 data files.
paddingint, optional: number of data points to pad the loaded topography file, by default 0
padding_tolint, optional: padding tolerance is added no matter the user-defined padding, by default 50

read_dat(fn, obj)#

Reads data by attributes defined in the obj class.

Parameters#

fnstr: filename
objsrc.var.grid or src.var.topo or src.var.topo_cell: any data object in src.var accepting topography attributes

read_topo(topo, cell, lon_vert, lat_vert)#

Reads USGS GMTED 2010 dataset

Parameters#

toposrc.var.topo or src.var.topo_cell: instance of a topography class containing the full regional or global topography loaded via src.io.read_dat().
cellsrc.var.topo_cell: instance of a cell object
lon_vertlist: extent of the longitudinal coordinates encompassing the region to be loaded
lat_vertlist: extent of the latitudinal coordinates encompassing the region to be loaded

Note

Loading the global topography in the topo argument may not be memory efficient. The notebook nc_compactifier.ipynb contains a script to extract a region of interest from the global GMTED 2010 dataset.

class read_merit_topo(cell, params, verbose=False)#

Subclass to read MERIT topographic data

__init__(cell, params, verbose=False)#

Populates cell object instance with arguments from params

Parameters#

cellsrc.var.topo or src.var.topo_cell: instance of an object with topograhy attribute
paramssrc.var.params: user-defined run parameters
verbosebool, optional: prints loading progression, by default False

get_topo(cell, fns, lon_cnt, lat_cnt, init=True, populate=True)#

This method assembles a contiguous array in cell.topo containing the regional topography to be loaded.

However, this full regional array is assembled from an array of block arrays. Each block array is loaded from a separated MERIT data file and varies in shape that is not known beforehand.

Therefore, the get_topo method is run recursively:

The first run determines the shape of each constituting block array and subsequently the shape of the full regional array. An empty array in initialised.
The second run populates the empty array with the information of the block arrays obtained in the first run.

class src.io.writer(fn, idxs, sfx='', debug=False)#

HDF5 writer class

Contains methods to create HDF5 file, create data sets and populate them with output variables.

Note

This class was taken from an I/O routine originally written for the numerical flow solver used in Chew et al. (2022) and Chew et al. (2023).

__init__(fn, idxs, sfx='', debug=False)#

Creates an empty HDF5 file with filename fn and a group for each index in idxs

Parameters#

fnstr: filename
idxslist: list of cell indices
sfxstr, optional: suffixes to the filename, by default ‘’
debugbool, optional: debug flag, by default False

io_create_file(paths)#

Helper function to create file.

Parameters#

pathslist: List of strings containing the name of the groups.

Notes#

Currently, if the filename of the HDF5 file already exists, this function will append the existing filename with ‘_old’ and create an empty HDF5 file with the same filename in its place.

write_all(idx, *args)#

Write all attributes and datasets of a given class instance to the group idx.

Parameters#

idxstr or int: group name to write the attributes or datasets

write_attr(idx, key, value)#

Write HDF5 attributes for a group

Parameters#

idxstr or int: group name to write the attributes
keystr: attribute name
valueany: attribute value that is accepted by HDF5

write_all_attrs(obj)#

Write all attributes a given class instance to the HDF5 file

Parameters#

objsrc.var.params: write all user-defined parameters to the HDF5 file for reproducibility of the output

populate(idx, name, data)#

Helper function to write data into HDF5 dataset.

Parameters#

idxint or str: The name of the group
namestr: The name of the dataset
datandarray: The output data to write to the dataset

class src.io.reader(fn)#

Simple reader class to read HDF5 output written by src.io.writer

__init__(fn)#

Parameters#

fnstr: filename of the file to be read

get_params(params)#

Get the user-defined parameters from the HDF5 file attributes

Parameters#

paramssrc.var.params: empty instance of the user-defined parameters class to be populated

read_data(idx, name)#

Read a particular dataset name from a group idx

Parameters#

idxstr or int: the group name
namestr: the dataset name

Returns#

array-like: the dataset

read_all(idx, cell)#

Populate cell with all datasets in a group idx

Parameters#

idxint or str: the group name
cellsrc.var.topo_cell: empty instance of a cell object to be populated

src.io.fn_gen(params)#

Automatically generates HDF5 output filename from src.var.params.

Parameters#

paramssrc.var.params: instance of the user parameter class

Returns#

str: automatically generated filename