InputHipims

The module is based on the following assumptions:

  • Input DEM is a regular DEM file

  • its map unit is meter

  • its cellsize is the same in both x and y direction

  • its reference position is on the lower left corner of the southwest cell

  • All the other grid-based input files must be consistent with the DEM file

To do:

  • generate input (including sub-folder mesh and field) and output folders

  • generate mesh file (DEM.txt) and field files

  • divide model domain into small sections if multiple GPU is used


class IO.InputHipims.InputHipims(dem_data=None, num_of_sections=1, case_folder=None, data_path=None)

To define input files for a HiPIMS flood model case

Read data, process data, write input files, and save data of a model case.

num_of_sections

(scalar) number of GPUs to run the model

shape

shape of the DEM array

header

(dict) header of the DEM grid

__attributes_default

(dict) default model attribute names and values

attributes

(dict) model attribute names and values

times

(list/numpy array) of four values reprenting model run time in seconds: start, end, output interval, backup interval

device_no

(int) the gpu device id(s) to run model

param_per_landcover

dict, argument to set grid parameters using the Landcover object. Keys are grid parameter names. Each Value is a dict with three keys: param_value, land_value, default_value. Refer to Landcover for more details.

Sections

a list of objects of child-class InputHipimsSub

Boundary

A boundary object for boundary conditions

DEM

a Raster object to provide DEM data [alias: Raster].

Rainfall

a Rainfall object to process rainfall data

Landcover

a Landcover object to provide landcover data for setting gridded parameters

Summary

a Summary object to record model information

__init__(dem_data=None, num_of_sections=1, case_folder=None, data_path=None)

Initialise the InputHipims object

Parameters
  • dem_data – (Raster object) or (str) provides file name of the DEM data

  • data_folder – a path contain at least a DEM file named as ‘DEM’ with a suffix .gz|.asc|.tif. ‘landcover’ and ‘rain_mask’ can also be read if these files were given with one of the three suffix

add_user_defined_parameter(param_name, param_value)

Add a grid-based user-defined parameter to the model

Parameters
  • param_name – (str) name the parameter and the input file name too

  • param_value – (scalar) or (numpy arary) with the same shape of the DEM array

domain_show(title='Domain Map', show_split=False, **kwargs)

Show domain map of the object

Parameters
  • title – string to set the figure titile, ‘Domain Map’ is the defualt

  • show_split – logical, show split lines for multi-gpu division

Retrun:

fig: figure handle ax: axis handle

get_case_folder()

Get the directory of the case.

Returns

The directory of the case

Return type

string

get_data_folders()

Get the directories and subdirectories of the input and output data.

Returns

a dict with four keys (‘input’, ‘output’, ‘mesh’, ‘field’)

providing their absolute paths

Return type

string

get_input_filenames()

Get the input file names.

Returns

a list of string giving all input filenames without

Return type

list

plot_rainfall_curve(start_date=None, method='mean', **kw)

Plot time series of average rainfall rate inside the model domain

Parameters
  • start_date – a datetime object to give the initial datetime of rain

  • method – ‘mean’|’max’,’min’,’mean’, method to calculate gridded rainfall over the model domain

plot_rainfall_map(figname=None, method='sum', **kw)

plot rainfall map within model domain

save_object(file_name)

Save object as a pickle file

set_boundary_condition(boundary_list=None, outline_boundary='fall')

To create a Boundary object for boundary conditions

Parameters
  • boundary_list

    (list of dicts), each dict contain keys (polyPoints, type, h, hU) to define a IO boundary’s position, type, and Input-Output (IO) sources timeseries. Keys including:

    1.polyPoints is a numpy array giving X(1st col) and Y(2nd col)

    coordinates of points to define the position of a boundary. An empty polyPoints means outline boundary.

    2.type: ‘open’(flow out flatly), ‘rigid’(no outlet),

    ’fall’(water flow out like a fall)

    3.h: a two-col numpy array. The 1st col is time(s). The 2nd col

    is water depth(m)

    4.hU: a two-col numpy array. The 1st col is time(s). The 2nd

    col is discharge(m3/s) or a three-col numpy array, the 2nd col and the 3rd col are velocities(m/s) in x and y direction, respectively.

  • outline_boundary – (str) ‘open’|’rigid’, default outline boundary is open and both h and hU are set as zero

set_case_folder(new_folder=None, make_dir=False)

Initialize, renew, or create case and data folders

Parameters
  • new_folder – (str) renew case and data folder if it is given

  • make_dir – True|False create folders if it is True

set_device_no(device_no=None)

set device no of the model

Parameters

device_no – int or a list of int corresponding to the number of sections

set_gauges_position(gauges_pos=None)

Set coordinates of monitoring gauges

Parameters

gauges_pos – (numpy array) the 1st column is X coordinates, 2nd column is the Y coordinates

set_grid_parameter(**kwargs)

Set grid parameter with Landcover object as name=value

Parameters

kwargs

Keyword Arguments Specified by a Dictionary keyword: name, from grid_parameter_keys

value: 1. scalar, a uniform parameter value
  1. array, gridded parameter value with the same shape

    of the DEM array

  2. dict, contains param_value, land_value, and

    default_value=0

set_initial_condition(parameter_name, parameter_value)

Set initial condition for h0, hU0x, hU0y

Parameters
  • parameter_name – (str) h0, hU0x, hU0y

  • parameter_value – scalar or numpy array with the same size of DEM.

set_landcover(landcover_data)

Set Landcover object with a Raster object or file

Parameters

landcover_data – (string or Raster) A Raster file or its file name of land cover data

set_num_of_sections(num_of_sections)

set the number of divided sections to run a case

It can transfer single-gpu to multi-gpu or the opposite way

Parameters

num_of_sections – (int) number of domains

set_rainfall(rain_mask=None, rain_source=None)

Set rainfall mask and rainfall source

Parameters
  • rain_mask – str [filename of a Raster endswith .gz/asc/tif] numpy int array with the same shape with DEM array a Raster object

  • rain_source – str [filename of a csv file for rainfall source data] numpy array the 1st column is time in seconds, 2nd to the end columns are rainfall rates in m/s.

set_runtime(runtime=None)

set runtime of the model

Parameters

runtime – a list of four values representing start, end, output interval and backup interval respectively

write_boundary_conditions()

Write boundary condtion files

if there are multiple domains, write in the first folder

and copy to others

write_device_file(device_no=None)

Create device_setup.dat for choosing GPU number to run the model

write_gauges_position(gauges_pos=None)

Write the gauges position file

Public version for both single and multiple GPUs

Parameters

gauge_pos – (2-coloumn numpy array) positions of gauges

write_grid_files(file_tag, is_single_gpu=False)

Write grid-based files

Public version for both single and multiple GPUs

Parameters

file_tag – the pure name of a grid-based file

write_halo_file()

Write overlayed cell IDs

write_input_files(file_tag=None)

Write input files

To classify the input files and call functions needed to write each

input files

Parameters

file_tag – a string or list of string giving the name(s) of input files without suffix

write_mesh_file(is_single_gpu=False)

Write mesh file DEM.txt, compatoble for both single and multiple GPU model

write_rainfall_source()

Write rainfall source data

rainfall mask can be written by function write_grid_files

write_runtime_file(time_values=None)

write times_setup.dat file

class IO.InputHipims.InputHipimsSub(dem_array, header, case_folder, num_of_sections)

object for each section, child class of InputHipims

sectionNO

the serial number of each section

_valid_cell_subs

(tuple, int) two numpy array indicating rows and cols of valid cells on the local grid

valid_cell_subsOnGlobal

(tuple, int) two numpy array indicating rows and cols of valid cells on the global grid

shared_cells_id

2-row shared Cells id on a local grid

case_folder

input folder of each section

_outline_cell_subs

(tuple, int) two numpy array indicating rows and cols of valid cells on a local grid

IO.InputHipims.load_input_object(filename)

load object from a dictionary and return as an InputHipims object :param filename: a string giving the object file name

Returns

An object of InputHipims