IOClass

class cosipy.cpkernel.io.IOClass(DATA=None)[source]

Bases: object

Attributes

`B`
`H`
`LE`
`LWin`
`LWout`
`MB`
`QRR`
`RAIN`
`SNOWFALL`

Methods

`__init__`([DATA])	Initialise the IO Class.
`add_variable_along_latlon`(ds, var, name, ...)	Add spatial data to a dataset.
`add_variable_along_latlonlayer`(ds, var, ...)	Add a spatial mesh to a dataset.
`add_variable_along_latlonlayertime`(ds, var, ...)	Add a spatiotemporal mesh to a dataset.
`add_variable_along_latlontime`(ds, var, name, ...)	Add spatiotemporal data to a dataset.
`add_variable_along_layer`(ds, var, name, ...)	Add layer data to a dataset.
`add_variable_along_layertime`(ds, var, name, ...)	Add temporal layer data to a dataset.
`add_variable_along_scalar`(ds, var, name, ...)	Add scalar data to a dataset.
`add_variable_along_time`(ds, var, name, ...)	Add temporal data to a dataset.
`check_field`(field, _max, _min)	Check the validity of the input data.
`check_input_data`()	Check the input data is within valid bounds.
`copy_local_restart_to_global`(y, x, local_restart)	Copy local restart data from workers to global numpy arrays.
`copy_local_to_global`(y, x, local_RAIN, ...)	Copy the local results from workers to global numpy arrays.
`create_3d_nan_array`(max_layers)	Create and fill a NaN array with time, (x,y,z) dimensions.
`create_data_file`()	Create the input data and read the restart file if necessary.
`create_empty_restart`()	Create an empty dataset for the RESTART attribute.
`create_global_restart_arrays`()	Initialise the global numpy arrays to store layer profiles.
`create_global_result_arrays`()	Create the global numpy arrays to store each output variable.
`create_grid_restart`()	Create and initialise the GRID_RESTART structure.
`create_local_restart_dataset`()	Create the result dataset for a single grid point.
`create_nan_array`()	Create and fill a NaN array with time, (x,y) dimensions.
`create_restart_file`()	Create and initialise the RESTART dataset.
`create_result_file`()	Create and initialise the RESULT dataset.
`get_datetime`(timestamp[, use_np, fmt])	Get datetime object from a string.
`get_full_field_metadata`()	Get layer variable names and units.
`get_grid_restart`()	Get the GRID_RESTART data structure.
`get_input_metadata`()	Get input variable names and units.
`get_output_variables`(variables)	Get output variable names from configuration string.
`get_restart`()	Get the RESTART data structure.
`get_restart_metadata`()
`get_result`()	Get the RESULT data structure.
`get_result_metadata`()	Get all variable names and units.
`init_atm_attribute`(name)	Initialise empty atm attribute.
`init_data_dataset`()	Read and store the input netCDF data.
`init_full_field_attribute`(name, max_layers)	Initialise empty layer attribute.
`init_internal_attribute`(name)	Initialise empty internal attribute.
`init_restart_dataset`()	Initialise the restart dataset.
`init_result_dataset`()	Create the final dataset to aggregate and store the results.
`set_atm_attribute`(name, value, x, y)	Set atm attribute if it is a desired output variable.
`set_full_field_attribute`(name, value, x, y)	Set layer attribute if it is a desired output variable.
`set_internal_attribute`(name, value, x, y)	Set internal attribute if it is a desired output variable.
`set_variable_metadata`(data, units, long_name)	Add long name, units, and default fill value to variable.
`write_restart_to_file`()	Add global numpy arrays to the RESTART dataset.
`write_results_to_file`()	Add the global numpy arrays to the RESULT dataset.

__init__(DATA=None)[source]

Initialise the IO Class.

DATA

Meteorological data.

Type:: xarray.Dataset or None

RESTART

Restart file data.

Type:: xarray.Dataset or None

RESULT

Model result data.

Type:: xarray.Dataset or None

add_variable_along_latlon(ds, var, name, units, long_name)[source]

Add spatial data to a dataset.

Parameters:

ds (xr.Dataset) – Target data structure.
var (np.ndarray) – New spatial data.
name (str) – The new variable’s abbreviated name.
units (str) – New variable units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new spatial variable.

Return type:

Dataset

add_variable_along_latlonlayer(ds, var, name, units, long_name)[source]

Add a spatial mesh to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New spatial mesh.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new spatial mesh.

Return type:

Dataset

add_variable_along_latlonlayertime(ds, var, name, units, long_name)[source]

Add a spatiotemporal mesh to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New spatiotemporal mesh data.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new spatiotemporal mesh.

Return type:

Dataset

add_variable_along_latlontime(ds, var, name, units, long_name)[source]

Add spatiotemporal data to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New spatiotemporal data.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new spatiotemporal variable.

Return type:

Dataset

add_variable_along_layer(ds, var, name, units, long_name)[source]

Add layer data to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New layer data.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new layer data.

Return type:

Dataset

add_variable_along_layertime(ds, var, name, units, long_name)[source]

Add temporal layer data to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New layer data with a time coordinate.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new layer data.

Return type:

Dataset

add_variable_along_scalar(ds, var, name, units, long_name)[source]

Add scalar data to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New data.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new scalar variable.

Return type:

Dataset

add_variable_along_time(ds, var, name, units, long_name)[source]

Add temporal data to a dataset.

Parameters:

ds (Dataset) – Target data structure.
var (ndarray) – New temporal data.
name (str) – The new variable’s abbreviated name.
units (str) – The new variable’s units.
long_name (str) – The new variable’s full name.

Returns:

Target dataset with the new temporal variable.

Return type:

Dataset

check_field(field, _max, _min)[source]

Check the validity of the input data.

Return type:: bool

check_input_data()[source]

Check the input data is within valid bounds.

Return type:: bool

copy_local_restart_to_global(y, x, local_restart)[source]

Copy local restart data from workers to global numpy arrays.

Parameters:

y (int) – Latitude index.
x (int) – Longitude index.
local_restart (Dataset) – Local RESTART dataset.

copy_local_to_global(y, x, local_RAIN, local_SNOWFALL, local_LWin, local_LWout, local_H, local_LE, local_B, local_QRR, local_MB, local_surfMB, local_Q, local_SNOWHEIGHT, local_TOTALHEIGHT, local_TS, local_ALBEDO, local_LAYERS, local_ME, local_intMB, local_EVAPORATION, local_SUBLIMATION, local_CONDENSATION, local_DEPOSITION, local_REFREEZE, local_subM, local_Z0, local_surfM, local_MOL, local_LAYER_HEIGHT, local_LAYER_RHO, local_LAYER_T, local_LAYER_LWC, local_LAYER_CC, local_LAYER_POROSITY, local_LAYER_ICE_FRACTION, local_LAYER_IRREDUCIBLE_WATER, local_LAYER_REFREEZE)[source]

Copy the local results from workers to global numpy arrays.

Parameters:

y (int)
x (int)
local_RAIN (ndarray)
local_SNOWFALL (ndarray)
local_LWin (ndarray)
local_LWout (ndarray)
local_H (ndarray)
local_LE (ndarray)
local_B (ndarray)
local_QRR (ndarray)
local_MB (ndarray)
local_surfMB (ndarray)
local_Q (ndarray)
local_SNOWHEIGHT (ndarray)
local_TOTALHEIGHT (ndarray)
local_TS (ndarray)
local_ALBEDO (ndarray)
local_LAYERS (ndarray)
local_ME (ndarray)
local_intMB (ndarray)
local_EVAPORATION (ndarray)
local_SUBLIMATION (ndarray)
local_CONDENSATION (ndarray)
local_DEPOSITION (ndarray)
local_REFREEZE (ndarray)
local_subM (ndarray)
local_Z0 (ndarray)
local_surfM (ndarray)
local_MOL (ndarray)
local_LAYER_HEIGHT (ndarray)
local_LAYER_RHO (ndarray)
local_LAYER_T (ndarray)
local_LAYER_LWC (ndarray)
local_LAYER_CC (ndarray)
local_LAYER_POROSITY (ndarray)
local_LAYER_ICE_FRACTION (ndarray)
local_LAYER_IRREDUCIBLE_WATER (ndarray)
local_LAYER_REFREEZE (ndarray)

create_3d_nan_array(max_layers)[source]

Create and fill a NaN array with time, (x,y,z) dimensions.

Parameters:

layers. (The maximum number of model)
max_layers (int)

Returns:

Filled array with time and 3D spatial coordinates.

Return type:

ndarray

create_data_file()[source]

Create the input data and read the restart file if necessary.

Returns:: Model input data.
Return type:: Dataset

create_empty_restart()[source]

Create an empty dataset for the RESTART attribute.

Returns:: Empty xarray dataset with coordinates from self.DATA.
Return type:: Dataset

create_global_restart_arrays()[source]

Initialise the global numpy arrays to store layer profiles.

Each global array will be filled with local results from the workers. The arrays will then be assigned to the RESTART dataset and stored to disk (see COSIPY.py).

create_global_result_arrays()[source]

Create the global numpy arrays to store each output variable.

Each global array is filled with local results from the workers. The arrays are then assigned to the RESULT dataset and stored to disk (see COSIPY.py).

create_grid_restart()[source]

Create and initialise the GRID_RESTART structure.

This contains the layer state of the last time step, which is required for the restart option.

create_local_restart_dataset()[source]

Create the result dataset for a single grid point.

Returns:: RESTART dataset initialised with layer profiles.
Return type:: Dataset

create_nan_array()[source]

Create and fill a NaN array with time, (x,y) dimensions.

Returns:: Filled array with time and 2D spatial coordinates.
Return type:: ndarray

create_restart_file()[source]

Create and initialise the RESTART dataset.

Return type:: Dataset

create_result_file()[source]

Create and initialise the RESULT dataset.

Return type:: Dataset

get_datetime(timestamp, use_np=True, fmt='%Y-%m-%dT%H:%M')[source]

Get datetime object from a string.

Parameters:

timestamp (str) – Timestamp.
use_np (bool) – Convert to numpy datetime64. Default True.
fmt (str) – Timestamp format.

Returns:

Timestamp converted to datetime or np.datetime64.

Return type:

datetime|np.datetime64

get_full_field_metadata()[source]

Get layer variable names and units.

Returns:: Metadata for full field layer variables, including netCDF keyname, unit, and long name.
Return type:: dict

get_grid_restart()[source]

Get the GRID_RESTART data structure.

Return type:: Dataset

get_input_metadata()[source]

Get input variable names and units.

Returns:: Metadata for spatial and spatiotemporal variables, including netCDF keyname, unit, and long name.
Return type:: tuple[dict, dict]

get_output_variables(variables)[source]

Get output variable names from configuration string.

Parameters:: variables (str)
Return type:: list

get_restart()[source]

Get the RESTART data structure.

Return type:: Dataset

get_result()[source]

Get the RESULT data structure.

Return type:: Dataset

get_result_metadata()[source]

Get all variable names and units.

Returns:: Metadata for all input and output variables, including netCDF keyname, unit, and long name.
Return type:: dict

init_atm_attribute(name)[source]

Initialise empty atm attribute.

Parameters:: name (str)

init_data_dataset()[source]

Read and store the input netCDF data.

The input data should contain the following variables:

PRES:: Air pressure [hPa].
N:: Cloud cover fraction [-].
RH2:: 2m relative humidity [%].
RRR:: Precipitation per time step [mm].
SNOWFALL:: Snowfall per time step [m].
G:: Solar radiation per time step [W m ^-2].
T2:: 2m air temperature [K].
U2:: Wind speed (magnitude) [m s ^-1].
HGT:: Elevation [m].

init_full_field_attribute(name, max_layers)[source]

Initialise empty layer attribute.

Parameters:

name (str)
max_layers (int)

init_internal_attribute(name)[source]

Initialise empty internal attribute.

Parameters:: name (str)

init_restart_dataset()[source]

Initialise the restart dataset.

Returns:: The empty restart dataset.
Return type:: Dataset

init_result_dataset()[source]

Create the final dataset to aggregate and store the results.

Aggregates results from individual COSIPY runs. After the dataset is filled with results from all the workers, the dataset is written to disk.

Returns:: One-dimensional structure with the model output.
Return type:: Dataset

set_atm_attribute(name, value, x, y)[source]

Set atm attribute if it is a desired output variable.

Parameters:

name (str) – Output variable name.
value (ndarray) – Output variable data.
x (int) – Slice x-coordinate.
y (int) – Slice y-coordinate.

set_full_field_attribute(name, value, x, y)[source]

Set layer attribute if it is a desired output variable.

Parameters:

name (str) – Output variable name.
value (ndarray) – Output variable data.
x (int) – Slice x-coordinate.
y (int) – Slice y-coordinate.

set_internal_attribute(name, value, x, y)[source]

Set internal attribute if it is a desired output variable.

Parameters:

name (str) – Output variable name.
value (ndarray) – Output variable data.
x (int) – Slice x-coordinate.
y (int) – Slice y-coordinate.

set_variable_metadata(data, units, long_name, fill_value=-9999)[source]

Add long name, units, and default fill value to variable.

Parameters:

data (Variable) – netCDF data structure.
units (str) – Variable units.
long_name (str) – Full name of variable.
fill_value (int) – NaN fill value. Default “-9999”.

Returns:

Dataset with updated metadata for a specific variable.

Return type:

Dataset

write_restart_to_file()[source]: Add global numpy arrays to the RESTART dataset.

write_results_to_file()[source]: Add the global numpy arrays to the RESULT dataset.