:py:mod:`wolfhece.hydrology.Catchment` ====================================== .. py:module:: wolfhece.hydrology.Catchment .. autoapi-nested-parse:: Author: HECE - University of Liege, Pierre Archambeau, Christophe Dessers Date: 2024 Copyright (c) 2024 University of Liege. All rights reserved. This script and its content are protected by copyright law. Unauthorized copying or distribution of this file, via any medium, is strictly prohibited. Module Contents --------------- .. py:class:: Catchment(_name, _workingDir, _plotAllSub, _plotNothing, _initWithResults=True, _catchmentFileName='', _rbFileName='', _tz=0, version=cst.VERSION_WOLFHYDRO) This object contains all the information about the Catchment. The Catchment is composed of element that can be: - Subbasin - RetentionBasin In the Catchment the following rules are applied: - there is one and only one outlet. - one element .. py:property:: simulation_intervals :type: list[tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime, wolfhece.hydrology.RetentionBasin.datetime.datetime]] .. py:property:: temporal_parameters :type: tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime, wolfhece.hydrology.RetentionBasin.datetime.datetime] .. py:attribute:: time_delays_F :type: wolfhece.PyParams.np.ndarray .. py:attribute:: _version :type: float .. py:attribute:: charact_watrshd :type: wolfhece.hydrology.PyWatershed.Watershed .. py:attribute:: subBasinCloud :type: wolfhece.PyVertex.cloud_vertices .. py:attribute:: retentionBasinCloud :type: wolfhece.PyVertex.cloud_vertices .. py:attribute:: iP_Cloud :type: wolfhece.PyVertex.cloud_vertices .. py:attribute:: catchmentDict :type: dict[wolfhece.PyParams.Union[str, int], wolfhece.PyParams.Union[wolfhece.hydrology.RetentionBasin.SubBasin, wolfhece.hydrology.RetentionBasin.RetentionBasin]] .. py:attribute:: subBasinDict :type: dict[int, wolfhece.hydrology.RetentionBasin.SubBasin] .. py:attribute:: retentionBasinDict :type: dict[str, wolfhece.hydrology.RetentionBasin.RetentionBasin] .. py:method:: get_subBasin(id_sorted_or_name: int | str) -> wolfhece.hydrology.RetentionBasin.SubBasin This method returns the subbasin object associated with the sorted id or name given in argument. The sorted id is the one given by the Fortran code. .. py:method:: get_time() This method saves the time characteristics read in the .param file and build a time array. The convention used for the time written in the .param is as follow: YYYYMMDD-HHMMSS It is important to notice that the dateBegin and dateEnd are converted in GMT+0 Internal variables modified : self.deltaT, self.dateBegin, self.dateEnd, self.time. NB : If any change in the convention is mentionned in the comment following the dates the code will return an error Otherwise, no procedure will warn the user that a converntion is modified. .. py:method:: get_rain(workingDir) .. py:method:: get_hyeto(fileName) .. py:method:: init_dictIdConversion(workingDir) Procedure that converts the Id of the intersection points in the input file into the sorted sub-basin ids file read: simul_sorted_interior_points.txt Internal variables modified: self.dictIdConversion The conversion dictionnary has the given form: self.dictIdConversion[Internal Point id] = sorted subbasin from the lowest to the highest .. py:method:: create_ObjectsInCatchment() Procedure which creates the objects in the dictionnaries of the subbasins and the RB and each object are pointed in the global catchment dictionnary. This procedre also create the 1st level of the Topo dictionnary. Internal variables modified: subBasinDict, retentionBasinDict, self.catchmentDict, .. py:method:: _fill_cloud_retentionbasin() This procedure fills the cloud of the retention basin with the vertices of the retention basin and its inlets. .. py:method:: get_retentionbasin_zones() -> wolfhece.wolf_array.Zones This method returns a Zones instance of the retention basins. .. py:method:: link_objects() This procedure link all the subbasins and the retention basin altogether to form a network. If a subbasin without inlet whatsoever is detected, one adds it to the first level of the Topology tree. Internal variables modified: subBasinDict, retentionBasinDict, topologyDict .. py:method:: complete_topoDict() Procedure that finish to complete the topo tree. Before calling this procedure, only the first level were completed in self.link_objects(). Modified internal variables: self.topologyDict Strategy: - We save the element on a certain level if all his inlets have inferior levels. TO DO: Add a test that counts the number of subbasins and check if the number is right or not -> take into account the fact that a subbasin can be the last element in this computation. .. py:method:: construct_hydro(firstLevel=1, lastLevel=-1, fromStation: str = '', updateAll: bool = False) This procedure will use the topo tree to build the hydrographs of all elements Internal variable changed: self.catchmentDict .. py:method:: read_Jsonfile(fileName) Function which reads a json file as input .. py:method:: save_ExcelFile() Procedure that saves the data in an Excel file. .. py:method:: save_ExcelFile_noLagTime() Procedure that saves the data in an Excel file. .. py:method:: save_ExcelFile_inlets_noLagTime() Procedure that saves the inlets in an Excel file. .. py:method:: save_ExcelFile_V2() Procedure that saves the data in an Excel file. .. py:method:: save_ExcelFile_Vesdre_simul2D(fileName='PostProcess/Data_simul2D.xlsx', directory='') Procedure that saves the data in an Excel file. .. py:method:: save_ExcelFile_Vesdre_all(fileName='PostProcess/Data_simul2D.xlsx', directory='') Procedure that saves the data in an Excel file. .. py:method:: save_hydro_for_2D(fileName: str = 'Hydros_2_simul2D.txt', directory: str = '', format: str = '%1.5e') Procedure that saves the data in an text file that can be read and used in a 2D model. :param fileName: The name of the file to save the data to. Defaults to "Hydros_2_simul2D.txt". :type fileName: str, optional :param directory: The directory to save the file in. Defaults to an empty string. :type directory: str, optional :returns: None .. py:method:: save_own_hydro_for_2D(fileName: str = 'HydrosSub_2_simul2D.txt', directory: str = '', format: str = '%1.5e') Saves subbasins' hydrographs from their own drained surface only (not taking into account the surface drained by the inlets or upstream elements) to a text file that can be read and used in a 2D model. :param fileName: Name of the output file. Defaults to "HydrosSub_2_simul2D.txt". :type fileName: str, optional :param directory: Directory where the file will be saved. Defaults to an empty string. :type directory: str, optional :param format: Format string for the data values. Defaults to '%1.5e'. :type format: str, optional :returns: None .. py:method:: save_characteristics() Procedure that saves the data in an Excel file. .. py:method:: read_dbfFile(fileName) .. py:method:: init_hyetoDict() Procedure that saves the all the hyeto data of the Catchment in a dictionnary Internal variables modified: self.hyetoDict Structure du dictionnaire self.hyetoDict: - Ordered To Nb: self.hyetoDict['Ordered To Nb'][nb] = iD - iD = hyeto nb of the file to read in the folder "Whole_basin". E.g.: the file "[iD]evap.hyeto" - nb = hyeto number sorted from 1 to nbHyeto. E.g.: if iD=['2', '5', '7'] => self.hyetoDict['Ordered To Nb'][2] = '5' - Hyetos : self.hyetoDict['Hyetos'][nb] - time: time array read in the .hyeto file - rain: rain array read in the .hyeto file TO DO: Consider a more general way to detect .dbf files. E.G. when the data are read in NetCDF files. .. py:method:: add_rainToAllObjects() Add rain and hyetographs to all subbasins .. py:method:: plot_intersection(rangeData=[], plot_raw=True, tzPlot=0, axis: str = 'Datetime', show: bool = True) This procedure will plot all the subbasins or RB with level>1 in the topo tree. .. py:method:: plot_allSub(withEvap=False, withCt=False, selection_by_iD=[], graph_title='', show=True, writeDir='', figure=None, Measures=[]) This procedure plots the hydrographs and hyetographs of all subbasins .. py:method:: plot_allJct(withEvap=False, selection_by_key=[], graph_title='', show=True, writeDir='', figure=None, Measures=[], Measure_unit='m3/s', addTable=False, rangeData=[]) This procedure plots the hydrographs and hyetographs of all junctions .. py:method:: draw_flowChart(flowchart) This procedure save and plot a flowchart representing the topo tree input: - flowchart: graphviz.Digraph Object -> modified at the end .. py:method:: make_stat_distributionOfslope() This procedure plot the stat distribution of slopes. .. py:method:: make_stat_distributionOfTime() This procedure plot the stat distribution of slopes. .. py:method:: check_massConservation() This procedure check whether the mass conservation is verified ot not. .. py:method:: copy() .. py:method:: get_time_btw_ssbasins(stationNames=[], unit='h', ref=[]) Returns the transfer time between susBasin modules .. py:method:: operation_on_param_file(fileName, which, operation=None) .. py:method:: _correct_Umax_from_old_model(adapt_with_rain: bool = True, k_opt: float = 0.0, U_max_opt=0.0) .. py:method:: plot_all_diff_cumulRain_with_lagtime(interval=0, lagTime=0, selection_by_iD=[], graph_title='', show=True, writeDir='', lawNetRain=0, netRainParams={}) .. py:method:: get_all_cumulRain(selection_by_iD=[]) -> tuple[wolfhece.PyParams.np.array, list[wolfhece.PyParams.np.array]] .. py:method:: read_measuring_stations_SPW(fileNameIn='') Function that read the stations, their characteristics and locations and store all information in a dictionnary .. py:method:: get_eff_subBasin() .. py:method:: get_one_surfaces_proportions(whichName) .. py:method:: update_hydro(idCompar, fromLevel: bool = False, level_min: int = 1) .. py:method:: get_cvg(pointerData) .. py:method:: define_station_out(stationOut) .. py:method:: sort_level_given_junctions(givenJct: list, changeNames=False) .. py:method:: construct_surfaceDrainedHydro_RB() .. py:method:: activate_usefulSubs(mask=[], blockJunction=[], onlyItself: bool = False) .. py:method:: get_key_catchmentDict(name) .. py:method:: get_keys_catchmentDict(names: list) .. py:method:: write_eff_subBasin() .. py:method:: read_hydro_eff_subBasin() .. py:method:: update_timeDelay(stationName, value=0.0, reset=False) .. py:method:: update_timeDelays_from_F(stationName, value=0.0, reset=False) .. py:method:: reset_timeDelay(stationOut='') .. py:method:: get_inletsName(stationOut) .. py:method:: get_all_timeDelay(ref='') .. py:method:: get_timeDelays_inlets(ref: str = '') -> dict[str, float] .. py:method:: save_timeDelays(junctionList: list) .. py:method:: get_lastJunctionKey() .. py:method:: set_timeDelays(method='wolf_array', junctionKey='', readWolf: bool = True, updateAll: bool = False) .. py:method:: find_all_timeDelayObj() .. py:method:: plot_landuses(selection_by_iD: list = [], graph_title: str = '', onlySub: bool = True, show: bool = True, writeDir: str = '', figure=None) .. py:method:: read_all_landuses() .. py:method:: build_compare_file(hydroFile: str, unit: str = 'mm/h', otherSurf: float = 0.0, lag: int = 0, junction: str = '', dateBegin: wolfhece.hydrology.RetentionBasin.datetime.datetime = None, dateEnd: wolfhece.hydrology.RetentionBasin.datetime.datetime = None, deltaT: wolfhece.hydrology.RetentionBasin.datetime.timedelta = None) .. py:method:: change_version(newVersion=None) .. py:method:: get_version() .. py:method:: get_sub_Nash(measure: wolfhece.hydrology.RetentionBasin.SubBasin, selection_by_iD, intervals: list[tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime]] = []) .. py:method:: get_sub_peak(selection_by_iD, intervals: list[tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime]] = []) .. py:method:: set_eff_outlet_coord() .. py:method:: update_charact_watrshd() .. py:method:: get_all_x_production(selection_by_iD: list = [], to_save: bool = True, to_plot: bool = False) -> dict Retrieves the x production values for all sub-basins or a specific selection of sub-basins. :param selection_by_iD: A list of sub-basin IDs to retrieve x production values for. If empty, retrieves x production values for all sub-basins. Defaults to []. :type selection_by_iD: list, optional :returns: A dictionary containing the sub-basin names or IDs as keys and their corresponding x production values as values. :rtype: dict .. py:method:: get_all_fractions(plt_dict: dict[str:np.array] = {}, selection_by_iD: list = [], to_save: bool = True, to_plot: bool = False, summary: str = None, summary_interval: list[wolfhece.hydrology.RetentionBasin.datetime.datetime] = None, add_info: dict[dict[str, float]] = {}) -> dict Retrieves the physical flux fractions values for all sub-basins or a specific selection of sub-basins. :param selection_by_iD: A list of sub-basin IDs to retrieve fractions values for. If empty, retrieves fractions values for all sub-basins. Defaults to []. :type selection_by_iD: list, optional :returns: A dictionary containing the sub-basin names or IDs as keys and their corresponding fractions values as values. :rtype: dict .. py:method:: plot_all_fractions(all_fractions: dict[str:np.array] = {}, selection_by_iD: list = [], to_show: bool = False, writeDir: str = '', range_data: list[wolfhece.hydrology.RetentionBasin.datetime.datetime] = []) .. py:method:: get_all_iv_production(selection_by_iD: list = [], to_save: bool = True) -> dict Retrieves the x production values for all sub-basins or a specific selection of sub-basins. :param selection_by_iD: A list of sub-basin IDs to retrieve x production values for. If empty, retrieves x production values for all sub-basins. Defaults to []. :type selection_by_iD: list, optional :returns: A dictionary containing the sub-basin names or IDs as keys and their corresponding x production values as values. :rtype: dict .. py:method:: activate_all_internal_variables(selection_by_iD: list = []) -> dict Activates all internal variables for all sub-basins or a specific selection of sub-basins. :param selection_by_iD: A list of sub-basin IDs to activate internal variables for. If empty, activates internal variables for all sub-basins. Defaults to []. :type selection_by_iD: list, optional :returns: A dictionary containing the sub-basin names or IDs as keys and their corresponding internal variables as values. :rtype: dict .. py:method:: check_presence_of_iv(selection_by_iD: list = []) -> dict Checks the presence of internal variables for all sub-basins or a specific selection of sub-basins. :param selection_by_iD: A list of sub-basin IDs to check the presence of internal variables for. If empty, checks the presence of internal variables for all sub-basins. Defaults to []. :type selection_by_iD: list, optional :returns: A dictionary containing the sub-basin names or IDs as keys and their corresponding internal variables as values. :rtype: dict .. py:method:: get_all_Qtest(selection_by_iD: list = [], nb_atttempts: int = -1) .. py:method:: _get_simulation_intervals() This procedure is getting the simulation intervals of the current module. .. py:method:: _set_simulation_intervals(simulation_intervals: list[tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime, wolfhece.hydrology.RetentionBasin.datetime.datetime]]) This procedure is setting the simulation intervals of the current module. .. py:method:: _get_temporal_parameters() -> tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime, wolfhece.hydrology.RetentionBasin.datetime.datetime] This procedure is getting the temporal parameters of the current module. .. py:method:: _set_temporal_parameters(simulation_intervals: tuple[wolfhece.hydrology.RetentionBasin.datetime.datetime, wolfhece.hydrology.RetentionBasin.datetime.datetime]) This procedure is setting the temporal parameters of the current module. .. py:method:: _set_IC_qif(keys: list[str], values: wolfhece.PyParams.np.ndarray) .. py:method:: make_nd_array(c_pointer, shape, dtype=np.float64, order='C', own_data=True, readonly=False)