Tools for simulations

Tools for simulations are in the tools folder. It contains all the classes and methods shared by the vortex project and standalone applications. It includes only pre-processing of input files and post-processing of output files.

Forcing edition

Created on 3 Aug. 2017

@author: lafaysse

class tools.change_forcing.forcinput_tomerge(forcin, forcout, *args, **kwargs)[source]

Bases: object

This class represents a group of forcing files which must be merged in a single one through the Number_of_points dimension.

Parameters:

  • forcin (list) – List of input files names

  • forcout (str) – Name of merged output file

Generic method to open and merge multiple forcing files

checktime(init_forcing_file, forcin)[source]

Check time consistency of forcing files to merge.

Parameters:
merge(init_forcing_file, new_forcing_file, *args)[source]

Merge forcing files.

Parameters:
class tools.change_forcing.forcinput_applymask(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomerge

This class represents a group of forcing files which must be merged in a single one through the Number_of_points dimension. and for which incoming shortwave radiation must be corrected from shadows. Or a single forcing file for which incoming shortwave radiation must be corrected from shadows.

Generic method to open and merge multiple forcing files

class tools.change_forcing.forcinput_tomodify(forcin, forcout, *args, **kwargs)[source]

Bases: object

This class represents a forcing file for which modifications are needed before being used as SURFEX input Instanciation opens the initial forcing file to read and create the modified forcing file.

The change_forcing.forcinput_tomodify.modify() must be defined in child classes.

Parameters:

  • forcin (str) – Input file name

  • forcout (str) – Output file name

modify(init_forcing_file, new_forcing_file, *args)[source]

The key method to be overriden

Parameters:
add_massif_variables(init_forcing_file, new_forcing_file, savevar={})[source]

Add massif-scale diagnostics (isotherm 0 and rain snow limit elevation)

Parameters:
create_massif_dimension(init_forcing_file, new_forcing_file, savevar)[source]

create massif dimension from existing massifs in the forcing file

Parameters:
add_snow_rain_limit(init_forcing_file, new_forcing_file, savevar)[source]

Adds a massif-scale snow-rain limit elevation diagnostic

Parameters:
add_iso_zero(init_forcing_file, new_forcing_file, savevar)[source]

Adds a massif-scale 0 degree isotherm diagnostic

class tools.change_forcing.forcinput_addmeteomassif(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomodify

This class represents a forcing file for which massif-scale meteorological diagnostics must be added.

modify(init_forcing_file, new_forcing_file, *args)[source]

Add massif-scale meteorological diagnostics

Parameters:
class tools.change_forcing.forcinput_select(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomodify

This class represents a forcing file for which the geometry has to been modified before being used as SURFEX input including selection of massifs, elevation levels, slopes or aspects, duplication of slopes.

modify(init_forcing_file, new_forcing_file, *args)[source]

Selection of massifs, elevation levels, slopes or aspects, duplication of slopes.

Parameters:

  • init_forcing_file (utils.prosimu.prosimu) – Input file object

  • new_forcing_file (utils.prosimu.prosimu) – Output file object

  • args (list, int, int, list, list) – list of massif numbers, minimum elevation, maximum elevation, list of slopes, list of aspects

addCoord(forcing, massifnumber, dimension, varFillValue)[source]

Routine to add coordinates in the forcing file for the SAFRAN massifs

class tools.change_forcing.proselect(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_select

This class is designed to extract a selection of massifs, elevation levels, slopes or aspects from a PRO file.

add_massif_variables(init_forcing_file, new_forcing_file, savevar={})[source]

Add massif-scale diagnostics (isotherm 0 and rain snow limit elevation)

Parameters:
class tools.change_forcing.forcinput_ESMSnowMIP(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomodify

This class prepares FORCING files from the ESMSnowMIP offical netcdf dataset

modify(init_forcing_file, new_forcing_file, *args)[source]

Prepare ESM-SnowMIP forcings.

Parameters:
class tools.change_forcing.forcinput_extract(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomodify

This class allows to extract from an original forcing file all the variables corresponding to a pre-defined list of points.

Implemented by C. Carmagnola in November 2018 (PROSNOW project).

modify(init_forcing_file, new_forcing_file, *args)[source]

Extract a pre-defined list of points in a forcing file.

Parameters:
class tools.change_forcing.forcinput_changedates(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomodify

This class allows to change the dates of a forcing file from the climatology Implemented by C. Carmagnola in November 2018 (PROSNOW project).

modify(init_forcing_file, new_forcing_file, *args)[source]

Change the dates of a forcing file for climatological forecast.

Parameters:

Meteorological functions

Authors:

  • Diego Monteiro

  • LVG

Common atmosphere/meteorological conversions that are not elsewhere but commonly used in particular in the FORCING preparation.

Note : The dependency bronx proposes numerous tools to represent atmosphere state in bronx.meteo.thermo module. If you do not find what you need in this module, please check what you need is not yet implemented in bronx.

In particular conversion between relative humidity (rh) and specific humidity (qair) could be done the following way (knowing the air temperature Tair and atmospheric pressure PSurf):

import numpy as np
from bronx.meteo.thermo import Thermo

# rh -> qair:
qair = Thermo(['v', 'c'], data=dict(P=PSurf, Huw=hu, T=Tair, rc=np.zeros_like(Tair))).get('qv')

# qair -> rh
rh = Thermo(['v', 'c'], data=dict(P=PSurf, qv=qair, qt=qair, T=Tair)).get('Huw')
# Note: it may be necessary to cap to 100% when there is condensation:
rh[rh > 100] = 100
rh[rh < 0] = 0
tools.meteo.CO2_CONCENTRATION = 0.00062

Mean CO2 concentration

tools.meteo.splitting_prectot(prectot: array, tair: array, rh: array, alpha: float = 22, beta: float = -2.7, gamma: float = -0.2)[source]

Function used to partition total precipitation into liquid and solid part.

The computation is using air temperature and relative humidity.

Alpha, beta and gamma are parameters of logistic values that can be adjusted depending on the site considered following Froidurot et al., (2014) method (default values are taken from Koistinen and Saltikoff (1998)).

Parameters:

  • prectot (np.array) – total precipitation (units in is unit out)

  • tair (np.array) – air temperature (°C)

  • rh (np.array) – near surface relative humidity (%)

  • alpha (float, optional) – parameters or logistic function, defaults to 22

  • beta (float, optional) – parameters or logistic function, defaults to -2.7

  • gamma (float, optional) – parameters or logistic function, defaults to -0.2

Returns:

Tuple of precliq and precsol (same units as the prectot input)

Return type:

Tuple of np.array

tools.meteo.psurf(elevation)[source]

Compute the mean air pressure for a given elevation (hypothesis of standard atmosphere)

Parameters:

elevation (float or numpy array) – Elevation (m a.s.l)

Returns:

Surface pressure

Return type:

same as elevation

Namelist edition

tools.update_namelist.update_surfex_namelist_file(datebegin, namelistfile='OPTIONS.nam', forcing='FORCING.nc', dateend=None, updateloc=True, physicaloptions={}, snowparameters={}, nmembers=None, no_caution=False, cselect=None)[source]

This function updates a namelist file through the bronx module. Called by standalone S2M but not by vortex

Parameters:

  • datebegin (class:bronx.stdtypes.date.Date) – Initial date of simulation

  • namelistfile (str, optional) – Address of namelist to modified. Defaults to “OPTIONS.nam”

  • forcing (str, optional) – Address of associated forcing file. Defaults to “FORCING.nc”

  • dateend (class:bronx.stdtypes.date.Date, optional) – Last date of simulation (only necessary if different from the end of the FORCING file)

  • updateloc (bool, optional) – Modify coordinates in the namelist from the forcing file. Defaults to True

  • physicaloptions (dict, optional) – ESCROC physical options. Defaults to {}.

  • snowparameters (dict, optional) – ESCROC physical parameters. Defaults to {}.

  • nmembers (int, optional) – number of members for mutiphysics simulations. Defaults to None

  • no_caution (boolean, optional) – do not open the forcing to reduce computation time

tools.update_namelist.update_surfex_namelist_object(NamelistObject, datebegin, forcing='FORCING.nc', dateend=None, updateloc=True, physicaloptions={}, snowparameters={}, no_caution=False, cselect=None)[source]

This function updates a class:bronx.datagrip.namelist.NamelistSet object. Called directly by vortex algos.

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified.

  • datebegin (class:bronx.stdtypes.date.Date) – Initial date of simulation

  • forcing (str, optional) – Address of associated forcing file. Defaults to “FORCING.nc”

  • dateend (class:bronx.stdtypes.date.Date, optional) – Last date of simulation (only necessary if different from the end of the FORCING file)

  • updateloc (bool, optional) – Modify coordinates in the namelist from the forcing file. Defaults to True

  • nmembers (int, optional) – number of members for SODA simulations. Defaults to None

  • physicaloptions (dict, optional) – ESCROC physical options. Defaults to {}.

  • snowparameters (dict, optional) – ESCROC physical parameters. Defaults to {}.

  • no_caution (boolean, optional) – do not open the forcing to reduce computation time

  • cselect (list) – do not open the forcing to reduce computation time

  • cselect – set a list of diagnostic variables

tools.update_namelist.check_or_create_block(NamelistObject, blockname)[source]

Create a new namelist block only if it does not already exist.

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • blockname (str) – name of new block

tools.update_namelist.update_mandatory_settings(NamelistObject)[source]

Force some options whose values are mandatory to be compatible with snowtools_git

Parameters:

NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

tools.update_namelist.update_dates(NamelistObject, datebegin)[source]

Modify SURFEX namelist for defining the beginning of the simulation.

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • datebegin (class:bronx.stdtypes.date.Date) – Initial date of simulation

tools.update_namelist.update_loc(NamelistObject, forcing)[source]

Modify SURFEX namelist for defining the coordinates of the simulation points.

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • forcing (str) – Address of associated forcing file.

tools.update_namelist.update_forcingdates(NamelistObject, datebegin, dateend, forcing='FORCING.nc', no_caution=False)[source]

Modify SURFEX namelist limiting the dates to read in a FORCING file longer than the simulation.

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • datebegin (class:bronx.stdtypes.date.Date) – Initial date of simulation

  • dateend (class:bronx.stdtypes.date.Date) – Last date of simulation

  • forcing (str, optional) – Address of associated forcing file. Defaults to “FORCING.nc”

  • no_caution (boolean, optional) – do not check the forcing dates to reduce computation time (dangerous option, not recommended)

tools.update_namelist.update_physicaloptions(NamelistObject, **kwargs)[source]

Modify physical options for ESCROC simulations

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • kwargs (dict, optional) – ESCROC physical options. Defaults to {}.

tools.update_namelist.update_snowparameters(NamelistObject, **kwargs)[source]

Modify physical parameters for ESCROC simulations

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • kwargs (dict, optional) – ESCROC physical parameters. Defaults to {}.

tools.update_namelist.update_namelist_object_nmembers(NamelistObject, nmembers)[source]

Modify number of members for SODA simulations

Parameters:

  • NamelistObject (class:bronx.datagrip.namelist.NamelistSet) – Namelist to modified

  • nmembers (int) – number of members for SODA simulations.

Ground initialization

Created on 5 Sept. 2017

@author: lafaysse

tools.initTG.clim(options)[source]

Generate a temperature climatology from S2M options

Parameters:

options (dict) – S2M options

tools.initTG.create_env(diroutput)[source]

Create working directory and directories to save outputs

Parameters:

diroutput (str) – output directory

tools.initTG.generate_clim(list_forcing)[source]

Generate a temperature climatology from meteorological forcing files

Parameters:

list_forcing (list of str) – List of forcing files addresses

tools.initTG.get_meteo_for_clim(forcingpath, datebegin, dateend, geolist, list_forcing=[])[source]

Get the meteorological forcing files required to compute a climatology This is a recursive function until all files are found.

Parameters:

  • forcingpath (str) – directory where are stored the forcing files

  • datebegin (class:datetime.datetime) – First date of the climatology period

  • dateend (class:datetime.datetime) – Last date of the climatology period

  • geolist (list) – list defining the domain

  • list_forcing (list, optional) – list of forcing files previously found by previous iterations (should not be set by the user)

Prep edition

Created on 23 Aug. 2017

@author: lafaysse

class tools.change_prep.prep_tomodify(prepfile)[source]

Bases: object

This class represents a PREP.nc file for SURFEX initial conditions which has to be modified before SURFEX execution

Parameters:

prepfile (str) – Address of prep file to modify

Init method opens a PREP.nc file ready to be modified

apply_swe_threshold(swe_threshold, closefile=False)[source]

Method to apply a threshold on snow water equivalent in a PREP.nc file

Parameters:

  • swe_threshold (int or float) – Maximum allowed Snow Water Equivalent (kg/m2)

  • closefile (bool, optional) – Close PREP file after modification. Defaults to False

change_date(newdate, closefile=False)[source]

Method to change the date of a PREP file because a spinup is used to initialize the simulation

Parameters:

  • newdate (class:datetime.datetime) – New initial date of simulation

  • closefile (bool, optional) – Close PREP file after modification. Defaults to False

close()[source]

Close the PREP file

fix_version(iversion, ibug, closefile=False)[source]

Modify surfex version in PREP files that were built with an incorrect numbering :param iversion: fixed version number :type iversion: int :param ibug: fixed subversion number :type ibug: int :param closefile: close file after modification (default False) :type closefile: bool

insert_snow_depth(my_name_SRU, my_name_SNOWSAT, my_name_OBS, my_name_extprep50, my_name_extprep5, my_name_var, my_name_PREP)[source]

This function was implemented by C. Carmagnola in March 2019 (PROSNOW project). It modifies a PREP file by inserting measured snow depth values.

Massif-scale diagnostics

Created on 25 June 2018

@author: lafaysse

class tools.massif_diags.massif_simu(path, ncformat='NETCDF3_CLASSIC', openmode='r')[source]

Bases: prosimu1d

Class overriding prosimu to add massif-scale diagnostics

forceread : si True force lors de la lecture d’une variable par la méthode read_var à mettre l’ensemble des données de cette variable en cache - utile lorsque de grands nombre d’accès à la même variable sont nécessaires

massif_natural_risk()[source]

Compute massif-scale natural hazard index and add it to the file

warnings(minaltitude, maxaltitude, minlevel, maxlevel, naspects, list_aspects)[source]

Check if all elevations and aspects are present in the computation of massif-scale natural hazard index

Parameters:

  • minaltitude (float) – Minimum elevation present in the PRO file

  • maxaltitude (float) – Maximum elevation present in the PRO file

  • minlevel (float) – Minimum elevation considered in massif-scale natural hazard index

  • maxlevel (float) – Maximum elevation considered in massif-scale natural hazard index

  • naspects (int) – Number of aspects present in the PRO file

  • list_aspects (list) – List of aspects present in the PRO file

Hydrological diagnostics

snowtools contains hydrological routines designed to agregate S2M outputs into hydrological basins.

Starting from a shapefile of hydrological basins and a digital elevation model including massif numbers, two preliminary steps are necessary:

  1. Rasterize the shapefile of basin on the same grid as the DEM using the following:

from snowtools.tools.hydro import rasterized_shapefile
from snowtools.DATA import TESTBASE_DIR
import os

dem = os.path.join(TESTBASE_DIR, 'hydro', '/home/lafaysse/hydroMF/DEM_FRANCE_L93_250m_bilinear.nc')
shapefilebasin = os.path.join(TESTBASE_DIR, 'hydro', 'BVTopo_Topage2024_inmassifs.shp')

# Rasterize shapefilebasin on the same grid as dem using the value of the 'gid' attribute in the shapefile
# Note that the attribute should be an integer in the shapefile.
# If not please use QGIS to previously add an integer id attribute in your basins shapefile.

rasterized_shapefile(shapefilebasin, 'gid', dem, output='raster_basins.nc')

2. Compute the areas of S2M simulation units inside each basin using the following example where rasterbasin can be replaced by the file obtained at the previous step:

from snowtools.tools.hydro import basin_areas_file
from snowtools.DATA import TESTBASE_DIR
import os

dem = os.path.join(TESTBASE_DIR, 'hydro', '/home/lafaysse/hydroMF/DEM_FRANCE_L93_250m_bilinear.nc')
rasterbasin = os.path.join(TESTBASE_DIR, 'hydro', 'BNBV_SCHAPI_FRANCE250m.nc')
listpro = [os.path.join(TESTBASE_DIR, "PRO", "pro_testhydro_alp_oper_2025031906_2025032306.nc")]
outputdir = '.'

# Compute the areas of basins in rasterbasin corresponding to the geometry of the pro file
# and store them in outputdir
b = basin_areas_file(dem, rasterbasin, listpro, outputdir)

Once this areas file is available, the computation of hydrological diagnostics can be done using the following example where a list of variables are agregated and saved in the HYDRO.nc file

from snowtools.tools.hydro import hydro
from snowtools.DATA import TESTBASE_DIR
import os
forcing = os.path.join(TESTBASE_DIR, "FORCING", "forcing_testhydro_alp_oper_2025031806_2025032306.nc")
pro = os.path.join(TESTBASE_DIR, "PRO", "pro_testhydro_alp_oper_2025031906_2025032306.nc")
areas = os.path.join(TESTBASE_DIR, "hydro", "areas_alp27_allslopes.nc")
with hydro([forcing, pro], areas, 'HYDRO.nc') as h:
    h.integration(['Tair', 'Rainf', 'Snowf', 'SNOMLT_ISBA', 'WSN_T_ISBA', 'DSN_T_ISBA'], var_sca='WSN_T_ISBA')

@author: Matthieu Lafaysse, March 2025

class tools.hydro.hydro(profilename, areasfile, hydrofile)[source]

Bases: object

This class is an object designed to produce hydrological diagnostics of snow simulations. It includes the diagnostic file and the methods to read the associated metadata.

Parameters:

  • profilename (str or list of str) – FORCING or PRO file or list of addresses for FORCING + PRO

  • areasfile (str) – Address of the file describing the areas of PRO units for different catchments

  • hydrofile (str) – Address of the outputfile

close()[source]

Write global attributes and close the PRO and diagnostic files associated with this class

checktime(profilename)[source]

Check if time vectors are compatible between the different input files and return time to copy in output file

Parameters:

profilename (str) – list of pro file names (for error message)

Returns:

static checkpoints(listprofilename, areasfile)[source]

This method raise an exception in case of inconsistent number of points between pro file and areas file

Parameters:

  • listprofilename (list of str) – list of pro file name

  • areasfile (str) – areas file name

Returns:

get_basins(areasfile)[source]

This method reads the areas file describing the basins

Parameters:

areasfile (str) – Path of the shapefile

createhydrofile(hydrofilename)[source]

Create a catchment scale diagnostic file

integration(listvarname, agg_method='average', var_sca=None)[source]

Loop over a list of output variables to compute and write spatially aggregated diagnostics

Parameters:

  • listvarname (list) – List of variables required in output

  • agg_method (str) – Method used for spatial aggregation: average (default), cumul

  • var_sca (str) – Variable to compute snow cover area (e.g. DSN_T_ISBA, WSN_T_ISBA)

cumul(varin)[source]

This method cumulates the diagnostic varname in pro file across the catchment

Parameters:

varin (2d array of any type with dimensions (time, Number_of_points) as read from a PRO file) – Variable to cumulate spatially (time, Number_of_points)

Returns:

array of same type as varin with dimension (time, basin)

average(varin)[source]

This method averages the diagnostic varname in pro file across the catchment

Parameters:

varin (2d array of any type with dimensions (time, Number_of_points) as read from a PRO file) – Variable to average spatially (time, Number_of_points)

Returns:

array of same type as varin with dimension (time, basin)

sca(varin, threshold)[source]

This methods return the surface of the catchment for which varin > threshold

Parameters:

  • varin (array of any type with time as first dimension as read from a PRO file) – Variable for which a surface of exceedance should be computed (snow depth, snow water equivalent)

  • threshold (int or float) – Threhold

Returns:

array of same type as varin with time dimension length

copyvarattrs(varname)[source]

Copy attributes from a variable in input file to a variable in output file

Parameters:

varname (str) – variable name in input and output files

class tools.hydro.basin_areas_file(demfilename, basinraster, listprofilename, outputdir)[source]

Bases: object

Class to provide a file describing the areas of S2M units for hydrological basins :param demfilename: Digital elevation model including elevation, aspect, slope and massifs :type demfilename: str :param basinraster: Rasterized file of hydrological basins on the same grid as the dem file :type basinraster: str :param listprofilename: List of reference PRO files describing S2M geometry :type listprofilename: list of str :param outputdir: Directory where save output files are saved :type outputdir: str

read_dem(demfilename)[source]

This method reads the dem file

Parameters:

demfilename (str) – Digital elevation model file

read_rasterbasin(basinraster)[source]

This method reads the raster file of basins

Parameters:

basinraster (str) – Raster file of basins in the same grid as the dem

check_coordinates()[source]

This method checks if grids are identical between dem and raster of basins

get_list_basins()[source]

List of unique available basin identifiers

read_s2m_units(listprofilename)[source]

This method reads available S2M spatial units

Parameters:

listprofilename (list of str) – List of PRO reference files to describe S2M geometry

compute_areas(basins_list, metaprolist)[source]

This method computes the areas of S2M units for each basin of the list.

Parameters:

  • basins_list (list of int) – List of basin identifiers

  • metaprolist (list of str) – List of PRO reference files for S2M units

write_areas(metaprolist, outputdir)[source]

This method writes the computed areas in as many output files as available PRO reference files

Parameters:

  • metaprolist (list of str) – List of PRO reference files for S2M units

  • outputdir (str) – Directory where save output files are saved

tools.hydro.rasterized_shapefile(shapefilepath, attribute, refraster, output=None)[source]

Rasterize the attribute value of the shapefile shapefilepath on the same grid as the refraster file Dependencies on gdal and nco for this function

Parameters:

  • shapefilepath (str) – path of the shapefile to rasterize (allowed format: shp)

  • attribute (str) – name of the attribute of polygons for which the value will be rasterized

  • refraster (str) – reference file describing the grid (allowed format: tif)

  • output (str) – output file address (optional, if not available just change the extension of shapefilepath)

Returns:

True if all commands succeed

class tools.hydro.metaprosimu(profilename)[source]

Bases: prosimu1d

This class adds topographic and time metadata to a prosimu instance :param profilename: Path of the PRO.nc filename :type profilename: str

forceread : si True force lors de la lecture d’une variable par la méthode read_var à mettre l’ensemble des données de cette variable en cache - utile lorsque de grands nombre d’accès à la même variable sont nécessaires

tools.hydro.diff_aspect(aspect1, aspect2)[source]

Compute the angle absolute difference between two aspects (0-360 degrees) or two arrays of aspects

Parameters:

  • aspect1 (int, float or array of float) – Aspect or array of aspect (0-360 degrees)

  • aspect2 (int, float or array of float of same type as aspect1) – Aspect or array of aspect (0-360 degrees)

Returns:

array of type of aspect1 and aspect2

tools.hydro.bbox(img)[source]

This method provides the bounding box of True components of a given field

Parameters:

img (2d np.array) – Field of logical values

Simulation execution helpers

Created on 9 oct. 2012 @author: lafaysse

exception tools.execute.SystemException(status, command, errorcode=None)[source]

Bases: Exception

Exception for a system command

tools.execute.callSurfexOrDie(commande, moderun='NORMAL', nproc=1, errorcode=None)[source]

Method to execute a SURFEX binary and kill the current program if it fails. Include the setting of MPI and OpenMP tasks, and the extension of stack memory.

tools.execute.callSystemOrDie(commande, errorcode=None)[source]

Method to execute a system command and kill the current program if it fails.

tools.execute.printandcallSystemOrDie(commande, errorcode=None)[source]

Method to print and execute a system command and kill the current program if it fails.

Ensemble of perturbed forcing

Created on 3 Aug. 2022

@author: M Lafaysse, from B. Cluzet methods

tools.perturb_forcing.addNoise2Impur(var, varName, sigma, tau, dt, semiDistrib=False, brutal=False)[source]

Add noise with temporal correlation.

Parameters:

  • var (numpy.array) – data to be pertubed

  • varName (str) – name of the variable

  • sigma (float) – standard deviation of the random perturbation

  • tau (float) – temporal correlation length of the random perturbation (hours)

  • dt (int) – time step (hour)

  • semiDistrib (bool) – flag if var in SAFRAN geometry or semi-distributed geometry

  • brutal (bool) – multiply all timesteps by a random factor following a lognormal law

tools.perturb_forcing.addNoiseAdditive(var, sigma, tau, dt, fsys=0, semiDistrib=False)[source]

Apply additive perturbation (sigma=std of random perturbation, tau=temporal correlation, fsys=systematic perturbation) to a time serie.

Parameters:

  • var (numpy.array) – data to be pertubed

  • sigma (float) – standard deviation of the random perturbation

  • tau (float) – temporal correlation length of the random perturbation (hours)

  • dt (int) – time step (hour)

  • fsys (float) – value of the systematic perturbation

  • semiDistrib (bool) – flag if var in SAFRAN geometry or semi-distributed geometry

:return perturbed variable, same type and shape as var

tools.perturb_forcing.addNoiseMultiplicative(var, sigma, tau, dt, fsys=1, semiDistrib=False)[source]

Apply multiplicative perturbation (sigma=std of random perturbation, tau=temporal correlation, fsys=systematic

Parameters:

  • var (numpy.array) – data to be pertubed

  • sigma (float) – standard deviation of the random perturbation

  • tau (float) – temporal correlation length of the random perturbation (hours)

  • dt (int) – time step (hour)

  • fsys (float) – value of the systematic perturbation

  • semiDistrib (bool) – flag if var in SAFRAN geometry or semi-distributed geometry

:return perturbed variable, same type and shape as var

tools.perturb_forcing.convertPrecipPhase(Tair, precip, Tmin=272.65, Tmax=274.05)[source]

Convert precipitation to solid or liquid according to the disturbed temperature.

Parameters:

  • Tair – air temperature data (K)

  • precip – precip data

  • Tmin – minimum temperature for liquid precip (K)

  • Tmax – maximum temperature for solid precip (K)

Returns:

list [Rain, Snow]

class tools.perturb_forcing.forcinput_perturb(forcin, forcout, *args, **kwargs)[source]

Bases: forcinput_tomodify

Stochastically perturbed meterological forcing file for assimilation purpose

modify(init_forcing_file, new_forcing_file, *args)[source]

Add stochastic perturbations to a meterological forcing file

Parameters:
tools.perturb_forcing.gener_random_serie_autocorr(nt, sigma, tau, dt, semiDistrib=False, fsys=0)[source]

Generates a serie perturbation_vector of random temporally correlated values, centered on fsys of std sigma and temporal correlation tau.

Parameters:

  • nt (int) – time dimension length

  • sigma (float) – standard deviation of the random perturbation

  • tau (int) – temporal correlation length of the random perturbation (hours)

  • dt (int) – time step (hours)

  • fsys (float) – value of the systematic perturbation

  • semiDistrib (bool) – flag if var in SAFRAN geometry or semi-distributed geometry

Return perturbation_vector:

vector of the same size as var of perturbation

Management of ensemble PRO output files

Created on Wed Jul 5 2023.

This module provide a method to combine PRO simulation output files from different members into one single file.

Authors:

  • Jari-Pekka Nousu

tools.combine_memberfiles.combine_memberfiles(parentfolder, keep_open=False)[source]

Combining ensemble of SURFEX outputs into a single outputfile with additional dimension for ensemble members

  • creates output folder e.g. ‘mb0001_mb0005’

  • adds new profile file

Notes:

  • currently ensemble dimensions added for all variables, including constant outputs..

  • couple of work arounds to avoid AttributeErrors, fix better later

  • only tested for outputs for one point

Parameters:

parentfolder (str) – Path to the folder hosting output folders for each member. The actual simulation output file should be in parentfolder/mbXXXX/pro/XXXX.nc.

Returns:

None or the output netCDF4 dataset when keep_open is set to True.

Return type:

None or netCDF4.Dataset