HydroCNHS package

HydroCNHS.abm module

class HydroCNHS.abm.Base(**kwargs)

Bases: object

Agent_type class’s available items: * name: agent’s name. * config: agent’s configuration dictionary the model file (.yaml). * start_date: datetime object. * data_length: length of the simulation. * data_collector: a container to store simulated data. * rn_gen: random number generator to ensure reproducibility (e.g., * self.rn_gen.random()). Note that do NOT set a global random seed in * this module! All type of random number should be created by “rn_gen.” * dm: decision making object if assigned in the model file (.yaml).

Decision-making class’s available items:

  • start_date: datetime object.

  • data_length: length of the simulation.

  • abm: the ABM configuration dictionary from the model file (.yaml).

  • data_collector: a container to store simulated data.

  • rn_gen: random number generator to ensure reproducibility (e.g.,

  • self.rn_gen.random()). Note that do NOT set a global random seed in

  • this module! All type of random number should be created by “rn_gen.

class HydroCNHS.abm.agent

Bases: object

HydroCNHS.abm.read_factor(ag_config, outlet)

Read factor from agent’s ag_config at a given outlet.

The function will automatically parse the list-like value assignment. e.g., [ReturnFactor, 0, Plus].

ag_configdict

Agent’s configuration.

outletstr

Outlet name.

HydroCNHS.abm_script module

HydroCNHS.abm_script.add_agt_class(agt_type)
HydroCNHS.abm_script.add_dm_class(dm_type, is_institution=False)

HydroCNHS.data_collector module

class HydroCNHS.data_collector.Data_collector

Bases: object

add_field(field, data_type={}, desc=None, unit=None, check_exist=True)

Add a field to the data collector.

A field can be a dictionary or a list. A Data_collector object cannot have duplicated field name.

fieldstr

Field name. Cannot have space in a field name.

data_typedict, optional

Data type of the field (e.g., {} and []), by default {}. User can also populate the field by directly assigning data here.

descstr

Field description.

unit

Unit of the field.

check_existbool, optional

If Ture, check the given field name is not existed before adding, by default True.

del_field(field)

Delete a field from the data collector.

fieldstr

Field name.

get_dict(copy=False)

Get data collector in dictionary format.

Note that if copy=False, any modification on a variable assigned with the returned dictionary will also affect the data stored in the data collector object.

copystr

If true, a copy of dictionary will be returned, else a pointer will be returned. Default False.

dict

A dictionary contains all fields.

get_field(field, copy=False)

Get a field.

This function create a shortcut to access a field. Namely, changes of a local variable of get_field() will be accumulated back to the original data_collector. copy=Ture if a copy of a field is needed.

fieldstr

Field name.

copybool

If true, create a copy of a field, which has seperate storage

pointer than the original data_collector. Otherwise, return a shortcut of a field to the original data_collector. Returns ——- Assigned field type.

list_fields()

Print available fields in the data collector.

HydroCNHS.hydrocnhs module

class HydroCNHS.hydrocnhs.Model(model, name=None, rn_gen=None, checked=False, parsed=False, log_filename=None)

Bases: object

get_model_object()

Get the model object in a dictionary form.

dict

model object dictionary.

load_weather_data(temp, prec, pet=None, outlets=[])

Load temperature, precipitation, and otential evapotranpiration data.

tempdict

[degC] Daily mean temperature time series data (value) for each subbasin named by its outlet. E.g., {“subbasin1”:[…], “subbasin2”:[…]}

precdict

[cm] Daily precipitation time series data (value) for each subbasin named by its outlet. E.g., {“subbasin1”:[…], “subbasin2”:[…]}

petdict, optional

[cm] Daily potential evapotranpiration time series data (value) for each subbasin named by its outlet, by default None. E.g., {“subbasin1”:[…], “subbasin2”:[…]}

run(temp, prec, pet=None, assigned_Q={}, assigned_UH={}, disable=False)

Run HydroCNHS simulation.

tempdict

[degC] Daily mean temperature.

precdict

[cm] Daily precipitation.

petdict, optional

[cm] Potential evapotranspiration, by default None. If none, pet is calculted by Hamon’s method.

assigned_Qdict, optional

[cms] If user want to manually assign Q for certain outlets {“outlet”: array}, by default {}.

assigned_UHdict, optional

If user want to manually assign UH (Lohmann) for certain outlet {“outlet”: array}, by default {}.

disablebool, optional

Disable display progress bar, by default False.

dict

A dictionary of flow time series.

HydroCNHS.indicators module

class HydroCNHS.indicators.Indicator

Bases: object

static CP(x_obv, y_sim, r_na=False)

Correlation of persistence.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Correlation of persistence.

static KGE(x_obv, y_sim, r_na=True)

Kling–Gupta efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Kling–Gupta efficiency.

static NSE(x_obv, y_sim, r_na=False)

Nash–Sutcliffe efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Nash–Sutcliffe efficiency.

static RSR(x_obv, y_sim, r_na=False)

RMSE-observations standard deviation ratio.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

RMSE-observations standard deviation ratio.

static cal_indicator_df(x_obv, y_sim, index_name='value', indicators_list=None, r_na=True)
static iKGE(x_obv, y_sim, r_na=True)

Inverse Kling–Gupta efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Inverse Kling–Gupta efficiency.

static iNSE(x_obv, y_sim, r_na=False)

Inverse Nash–Sutcliffe efficiency.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Inverse Nash–Sutcliffe efficiency.

static r(x_obv, y_sim, r_na=True)

Correlation.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

r coefficient.

static r2(x_obv, y_sim, r_na=True)

Coefficient of determination.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

r2 coefficient.

static remove_na(x_obv, y_sim)

Remove nan in x_obv and y_sim.

This function makes sure there is no nan involves in the indicator calculation. If nan is detected, data points will be remove from x_obv and y_sim simultaneously.

x_obvarray

Observation data.

y_simarray

Simulation data.

tuple

Updated (x_obv, y_sim)

static rmse(x_obv, y_sim, r_na=False)

Root mean square error.

x_obvarray

Observation data.

y_simarray

Simulation data.

r_nabool, optional

Remove nan, by default True

float

Root mean square error.

HydroCNHS.model_builder module

class HydroCNHS.model_builder.ModelBuilder(wd)

Bases: object

add_agent(agt_type_class, agt_name, api, priority=1, link_dict={}, dm_class=None, par_dict={}, attr_dict={})

Add agent.

agt_type_classstr

Assigned agent type class.

agt_namestr

Agent name.

apistr

The API to integrate the agent to the HydroCNHS. e.g., mb.Dam.

priorityint, optional

Priority of the agent if conflicts occur, by default 1.

link_dictdict, optional

Linkage dictionary, by default {}.

dm_classstr, optional

Assigned decision-making class, by default None

par_dictdict, optional

Parameter dictionary, by default {}

attr_dictdict, optional

Attribution dictionary, by default {}

add_institution(institution, instit_dm_class, agent_list)

Add a institution.

institutionstr

Institution name.

instit_dm_classstr

Assigned institutional decision-making class.

agent_listlist

Agent member list of the institute.

gen_ABM_module_template()

Generate ABM module template based on the ABM setting.

help()
print_model(indentor='  ', level=1)

Print model to the console

indentorstr, optional

Indentor, by default ” “.

levelint, optional

Print out level of a nested dictionary, by default 1.

set_ABM(abm_module_folder_path=None, abm_module_name='ABM_module.py')

Set up ABM

abm_module_folder_pathstr, optional

Folder directory of ABM modules. It it is not given, working directory will be assigned, by default None.

abm_module_namestr, optional

The ABM module name, by default “ABM_module.py”

set_rainfall_runoff(outlet_list, area_list=None, lat_list=None, runoff_model='GWLF')

Set up RainfallRunoff.

outlet_listlist

A list of subbasin outlet names.

area_listlist, optional

Area [ha] list corresponding to outlet_list, by default None.

lat_liststr, optional

Latitude [deg] list corresponding to outlet_list, by default None.

runoff_modelstr, optional

“GWLF” or “ABCD” or “Other”, by default None.

Note

If “Other” is selected for runoff_model, users must provide precalculated runoffs for each subbasin as an input to HydroCNHS.

set_routing_outlet(routing_outlet, upstream_outlet_list, instream_objects=[], flow_length_list=None, routing_model='Lohmann')

Set up a routing outlet.

routing_outletstr

Name of routing outlet. routing_outlet should be one of outlets in RainfallRunoff.

upstream_outlet_listlist

A list of outlets or dam agents that contribute to the streamflow at routing_outlet.

instream_objectslist, optional

A list of instream objects’ names (i.e., dam agents), by default [].

flow_length_listlist, optional

A list of flow lengths. The order has to consist to the upstream_outlet_list.

routing_modellist, optional

Routing model, by default “Lohmann”.

set_water_system(start_date, end_date)

Set up WaterSystem.

start_datestr

“yyyy/mm/dd”

end_datestr

“yyyy/mm/dd”

write_model_to_yaml(filename)

Output model configuration file (.yaml)

filenamestr

Filename

HydroCNHS.routing module

HydroCNHS.routing.form_UH_Lohmann(inputs, routing_pars, force_ingrid_off=False)

Derive HRU’s UH at the (watershed) outlet.

inputsdict

Inputs dictionary containing FlowLength [m] Travel distence of flow between two outlets [float] and InstreamControl [bool].

routing_parsdict

Four parameters for routing: GShape, GScale, Velo, Diff [float]

force_ingrid_offbool, optional

If True, then within subbasin routing will be forced to turn off, by default False.

HydroCNHS.routing.run_step_Lohmann(routing_outlet, routing, UH_Lohmann, Q, Q_runoff, t)

Calculate a single time step routing for a given routing_outlet at time t.

routing_outletstr

routing outlet.

routingdict

Routing setting dictionary from model.yaml file.

UH_Lohmanndict

A dictionary containing pre-formed UHs.

Qdict

A dictionary containing newest routed flows.

Q_runoffdict

A dictionary containing newest unrouted flows without.

tint

Index of current time step [day].

float

Routed flow of routing_outlet at time t.

HydroCNHS.routing.run_step_Lohmann_convey(routing_outlet, routing, UH_Lohmann_convey, Q_convey, t)

Calculate a single time step conveying water routing for a given routing_outlet at time t.

routing_outletstr

routing outlet.

routingdict

Routing setting dictionary from model.yaml file.

UH_Lohmann_conveydict

A dictionary containing pre-formed conveying UHs (i.e., no within subbasin routing).

Q_conveydict

A dictionary containing conveying water.

tint

Index of current time step [day].

float

Routed conveying flow of routing_outlet at time t.

HydroCNHS.util module

HydroCNHS.util.check_RainfallRunoff(model_dict)
HydroCNHS.util.check_WS(model_dict)
HydroCNHS.util.check_agent_in_routing(model_dict)
HydroCNHS.util.check_model(model_dict)

Check the model dictionary

model_dictdict

Model dictionary

bool

True if pass the check.

HydroCNHS.util.create_rn_gen(seed)

Create random number generator based on numpy module.

seedint

Random seed.

object

Random number generator.

HydroCNHS.util.dict_to_string(dictionary, indentor='  ', level=1)

Ture a dictionary into a printable string.

dictionarydict

A dictionary.

indentorstr, optional

Indentor, by default ” “

str

String.

HydroCNHS.util.form_sim_seq(node_list, back_tracking_dict)
HydroCNHS.util.gen_default_bounds(model_dict, key_option=['Pars'])

Generate default parameter bounds in the format of a list of DataFrames.

model_dictdict

Model dictionary.

key_optionlist, optional

Output sections (e.g., Pars, Inputs, Attributes), by default [“Pars”].

tuple

A list of parameter bound DataFrames, A list of DataFrame names.

HydroCNHS.util.list_callable_public_object(obj)
HydroCNHS.util.load_customized_module_to_class(Class, module_name, path)

Load classes and functions in a user defined module (.py) into a given Class.

Classclass

A class to collect classes and functions in a given module.

module_namestr

filename.py or filename.

pathstr

Directory of filename.py.

HydroCNHS.util.load_df_to_model_dict(model_dict, df, section, key)

Load dataframe to model dictionary.

Note that the column and index names have to be identical as outputted from write_model_to_df() function.

model_dictdict

Model dictionary.

dfDataFrame

Dataframe.

sectionstr

RainfallRunoff or Routing or ABM.

keystr

nputs or Pars or Attributes.

dict

Updated model_dict.

HydroCNHS.util.load_model(model, checked=False, parsed=False, print_summary=True)

Load model.yaml or model dictionary.

modelstr/dict

Filename (e.g., model.yaml) or model dictionary.

checkedbool, optional

If True, no pre-check will be implemented, by default False.

parsedbool, optional

If True, model will not be re-parses, by default False.

print_summarybool, optional

Print the summary of loaded model, by default True.

dict

Model dictionary.

HydroCNHS.util.parse_model(model_dict, print_summary=True)

Parse model dictionary. Populate SystemParsedData.

Args:

model_dict (dict): Load from model.yaml.

Returns:

dict: model_dict

HydroCNHS.util.parse_sim_seq(model_dict, print_summary=True)
HydroCNHS.util.set_logging_config(log_filename=None)

Set up logging config.

log_filenamestr, optional

Log filename, by default None

HydroCNHS.util.update_sim_seq_with_group(sim_seq, group, back_tracking_dict)
HydroCNHS.util.write_model(model_dict, filename, org_model=None)

Write model dictionary to .yaml file

If org_model is given, comments in the original file will be kept in the output model file.

model_dictdict

Model dictionary.

filenamestr

Model configuration filename (e.g. model.yaml).

org_modelstr, optional

Original model name (e.g. org_model.yaml), by default None.

Common error :
  1. value type is numpy.float64 => convert it to float.

HydroCNHS.util.write_model_to_csv(folder_path, model_dict, key_option=['Pars'], prefix='')

Write model (dictionary) to csv files.

folder_pathstr

Output folder directory.

model_dictdict

Model dictionary.

key_optionlist, optional

Output sections (e.g., Pars, Inputs, Attributes), by default [“Pars”].

prefixstr, optional

Prefix for the filenames, by default “”.

list

A list of filenames.

HydroCNHS.util.write_model_to_df(model_dict, key_option=['Pars'], prefix='')

Write model dictionary to dataframes given key options.

This function will convert model dictionary to dataframes according to user’s specified sections (key_option).

model_dictdict

Model dictionary.

key_optionlist, optional

Output sections (e.g., Pars, Inputs, Attributes), by default [“Pars”].

prefixstr, optional

Prefix for the filenames, by default “”.

HydroCNHS.visual module

class HydroCNHS.visual.Visual

Bases: object

Collection of some plotting functions.

static plot_reg(x_obv, y_sim, title=None, xy_labal=None, same_xy_limit=True, return_reg_par=False, save_fig_path=None, show=True)

Plot regression.

x_obvarray

Observation data.

y_simarray

Simulation data.

titlestr, optional

Title, by default None.

xy_laballist, optional

List of x and y labels, by default None.

same_xy_limitbool, optional

If True same limit will be applied to x and y axis, by default True.

return_reg_parbool, optional

If True, slope and interception will be return, by default False.

save_fig_pathstr, optional

If given, plot will be save as .png, by default None.

showbool, optional

If True, the plot will be shown in the console, by default True.

ax or list

axis object or [slope, intercept].

static plot_simple_ts(df, title=None, xy_labal=None, data_dots=True, save_fig_path=None, **kwargs)

Plot timeseries.

dfDataFrame

Dataframe.

titlestr, optional

Title, by default None.

xy_laballist, optional

List of x and y labels, by default None.

data_dotsbool, optional

If Ture, show data marker, by default True.

save_fig_pathstr, optional

If given, plot will be save as .png, by default None.

object

axis object.

static plot_timeseries(x_obv, y_sim, xticks=None, title=None, xy_labal=None, save_fig_path=None, legend=True, show=True, **kwargs)

Plot timeseries.

This function can plot two DataFrames with same column names.

x_obvarray/DataFrame

Observation data.

y_simarray/DataFrame

Simulation data.

xtickslist, optional

Ticks for x-axis, by default None.

titlestr, optional

Title, by default None.

xy_laballist, optional

List of x and y labels, by default None.

save_fig_pathstr, optional

If given, plot will be save as .png, by default None.

legendbool, optional

If True, plot legend, by default None.

showbool, optional

If True, the plot will be shown in the console, by default True.

kwargsoptional

Other keywords for matplotlib.

object

axis object.

Module contents