smashbox 1.0__py2.py3-none-any.whl

smashbox/tutorials/R_Graffas_tutorial.md

@@ -0,0 +1,153 @@
+Schypre-Graffas-SmashBox coupling and discharges quantile compuation
+---------------------------------------------------------------------
+
+This section contains a R tutorials to connect a Schypre/Graffas simulation with Smash using SmashBox environment. In this tutorial, we are going to use a long chronicle of rainfall data stored in a matrix with Smash, simulate the discharges at every pixel of the domain and compute the discharges quantiles.
+
+To use smashbox with R, you must load the module with the Reticulate package.
+
+First of all, launch the R console, load the Reticulate package and load your Python environment where SmashBox and Smash are installed (change the path according your installation).
+
+```R
+library(reticulate)
+use_virtualenv("path/to/pythonenv/smashbox_env") #use a specific python environnement
+```
+
+Then load the package EsaySmash
+
+```R
+smashbox <- import("smashbox")
+```
+
+Now we are going to load results from a Schypre/Graffas simulation. This simulation has been done on the Gapeau catchment (France) and is stored in a Rdata file.
+
+```R
+path_to_graffas_rainfall="/nas/RHAX/UTILISATEURS/kevin.tartour/2025_Graffas/SPATIAL/Gapeau/DataOutput/simul/RRsim_Gapeau_calage_reso_1000_res_1000_twin1_SMASH.Rdata"
+GraffasRainfall=load(path_to_graffas_rainfall)
+```
+This Rdata file contains 3 elements: 
+* `info_simu_smash`: information about the mesh
+* `RRsim_3D`: the 3 dimensional matrix of the rainfall (x,y,nb_time_step)
+* `Calendar` : the list of the date of the rainfall
+
+
+First we need to define the bounding box for Smash from `info_simu_smash`. The bounding box of the Schypre/Graffas model is defined on the center of the cells. The bounding box of Smash is defined from the border of each cell. Thus we need to extend the original domain about the half of the resolution :
+
+```R
+bbox=smashbox$tools$tools$infograffas_bbox_extractor(info_simu_smash)
+
+```
+
+Then we configure the smashbox module. We set the bounding box, select the outlet database and select the outlet shapefile with catchment boundaries.
+
+```R
+es <- smashbox$SmashBox()
+es$myparam$set_param("bbox", bbox)
+```
+We are ready to create a container for your Smash simulation:
+
+```R
+es$newmodel("gapeau")
+```
+
+No need to adjust the setup. By default the setup `setup_rhax_gr4_dt3600` is automatically loaded. 
+
+Then we can build the mesh and add any outlets found in the database:
+
+```R
+es$gapeau$generate_mesh()
+```
+
+Again, few plot can help to validate our mesh:
+
+```R
+es$gapeau$myplot$plot_mesh(fig_settings=list("figname"= "output/mesh.png"))
+es$gapeau$myplot$plot_catchment_surface_error(fig_settings=list("figname"= "output/mesh_surface_error.png"))
+es$gapeau$myplot$plot_catchment_surface_consistency(
+  fig_settings=list("figname"= "output/mesh_surface_consistency.png")
+)
+```
+Let's warm the model, i.e we create a valid initial states. The warmup period is set in days (365) and is prior the `start_time` defined in the setup (default is an arbitrary date: `2014-01-01 00:00`). Precipitation data are read on the disk.
+
+```R
+es$gapeau$model_warmup(warmup=365)
+```
+Initial states are created and stored in the Smash container. These initial states will be loaded automatically when doing a forward_run.
+
+The next steps aims to create a Smash model, simulate the discharges and compute the maximal discharges values every year. Two cases may append, a small domain with a rather "short" data series which will consume a reasonable amount of RAM or a large domain with long data series which consume to much RAM.
+
+### For short periods
+
+For "short" period and/or small domain and if the RAM usage if not a constraint we can perform the simulation and the quantile compuation directly:
+
+```R
+es$gapeau$atmos_data_connector(input_prcp=RRsim_3D)
+es$gapeau$model()
+es$gapeau$forward_run(return_options=list("q_domain"= TRUE))
+es$gapeau$mystats$fquantile_stats(
+        chunk_size=365, estimate_method="MLE", ncpu=6, fit="gumbel", compute_uncertainties=FALSE,
+    )
+```
+Some explanations: we connect to SmashBox the precipitation matrix (the ten first year). Then we create the model using the `model()` function. Then we run the model and we compute the quantile on the whole period once.
+
+### For long periods
+
+Because the matrix contains to many time-steps, we split the calculation in three chunks:
+
+```R
+chunk_size=as.integer(dim(RRsim_3D)[3]/3)
+for (i in 0:2){
+    #send the rainfall data (Graffas) to smash
+    es$gapeau$atmos_data_connector(input_prcp=RRsim_3D[,,(i*chunk_size):((i+1)*chunk_size)])
+    #generate the smash model
+    es$gapeau$model()
+    #run the model with option invert_states=True : we use the final states as initial states except for the 1st chunk
+    es$gapeau$forward_run(invert_states=TRUE,return_options=list("q_domain"= TRUE))
+    #compute the annual maxima over each chunk: use option cumulated_maxima=True to store and accumulate these maxima
+    es$gapeau$mystats$fmaxima_stats(
+            chunk_size=365, cumulated_maxima=TRUE,
+        )
+}
+```
+
+Some explanations: For each chunk we send the rainfall data to Smash using the `atmos_data_connector` function. Then we generate a new model with the function `model()`. Then we run the forward model using two options: `invert_state=TRUE` in order to use the final states of the previous simulated chunk as the initial states of the current one (if not possible, current initial states will be preserved, i.e the warmup). Finally we compute the maximal discharges values for each pixel every 365 days. At the last step we use the option `cumulated_maxima=TRUE` to accumulate these maxima after each call of `fmaxima_stats` functions.
+
+The last step stands for the discharge quantile computation. Just call the function `fquantile_stats` and use option `compute_uncertainties=TRUE` to compute the uncertainties using the bootstrap method.
+
+```R
+es$gapeau$mystats$fquantile_stats(
+        chunk_size=365, compute_uncertainties=TRUE
+    )
+```
+
+Several figures can be plotted:
+
+First, we can plot the quantile discharge of 1h at any pixel of the domain:
+
+```R
+es$gapeau$myplot$plot_xy_quantile(
+        duration=1,
+        X=as.integer(15),
+        Y=as.integer(25),
+        fig_settings=list("figname"= "output/quantile_XY_1h.png", "font_ratio"= 2),
+        ax_settings=list("legend_fontsize"= 20),
+    )
+```
+
+Then we can plot the discharges quantile of 1h at every outlets:
+
+```R
+es$gapeau$myplot$plot_outlets_quantile(duration=1,fig_settings=list("figname"= "output/quantile_outlets.png", "font_ratio"= 2))
+```
+
+Spatial quantile discharges of duration 1h and for the return period 2 years can be plotted as follow:
+
+```R
+es$gapeau$myplot$plot_spatial_quantile(duration=1, T=2, fig_settings=list("figname"= "/nas/RHAX/UTILISATEURS/maxime.jay-allemand/smashbox/output/quantile_spatial_1hT2.png", "font_ratio"= 2))
+```
+
+A multiplot of the spatial discharges quantile for all return period can be achieved by:
+
+```R
+es$gapeau$myplot$multiplot_spatial_quantile(duration=1, fig_settings=list("figname"= "output/quantile_spatial_multiplot.png", "font_ratio"= 1))
+
+```

smashbox/tutorials/R_tutorial.md

@@ -0,0 +1,121 @@
+# R tutorial
+
+This section contains a R tutorials to achieve common task with SmashBox.
+
+To use Smashbox with R, you must load the module with the Reticulate package.
+
+Performing a REX
+----------------
+
+First of all, launch the R console load the Reticulate package and load your Python environment where SmashBox and Smash are installed (change the path according your installation).
+
+```R
+library(reticulate)
+use_virtualenv("path/to/pythonenv/smashbox_env") #use a specific python environnement
+```
+
+Then load the package EsaySmash
+
+```R
+smashbox <- import("smashbox")
+```
+
+Assume you need to perform a REX on a defined area. This area is defined by a bounding box 
+
+```R
+bbox={'left': 875000.0,
+ 'bottom': 6228000.0,
+ 'right': 1001000.0,
+ 'top': 6320000.0}
+```
+
+Configure the smashbox module: Set the bounding box, select the outlet database and configure the database fields.
+
+```R
+es <- smashbox$SmashBox()
+es$myparam$set_param("bbox", bbox)
+```
+We are ready to create a container for your Smash simulation:
+
+```R
+es.newmodel("rex")
+```
+
+Then we need to adjust the setup. By default the setup `setup_rhax_gr4_dt3600` is automatically loaded. If needed, you can select an other one (see function `es.rex.mysetup.list_available_setup()`), and change some properties of the setup. On the rhax server, only the date must be configured. Path to data are already set, we use comephore 60M for the precipitation, the 2025 extraction of the dicharges at every sites and the daily potential evapotranspiration.
+
+```R
+es$rex$mysetup$update_setup(
+  list(
+    "start_time"= "2014-01-01 00:00",
+    "end_time"= "2014-02-01 00:00"
+  )
+)
+```
+
+Then we can build the mesh and add outlets with surface greater then 20 km², and automatically exclude outlets if the modeled surface error :math:`(Ssim - Sobs)/Sobs>0.2` (`area_error_th` option).
+
+```R
+es.rex.generate_mesh(query="(SURF>20) & (INFLUENCE=='Influence nulle ou faible')", area_error_th=0.2)
+```
+
+Few plot can help to validate our mesh with functions `smashbox.plot.myplot.myplot.plot_mesh` and `smashbox.plot.myplot.myplot.plot_catchment_surface_error` and `smashbox.plot.myplot.plot_catchment_surface_consistency`:
+
+```R
+es$rex$myplot$plot_mesh(fig_settings=list("figname"= "output/mesh.png"))
+es$rex$myplot$plot_catchment_surface_error(fig_settings=list("figname"= "output/mesh_surface_error.png"))
+es$rex$myplot$plot_catchment_surface_consistency(
+  fig_settings=list("figname"= "output/mesh_surface_consistency.png")
+)
+```
+remark: if figname is not defined, the plot will be sent to the matplotlib interactive UI or to your web browser as html (the fig_settings `xsize` and `ysize` will control the size of the html plot). However, this  feature is not working for remote server (perhaps try to ssh -X firefox).
+
+Let's now run a forward run (the model will be automatically build), automatically perform a warmup period of 100 days and return the discharge on the grid.
+
+```R
+es$rex$forward_run(return_options=list("q_domain"= TRUE), warmup=100)
+```
+
+Statistics can be computed. `smashbox.stats.mystats.mystats.foutlets_stats` method compute basic discharges statistics at every outlets; `smashbox.stats.mystats.mystats.fspatial_stats` method compute basic spatial discharges statistics at every pixel; `smashbox.stats.mystats.mystats.fmisfit_stats` compute many misfits criteria at outlets.
+
+```R
+es$rex$mystats$foutlets_stats()
+es$rex$mystats$fspatial_stats()
+es$rex$mystats$fmisfit_stats()
+```
+
+Several figures can be plotted:
+
+First, we can plot the parameters First, we can plot the parameters with functions `smashbox.plot.myplot.myplot.plot_parameters` and `smashbox.plot.myplot.myplot.multiplot_parameters`:
+```R
+es$rex$myplot$multiplot_parameters(
+  fig_settings=list("figname"= "output/muliplot_parameters.png")
+)
+es$rex$myplot$plot_parameters(fig_settings=list("figname"= "output/cp_parameters.png"))
+```
+
+Then we can plot basic statistics with functions `smashbox.plot.myplot.myplot.plot_outlet_stats` and `smashbox.plot.myplot.myplot.plot_spatial_stats` :
+```R
+es$rex$myplot$plot_outlet_stats(
+  fig_settings=list("figname"= "output/outlets_max_discharges.png")
+)
+es$rex$myplot$plot_spatial_stats(
+  fig_settings=list("figname"= "output/spatial_max_discharges.png")
+)
+```
+
+Let's plot an hydrogram (by default the first outlet is used) with functions `smashbox.plot.myplot.myplot.plot_hydrograph`:
+```R
+es$rex$myplot$plot_hydrograph(fig_settings=list("figname"= "output/discharges_hydrogram.png"))
+```
+
+Finally, plot the misfit criteria with functions `smashbox.plot.myplot.myplot.multiplot_misfit` and `smashbox.plot.myplot.myplot.plot_misfit` and `smashbox.plot.myplot.plot_misfit_map` :
+```R
+
+es$rex$myplot$multiplot_misfit(
+  fig_settings=list("figname"= "output/multiplot_nse_misfit.png", "xsize"= 15, "ysize"= 15)
+)
+es$rex$myplot$plot_misfit(
+  misfit="nnse", fig_settings=list("figname"= "output/nnse_misfit.png")
+)
+es$rex$myplot$plot_misfit_map(fig_settings=list("figname"= "output/map_nse_misfit.png"))
+```

smashbox/tutorials/__init__.py

@@ -0,0 +1,6 @@
+"""
+.. include:: ./generate_doc.md
+.. include:: ./Python_tutorial.md
+.. include:: ./R_tutorial.md
+.. include:: ./R_Graffas_tutorial.md
+"""

smashbox/tutorials/generate_doc.md

@@ -0,0 +1,7 @@
+# Generate the documentation
+
+The documentation is auto-generated using pdoc (https://pdoc.dev/). To generate the documentation, go to the base level of the SmashBox module and launch the following command (ensure your SmashBox Python environment is active):
+
+```bash
+pdoc smashbox/ --math -o ./html
+```