Alpine3D

Alpine3D Svn Source Tree

Root/trunk/alpine3d/runoff/Runoff.h

1/***********************************************************************************/
2/* Copyright 2009-2015 WSL Institute for Snow and Avalanche Research SLF-DAVOS */
3/***********************************************************************************/
4/* This file is part of Alpine3D.
5 Alpine3D is free software: you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 Alpine3D is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public License
16 along with Alpine3D. If not, see <http://www.gnu.org/licenses/>.
17*/
18#ifndef RUNOFF_H
19#define RUNOFF_H
20
21#include <iostream>
22#include <vector>
23#include <map>
24#include <limits>
25#include <sstream>
26#include <meteoio/MeteoIO.h>
27#include <alpine3d/SnowpackInterface.h>
28#include <alpine3d/SnowpackInterfaceWorker.h>
29
30typedef unsigned long long longuint;
31
32class SnowpackInterface; // forward declaration, cyclic header include
33
34/**
35 * @page runoff Runoff
36 * This module computes the pure runoff from each cell or group of cells or a hydrological discharge (see \ref principles_runoff).
37 * It is also possible to perform hydrological modeling with the PREVAH system forced with the runoff grids produced by Alpine3D
38 * (see \ref prevah_runoff "PREVAH hydrological modeling").
39 *
40 * @section runoff_grid Runoff grid
41 * In order to use the Alpine3D generated runoff as input for a hydrological model, it is often necessary to write out the generated
42 * runoff at each cell and timesteps. This is done by setting the WRITE_RUNOFF_GRIDS key to true in the [Output] section. The grids will be
43 * in the ARC ascii format by default but this can be configured with the RUNOFF_GRID2D key. The path where to write the grids <b>must</b> be
44 * provided thanks to the RUNOFF_GRID2DPATH key. For example, to write per-pixel generated runoff grids in the ARC ascii format:
45 *
46 * @code
47 * [Output]
48 * WRITE_RUNOFF_GRIDS = true
49 * RUNOFF_GRID2D = ARC
50 * RUNOFF_GRID2DPATH = ../output/runoff
51 * @endcode
52 *
53 * @section runoff_sums Sub-catchments runoff sums
54 * In order to work with multiple catchments, it is possible to write out the sum of all the runoff generated within a given sub-catchment.
55 * The sub-catchments must be properly defined before as shown in the \ref sub_catch_input "sub-catchments inputs" section. Then these sums
56 * will be written out in a SMET file that contains both the total runoff (from the bottom of the snow/soil column)
57 * as well as the precipitation, snow melt and glacier melt components (these ones at the bottom of the snow column only, ie from the surface runoff).
58 * Please note that the total runoff is at the bottom of the snow/soil column while the splitting (precipitation, snowmelt and glacier melt) are at the snow/soil interface
59 * (ie surface runoff), therefore the sum of the components is smaller than the total runoff (ie some of the runoff could not be classified).
60 *
61 * In order to write the runoff sums at each time step, it is necessary to define the following keys:
62 * - CATCHMENT, in the [Input] section that gives the path and filename of the catchment definition grid;
63 * - CATCHMENTS_PATH, in the [Ouput] section that gives the path where to write the sub-catchments sums (one SMET file per sub-catchment)
64 * - CATCHMENT_NUMBERING (optional), in the [Input] section, which specifies which numbering scheme is used by the catchment definition grid
65 * to identify the individual sub-catchments. Two values are possible for this key: ALPINE3D_OLD (if the catchments are numbered with series
66 * of powers of 2, as described in the \ref sub_catch_input "sub-catchments inputs" section), or TAUDEM (if the catchments are identified
67 * with unique numbers, which are not required to be continuous)
68 *
69 * On top of the runoff components, additional variables can optionally be averaged over each sub-catchment area and written in the output files
70 * at each time step. These variables must be specified using key RUNOFF_FILES_EXTRA_DATA, which accepts the standard meteorological variables
71 * (TA, RH, VW, ILWR, etc.) along with T_SOIL, which corresponds to the soil temperature at a certain depth. In case T_SOIL is present, the depths
72 * (in meters) at which soil temperature should be returned must be specified using key SOIL_TEMPERATURE_DEPTHS:
73 *
74 * @code
75 * [Output]
76 * RUNOFF_FILES_EXTRA_DATA = TA RH ISWR T_SOIL
77 * SOIL_TEMPERATURE_DEPTHS = 5 7.5 ; meters
78 * @endcode
79 *
80 */
81
82class Runoff
83{
84public:
85Runoff(const mio::Config& in_cfg, const mio::DEMObject& in_dem,
86 const double& in_thresh_rain);
87Runoff(const Runoff& copy);
88
89// Methods to set other modules
90void setSnowPack(SnowpackInterface &sn_interface);
91
92virtual void output(const mio::Date& i_date, const mio::Grid2DObject& psum,
93 const mio::Grid2DObject& ta, mio::IOManager& io_in);
94virtual ~Runoff();
95
96std::string getGridsRequirements() const;
97double getTiming() const;
98
99protected:
100mio::IOManager *io;
101SnowpackInterface *snowpack; ///< Reference to SnowpackInterface object, used for callbacks, initialized during construction
102
103const double thresh_rain;
104const double tz_out;
105bool output_grids; //< output grid of runoff data? (for taking it over with an external hydro model)
106bool output_sums; //< output total runoff per subcatchment?
107std::string catchment_out_path; //< folder in which the extracted catchment sums should be written
108double resampling_cell_size; //< cell size [m] to which the runoff grids should be resampled
109double grid_size_factor;
110const size_t n_grid_cells;
111enum NumberingType {Alpine3DOld, TauDEM} const catchment_numbering;
112
113mio::Timer timer;
114const mio::Grid2DObject slope_correction;
115const bool is_glacier_mask_dynamic;
116bool is_glacier_mask_set;
117mio::Grid2DObject total_runoff, glacier_mask;
118std::vector<SnGrids::Parameters> extra_meteo_variables;
119size_t n_extra_meteo_variables;
120std::map<size_t, mio::Grid2DObject> catchment_masks;
121bool use_external_iomanager_for_grids; // To know if the same io manager than for the other grids must be used
122 // (to avoid having multiple netcdf files open)
123static const double MIN_CELL_SIZE; //< [m] two points closer to each other than this value will be assumed to overlap
124static const double DISTANCE_ABSOLUTE_PRECISION; //< [m] minimum size of a grid cell
125
126virtual void constructCatchmentMasks(mio::Grid2DObject catchmentGrid);
127virtual void updateTotalRunoffGrid();
128virtual void updateGlacierMask();
129virtual mio::Grid2DObject computePrecipRunoff(const mio::Grid2DObject& psum, const mio::Grid2DObject& ta) const;
130virtual void getExtraMeteoGrids(std::vector<mio::Grid2DObject>& grids) const;
131virtual void initializeOutputFiles(const mio::Grid2DObject& dem) const;
132virtual void updateOutputFile(const size_t& catchId, const mio::Date& currTime,
133 const double& totalRunoff, const double& precipRunoff,
134 const double& snowRunoff, const double& glacierRunoff,
135 const std::vector<double>& meteoVars) const;
136
137static mio::IOManager* getIOManager(mio::Config in_cfg, const bool& outputGrids);
138static mio::Grid2DObject getSlopeCorrection(const mio::DEMObject& dem);
139static NumberingType getCatchmentNumberingScheme(const mio::Config& in_cfg);
140static bool getIsGlacierDynamic(const mio::Config& cfg);
141static std::vector<SnGrids::Parameters> getExtraMeteoVariables(const mio::Config& cfg);
142static double getResamplingCellSize(const mio::DEMObject& in_dem, const mio::Grid2DObject& catchments);
143static bool isMultiple(const double& a, const double& b);
144static double estimateResamplingCellSize(const double& llOffset, const double& currSizeEstimate);
145static std::vector<size_t> factorizeCatchmentNumber(longuint value);
146static void cropMask(mio::Grid2DObject& mask);
147static double sumOverMask(const mio::Grid2DObject& grid, const mio::Grid2DObject& mask);
148static double averageOverMask(const mio::Grid2DObject& grid, const mio::Grid2DObject& mask);
149
150private:
151Runoff& operator=(const Runoff&) {return *this;} //< private in order to avoid being used and suppress compiler warning
152};
153
154#endif

Archive Download this file

Revision: HEAD