pymarthe.utils.marthe_utils

Attributes

`__name__`
`__author__`
`__version__`
`encoding`
`NO_DATA_VALUES`

Classes

`MartheModel`	Wrapper MARTHE --> Python
`MartheField`	Wrapper Marthe --> python
`MartheSoil`	Wrapper Marthe --> python.
`MarthePump`	Class for handling Marthe pumping data.
`MartheGrid`	Class to handle Marthe single grid.

Functions

`deprecated`(func)	This is a decorator which can be used to mark functions
`unanimous`(obj)	Check if all elements in object (obj) has same length.
`get_mlfiles`(rma_file)	Extract all Marthe file paths frop .rma file
`progress_bar`(percent[, barlen])	Function to print progress bar by percent according
`get_layers_infos`(layfile[, base])
`has_soilprop`(text)	Description:
`extract_soildf`(text[, istep])	Description:
`read_zonsoil_prop`(martfile, pastpfile)	Description:
`remove_autocal`(rmafile, martfile)	Function to make marthe auto calibration / optimisation silent
`make_silent`(martfile)	Function to make marthe run silent
`get_chasim_indexer`(chasim)	Return a DataFrame with start/end columns using as
`read_grid_file`(grid_file[, keep_adj, start, end])	Function to read Marthe grid data in file.
`replace_text_in_file`(file, match, subs[, flags])	Function to replace string by another in text file
`get_units_dic`(martfile)
`get_dates`(pastp_file, mart_file)
`read_prn`([prnfile])	Function to read simulated prn file
`read_histo_file`(histo_file)	Function to read .histo file.
`isiterable`(object)	Detect if a object is a iterable.
`make_iterable`(var)	Make any variable iterable
`read_listm_qfile`(qfile, istep, fmt)
`read_record_qfile`(i, j, k, v, qfile, qcol)
`extract_pastp_pumping`(pastpfile[, mode])
`convert_at2clp`(pastpfile, mm)	Function convert 'affluent' / 'tronçon' to column, line, plan (layer)
`remove_no_data_values`(df[, column, nodata])
`read_obsfile`(obsfile[, nodata])	Simple function to read observation file.
`write_obsfile`(date, value, obsfile)	Write a standard obsfile from observation dates and value.
`get_run_times`([logfile])	Extract run times for model processes from log file.
`bordered_array`(a, v)	Border an array with constant value.
`read_budget`([filename])	Global budget reader (.prn).
`read_zonebudget`([filename])	Zone budget reader.
`hydrodyn_periodicity`(pastpfile, istep[, external, ...])	Helper function to manage hydrodynamic computation periodicity in .pastp file.
`set_tw`([start, end, mm, martfile, pastpfile])	Function to set/change model time window in .mart file.
`get_tw`([mm, martfile, pastpfile, tw_type])	Function to extract model time window in .mart file.

Module Contents

pymarthe.utils.marthe_utils.__name__ = 'PyMarthe'

pymarthe.utils.marthe_utils.__author__ = 'Ryma Aissat, Alexandre Pryet, Pierre Matran'

pymarthe.utils.marthe_utils.__version__ = 1.0

class pymarthe.utils.marthe_utils.MartheModel(rma_path, spatial_index=False, modelgrid=False)

Wrapper MARTHE –> Python

__iter__(only_active=False)

Generate cell spatial informations for spatial indexing using class generator format. Each cell will contain following informations:

‘node’ : cell unique id

‘layer’: layer id

‘inest’: nested grid id

‘i’ : row number

‘j’ : column number

‘xcc’ : x-coordinate of the cell centroid

‘ycc’ : y-coordinate of the cell centroid

‘dx’ : cell width

‘dy’ : cell height

‘area’ : cell area

‘vertices’: cell vertices

‘ative’: cell activity (0=inactive, 1=active)

Parameters:

only_active (bool) : enable/disable inactive cell consideration

Returns:

it (iterator) : generator of cell spatial data.

Examples:

it = mm.__iter__()

build_spatial_index(name=None, only_active=False)

Function to build a spatial index on field data.

Parameters:

name (str, optional)filename of output spatial index files.: If None, name is .mlname + ‘_si’. Default is None.

only_active (bool, optional) : enable/disable inactive cell consideration.

Examples:

mm..build_spatial_index()

build_modelgrid(add_z=False)

Build an large pandas.DataFrame and store it in .modelgrid attribute. Each row represent a cell with the following informations (columns):

‘node’ : cell unique id

‘layer’: layer id

‘inest’: nested grid id

‘i’ : row number

‘j’ : column number

‘xcc’ : x-coordinate of the cell centroid

‘ycc’ : y-coordinate of the cell centroid

‘dx’ : cell width

‘dy’ : cell height

‘area’ : cell area

‘vertices’: cell vertices

‘ative’: cell activity (0=inactive, 1=active)

Parameters:

add_z (bool, optional): whatever add informations about z-dimension such as:

‘zcc’ : z-coordinate of the cell centroid

‘dz’ : cell thickness

‘bottom’ : cell bottom altitud

‘top’ : cell top altitud

‘volume’ : cell volume ([L^3])

Default is False. Note: this process can take a while since z-dimension

informations has to be extracted from ‘topog’, ‘hsubs’ and even ‘sepon’ fields.

Examples:

mm.build_modelgrid(add_z=True) xyzcellcenter = mm.modelgrid[[f’{dir}cc’ for dir in list(‘xyz’)]].values

_get_top_bottom_arrays(): Function to extract altitude of top and bottom of whole model cells in array with shape (nlay, ncpl)

load_geometry(g=None, **kwargs)

Load and store geometry grid information of a MartheModel instance.

Parameters:

g (str, optional)Marthe geometry grid file.

Can be ‘sepon’, ‘topog’, ‘hsubs’, .. If None all geometry grid file will be loaded. Default is None.

**kwargsadditional arguments of property classes.

Can be :

use_imask (bool) : Default will be False.

Returns:

mf (MartheField) : store geometry field in .geometry attribut.

Examples:

mm.load_geometry(‘sepon’)

build_imask(): Function to build a imask field based on permh with binary data : 0 -> inactive cell

1 -> active cell

Parameters:

self (MartheModel) : MartheModel instance

Returns:

imask (MartheField) : imask field

Examples:

imask = mf.build_imask()

load_prop(prop, **kwargs)

Load MartheModel properties by name.

Parameters:

prop (str)supported property name.

Can be : - Field (MartheField)

‘permh’

‘emmca’

‘emmli’

‘kepon’

Pumping (MarthePump)
- ‘aqpump’
- ‘rivpump’
Zonal Soil properties (MartheSoil)
- ‘cap_sol_progr’
- ‘aqui_ruis_perc’
- ‘t_demi_percol’
- ‘rumax’
- …

**kwargs : additional arguments of property classes (e.g. use_imask for MartheField)

Returns:

Stock property class in prop dictionary

Examples:

mm = MartheModel(‘mona.rma’) mm.load_prop(‘emmca’)

write_prop(prop=None)

Write MartheModel required properties by name.

Parameters:

prop (str)supported property name.

Can be : - Field (MartheField)

‘permh’

‘emmca’

‘emmli’

‘kepon’

Pumping (MarthePump)
- ‘aqpump’
- ‘rivpump’
Zonal Soil properties (MartheSoil)
- ‘cap_sol_progr’
- ‘aqui_ruis_perc’
- ‘t_demi_percol’
- ‘rumax’
- …

Returns:

write property data (already loaded)

Examples:

mm = MartheModel(‘mona.rma’) mm.write_prop(‘emmca’)

classmethod from_config(configfile): Load an existing Marthe model from a configuration file written from pymarthe.MartheOptim.write_config(). The return MartheModel instance contains all parametrizes properties with values from related parameters files (‘grid’ and ‘list’ prameters). Note : for a forward run use, remember to write all the model properties

on disk using the .write_prop() method.

Parameters:

configfile (str) : parametrization configuration file.

Returns:

mm (MartheModel) : MartheModel instance with parametrizes properties.

Examples:

mmfrom = MartheModel.from_config(‘myconfiguration.config’)

get_extent()

Return the model domain extension.

Returns:

extent (list)model extension: Format: [xmin, ymin, xmax, ymax]

Examples:

mm.modelgrid.get_extent()

get_edges(closed=False)

Return the xy-coordinates of model domain edges.

Parameters:

closed (bool)whatever adding first point in return list: (in order to close polygon).

Returns:

edges (list)list of xy-coordinates (points).

If closed is False:

Format: [edge_lower_left, edge_upper_left,: edge_upper_right, edge_lower_right]

If closed is False:

Format: [edge_lower_left, edge_upper_left,: edge_upper_right, edge_lower_right]

Examples:

mm.modelgridget_edges(closed=False)

remove_autocal(): Function to make marthe auto calibration silent. wrapper to marthe_utils.remove_autocal().

Parameters:

self : MartheModel instance

Returns:

Write in .mart file inplace

Examples:

mm = MartheModel(rma_file) mm.remove_autocal()

make_silent(): Function to make marthe run silent

Parameters:

self : MartheModel instance

Returns:

Write in .mart inplace

Examples:

mm = MartheModel(rma_file) mm.make_silent()

get_outcrop(as_2darray=False, base=0)

Function to get outcropping layer number (integer) as MartheField instance or 2D-array.

Parameters:

as_2darray (bool, optional)return 2D-array of outcroping layer.: Only available for non nested model. Default is False
base (int, optional)output layer id n-base.: Marthe is 1-based (base=1), PyMarthe is 0-based (base=0). Default is 0.

Returns:

outcrop (MartheField/array) : outcropping layer numbers.

Examples:

mm = MartheModel(‘mymodel.rma’) outcrop_arr = mm.get_outcrop()

query_grid(target=None, **kwargs)

High level method to perform queries on model grid.

Parameters:

target (str/it)requeried grid information to extract.

Can be:

‘node’ : cell unique id
‘layer’: layer id
‘inest’: nested grid id
‘i’ : row number
‘j’ : column number
‘xcc’ : x-coordinate of the cell centroid
‘ycc’ : y-coordinate of the cell centroi
‘dx’ : cell width
‘dy’ : cell height
‘ative’: cell activity (0=inactive, 1=active)

If None, all grid informations will be considered. Default is None.

**kwargs : required spatial information to subset grid.

Returns:

df (DataFrame)subset DataFrame.: Index : query variable(s). Columns : target(s) variables.

Examples:

# – Query grid to extract x-y cell resolutions df = mm.query_grid(target=[‘dx’,’dy’],

i = [23,45,56], j = [45,67,89], layer = [0,5,4], inest = [0,0,0])

isin_extent(x, y)

Boolean response to check if (a) point(s) is in model extension.

Parameters:

x, y (float/iterable) : xy-coordinate(s) of the required point(s)

Returns:

res (list)boolean mask.: True : point in model domain False: point out of model domain

Examples:

mm._isin_extent(x=[256.8,278.1], y=[345.2,349.3])

get_node(x, y, layer=None, only_active=False)

Function to fetch node id(s) from xy-coordinates.

Parameters:

x, y (float/it) : xy-coordinate(s) of the required point(s) layer (int/it, optional) : layer(s) to intersect.

Can be an integer (same layer for all points) or a sequence of integers for each xy-coordinates. If None, all layer will be considered. Default None.

only_active (bool): whatever set unactive cell intersected to np.nan.: Default is None.

Returns:

nodes (list) : intersected nodes.

Examples:

x, y = [456788.78, 459388.78], [6789567.2, 6789569.89] nodes = get_nodes(x, y, layer=2, only_active=True)

all_active(node): Check whatever a node or a serie of node are all active.

Parameters:

node (int/it) : node(s) to test

Returns:

res (bool) : boolean response.

Examples:

mm.is_active(6794)

any_active(node): Check whatever a node or a serie of node contains at least 1 active.

Parameters:

node (int/it) : node(s) to test

Returns:

res (bool) : boolean response.

Examples:

mm.is_active(6794)

get_ij(x, y, stack=False)

Function to extract row(s) and column(s) from provided xy-coordinates in model extension. Simple wrapper to imask.intersects().

Parameters:

x, y (float/iterable) : xy-coordinate(s) of the required point(s) layer (int/iterable) : layer id(s) to intersect data.

Returns:

i, j (float/iterable) : correspondin row(s) and column(s) stack (bool) : stack output array

Formatnp.array([x1, x1],

[x2, y2],
… )

Default is False.

Examples:

mm = MartheModel(‘mymodel.rma’) x, y = [456788.78, 459388.78], [6789567.2, 6789569.89] rowcol = mm.get_ij(x,y, stack=True)

get_xy(i, j, stack=False)

Function to extract x-y cellcenters from provided row(s) and column(s) in model extension.

Parameters:

i, j(float/iterable) : row(s), column(s) stack (bool) : stack output array

Formatnp.array([i1, j1],

[i2, j2],
… )

Default is False.

Returns:

x, y (float/iterable) : correspondinf xy-cellcenters

Examples:

mm = MartheModel(‘mymodel.rma’) i, j= [23, 56, 89], [78, 123, 134] coords = mm.get_ij(i,j, stack=True)

extract_refine_levels()

Function to extract refine levels of each nested grid. The main grid (inest=0) must have a refine level equal to 1 (= division for each x-y direction).

Parameters:

Returns:

rlevelsrefine levels from grid file (permh).

Format{inest_0None,

inest_1refine_level_1,: …

inest_N : refine_level_N}

Examples:

rl = mm.extract_refine_levels()

get_xycellcenters(stack=False)

Function to get xy-cell centers of the model grid.

Parameters:

stack (bool)stack output array

Formatnp.array([x1, y1],

[x2, y2],: … )

Default is False.

Returns:

if stack is False:

xcc, ycc (array)xy-cell centers.: shape: (ncpl,) (ncpl,)

if stack is True:

xycc (array)stacked xy-cell centers: shape: (ncpl,2)

Examples:

xcc, ycc = mm.get_xycellcenters()

get_layer_from_depth(x, y, depth, as_list=True): Function to infer the layer id at a given xyz coordonates. Note: still experimental.

Parameters:

x, y (float/iterable) : xy-coordinate(s) of the required point(s) depth (float/iterable) : depth to infer (=z) as_list (bool): whatever returning only list of layer ids or

whole Dataframe with x,y,depth,layer,name. Default is True.

Examples:

mm = MartheModel(‘mymodel.rma’) x, y = [456788.78, 459388.78], [6789567.2, 6789569.89] layers = mm.get_layer_from_depth(x,y,depth=[223.1, 368])

run_model(exe_name='marthe', rma_file=None, silent=True, verbose=False, pause=False, report=False, cargs=None)

Run Marthe model using subprocess.Popen. It communicates with the model’s stdout asynchronously and reports progress to the screen with timestamps

Parameters:

(str (rma_file) – Note: can be the entire path if the exename is not in environment path Default is ‘marthe’.
optional) (additional command line arguments to pass to the executable.) – Note: can be the entire path if the exename is not in environment path Default is ‘marthe’.
(str –
optional) –
(bool (report) –
optional) –
(bool – Default is False.
optional) – Default is False.
(bool – Default is False.
optional) – Default is False.
(bool – which is returned by the method Default is True.
optional) – which is returned by the method Default is True.
(str/list (cargs) – Default is None.
optional) – Default is None.

Returns:

(success, buff)
success (bool) (Binary success of the run)
buff (list) (stdout)

get_vtk(vertical_exageration=0.05, hws=None, smooth=False, binary=True, xml=False, shared_points=False)

Build vtk unstructured grid from model geometry. Wrapper of pymarthe.utils.vtk_utils.Vtk class. Required python vtk package.

Parameters:

vertical_exageration (float)floating point value to scale vertical

exageration of the vtk points. Default is 0.05.

hws (str)hanging wall state, flag to define whatever the superior

hanging walls of the model are defined as normal layers (explivitly) or not (implicitly). Can be:

‘implicit’

‘explicit’

If None, self.hws will be use. Default is None.

smooth (bool)boolean flag to enable interpolating vertex elevations

based on shared cell. Default is False.

binary (bool)Enable binary writing, otherwise classic ASCII format

will be consider. Default is True. Note : binary is prefered as paraview can produced bug

representing NaN values from ASCII (non xml) files.

xml (bool)Enable xml based VTK files writing.

Default is False.

shared_points (bool)Enable sharing points in grid polyhedron construction.

Default is False. Note : False is prefered as paraview has a bug (8/4/2021)

where some polyhedron will not properly close when using shared points.

Returns:

vtk (pymarthe.utils.vtk_utils.Vtk) : Vtk class containg unstructured vtk grid

Example:

mm = MartheModel(‘mymodel.rma’, spatial_index=’mymodel_si’) myvtk = mm.get_vtk(vertical_exageration=0.02,

hws= ‘implicit’, smooth=True)

show_run_times(logfile=None, tablefmt='fancy')

Print model run times.

Parameters:

logfile (str)log filename.: If None, logfile = .mldir + ‘bilandeb.txt’ Default is None.

Returns:

Print message on console.

Examples:

mm.run_model(exe_name = ‘Marth_R8’) mm.show_run_times()

get_time_window(tw_type='date')

Function to extract model time window in .mart file. Wrapper to marthe_utils.get_tw().

Parameters:

tw_type (str, optional)time window output type.

Can be :

‘date’ : return pd.timestamp objects
‘istep’: return integers

Default is ‘date’.

Returns:

tw_min, tw_max (tuple): time window bounds (start/end)

Examples:

# – From isteps istart, iend = get_time_window(tw_type=’istep’) # – Get time window dates start, end = get_time_window(tw_type=’date’)

set_time_window(start=None, end=None)

Function to set/change model time window in .mart file. Note: the .pastp file will not be modify. Wrapper to marthe_utils.set_tw()

Parameters:

start (str/int, optional)string date or istep number of required: first timestep to consider. If None, the first istep (in .pastp file) will be considered. Default is None.
end (str/int, optional)string date or istep number of required: last timestep to consider. If None, the last istep (in .pastp file) will be considered. Default is None.

Returns:

Change .mart file inplace with required time window.

Examples:

# – From isteps mm.set_time_window(start=10, end=35)

# – From dates mm.set_time_window(start=’1999/01/28’, end=65) mm.set_time_window(start=’1992/01/01’, end=’1993/05/02’)

set_hydrodyn_periodicity(istep, external=False, new_pastpfile=None)

Function to manage hydrodynamic computation periodicity in .pastp file. Wrapper to marthe_utils.mm.set_hydrodyn_periodicity().

Parameters:

istep (str/int/iterable)required istep to activate hydrodynamic computation.

Can be :

‘all’ : activate for all timesteps
‘none’: desactivate for all timesteps
‘start:end:step’ : string sequence
[0,1,2,..] : any integer iterables

external (bool, optional)whatever create a external file with required

hydrodynamic computation periodicity. Note: external optional will not be considered

for global istep such as ‘all’, ‘none’

Default is False.

new_pastpfile (str, optional)path to the new pastp file to write.

If None, will overwrite the input pastp file. Default is None.

Returns:

(Over-)write pastp file. If external == True, will also write ‘cacul_hydro.txt’.

.

Examples:

# – All timesteps mm.set_hydrodyn_periodicity(istep= ‘all’, external=False) # – Weekly mm.set_hydrodyn_periodicity(istep= ‘::7’, external=True) # – Annual mm.set_hydrodyn_periodicity(istep= ‘::365’, external=False) # – Specific mm.set_hydrodyn_periodicity(istep= [0,5,6,7,9,11], external=True)

__str__(): Internal string method.

class pymarthe.utils.marthe_utils.MartheField(field, data, mm, use_imask=True)

Wrapper Marthe –> python

get_xyvertices(stack=False)

Function to fetch x and y vertices of the modelgrid.

Parameters:

stack (bool)stack output array

Formatnp.array([vx1, vy1],

[vx2, vy2],: … )

Default is False.

Returns:

if stack is False:: vx, vy (array) : xy-vertices.
if stack is True:: vxy (array) : stacked xy-vertices

Examples:

vx, vy = mf.get_xyvertices()

sample(x, y, layer, masked_values=None, as_mask=False, as_idx=False)

Sample field data by x, y, layer coordinates. It will perform simple a spatial intersection with field data.

Parameters:

x, y (float/iterable) : xy-coordinate(s) of the required point(s) layer (int/iterable) : layer id(s) to intersect data. masked_values (None/list, optional) : values to ignore during the sampling process

Default is None.

as_mask (bool, optional)return field boolean mask.: Does not allow duplicated value (array <= x,y). Default is False.
as_idx (bool, optional)return field indexes (=cell ids, =node numbers).: Allows duplicated values (array >= x,y)

Returns:

rec (np.recarray) : data intersected on point(s) mask (np.array [1D]) : field boolean mask (if as_mask = True) idx (np.array [1D]) : cell ids/node number/field indexes (if as_idx = True)

Examples:

rec = mf.sample(x=456.32, y=567.1, layer=0)

get_data(layer=None, inest=None, as_array=False, as_mask=False, masked_values=list())

Function to select/subset NON-masked values.

Parameters:

layer (int, optional)number(s) of layer required.: If None, all layers are considered. Default is None.
inest (int, optional)number(s) of nested grid required.: If None, all nested are considered. Default is None.
as_array (bool, optional)returning data as 3D-array.: Format : (layer*inest, row, col) Default is False.
as_mask (bool, optional)returning data as boolean index.: Default is False.

Returns:

if as_array is False:: rec (np.recarray) : selected data as recarray.
if as_array is True:: arr (3D-array) : selected data as array.
Note: if all arguments are set to None,: all data is returned.

Examples:

rec1 = mf.get_data(layer=[1,5,8], inest = 1) arr1 = mf.get_data(inest=3, as_array=True)

set_data(data, layer=None, inest=None)

Set field data for active cells (where imask is 1) and NON-masked values (see dmv)

Parameters:

data (object)field data to read/set.

Can be:

Marthe property file (‘mymodel.permh’)
Recarray with layer, inest,… informations
3D-array

layer (int, optional)number(s) of layer required.

If None, all layers are considered. Default is None.

inest (int, optional)number(s) of nested grid required.

If None, all nested are considered. Default is None.

Returns:

Set field data inplace.

Examples:

mf.set_data(permh_recarray) mf.set_data(permh3darray) # structured grids only mf.set_data(2.3e-3) # all layers/inest mf.set_data(2.3e-3, layer=2, inest=3) # one nest

get_masked(rec): Return field data (rec.array) after masking with model active cells (.imask). Note : if the field is not related to the model (`use_imask`=False) then return

the input data.

Parameters:

rec (rec.array) : field data.

Returns:

mrec (rec.array) : masked field data

Examples:

mf.get_masked()

set_data_from_parfile(parfile, izone, btrans='none')

Set field data from parameter file inplace.

Parameters:

parfile (str)path to parameter file to read.: Can be either zpc or pp parameter.

izone (MartheField) : parameter zone(s) field.

btrans (str, optional)string function to back-transform: field values. Default is ‘none’.

Examples:

parfile = ‘par/hk_zpc.dat’ mf.set_data_from_parfile(parfile,

izone, btrans=’lambda x: 10**x’)

as_3darray()

Wrapper to .get_data(inest=0, as_array=True) with error handling for nested model.

Parameters:

self (MartheField) : MartheField instance.

Returns:

arr (3D-array)array 3D of main grid only.: Format : (layer, row, col)

Examples:

arr3d = mf.as_3darray()

static grids2rec(grids)

Read Marthe field property file. Wrapper of marthe_utils.read_grid_file().

Parameters:

filename (str) : path to Marthe field property file.

Returns:

rec (np.recarray)recarray with all usefull informations: for each model grid cell such as layer, inest, value, …

Examples:

rec = mf._grid2rec(‘mymodel.emmca’)

_3d2rec(arr3d)

Convert 3D-array Wrapper of marthe_utils.read_grid_file().

Parameters:

filename (str) : path to Marthe field property file.

Returns:

rec (np.recarray)recarray with all usefull informations: for each model grid cell such as layer, inest, value, …

Examples:

rec = mf._grid2rec(‘mymodel.emmca’)

_rec2grid(layer, inest): Single MartheGrid instance construction from given layer and inest.

Parameters:

layer (int) : number of layer required. inest (int) : number of nested grid required.

Returns:

mg (MartheGrid) : Single Marthe grid instance.

Examples:

rec = mf._grid2rec(‘mymodel.emmca’)

to_grids(layer=None, inest=None)

Converting internal data (recarray) to a list of MartheGrid instance for given layers and inests.

Parameters:

layer (int, optional)number(s) of layer required.: If None, all layers are considered. Default is None.
inest (int, optional)number(s) of nested grid required.: If None, all nested are considered. Default is None.

Returns:

mgrids (list) : Required MartheGrid instances.

Examples:

mg = mf.to_grids(layer)

write_data(filename=None, keep_uniform_fmt=False)

Write field data in Marthe field property file.

Parameters:

filename (str) : path to write field data.

keep_uniform_fmt (bool, optional)whatever to conserve marthe light format: for uniform grid. If True, light format will be conserved. If False, all grids will be written explictly. Default is False. /!/ CAREFULL /!/ keeping uniform light format on permh field can modify the model geometry.

Returns:

Write in Marthe field property file on disk.

Examples:

mf.write_data(‘modified.permh’)

to_shapefile(filename=None, layer=0, inest=None, masked_values=dmv, log=False, epsg=None, prj=None)

Write field data as shapefile by layer.

Parameters:

filename (str, optional)shapefile path to write.: If None, filename = ‘field_layer.shp’. Default is None
layer (int, optional)layer numerical id to export.: Note : a unique layer id is allowed Default is 0.
inest (int, optional)nested grid numerical id to export.: If None, all nested grid are considered. Default is None.
masked_values (list, optional)field values to ignore.: Default is [-9999., 0., 9999].
log (bool, optional)logarithmic transformation of all values.: Default is False.
epsg (int, optional)Geodetic Parameter Dataset.: Default is None.
prj (str, optional)cartographic projection and coordinates: Default is None.

Returns:

Write shape in filename.

Examples:

filename = os.path.join(‘gis’, ‘permh_layer5.shp’) mf.to_shapefile(filename, layer=5)

plot(ax=None, layer=0, inest=None, vmin=None, vmax=None, log=False, extent=None, masked_values=dmv, basemap=False, **kwargs)

Plot data by layer

Parameters:

ax (matplotlib.axes, optional)matplotlib.axes custom ax.: If None basic ax will be create. Default is None.
layer (int, optional)layer numerical id to export.: Note : a unique layer id is allowed Default is 0.
inest (int, optional)nested grid numerical id to export.: If None, all nested grid are considered. Default is None.

vmin, vmax (float, optional) : min/max value(s) to plot.

log (bool, optional)logarithmic transformation of all values.

Default is False.

extent (tuple/list, optional): xy-limits of the plot window.

Format: (xmin, ymin, xmax, ymax). If None, window correspond to the entire model domain. Default is None.

masked_values (list, optional)field values to ignore.

Default is [-9999., 0., 9999].

basemap (dict/bool, optional)add base map to AxesSubplot.

/!/ Required python contextily module /!/ Can be:

False : not adding any basemap

Trueadd standard basemap.
-> provider: Stamen Terrain web tiles. -> crs: Spherical Mercator projection (EPSG:3857)

dict()contextily.add_basemap() arguments.

Format:

{‘source’:TileProvider object,
zoom:’auto’, … , ‘crs’: ‘EPSG:2154’}

Default is False.

**kwargs (optional)matplotlib.PathCollection arguments.

(ex: cmap, lw, ls, edgecolor, …)

Returns:

ax (matplotlib.axes)standard ax with 2 collections:

1 for rectangles
1 for colorbar

Examples:

ax = mf.plot(layer=6, cmap=’jet’) ax.set_title(‘Field (layer = 6)’, fontsize=14)

zonal_stats(stats, polygons, layer=None, names=None, trans='none')

Perform statistics on zonal areas.

Parameters:

stats (str/list)statistics functions to perform.

Must be recognize by pandas.DataFrame.agg() method. Example: stats = [‘mean’, ‘min’,’max’,’median’,’count’].

polygons (it)iterable containing single part polygons.

Format: [ [(x0, y0),(x1,y1),(x2,y2)],.., [(x’N,y’N),..], ..]: <=> [ polygon_0 ,.., polygon_N ].

layer (int/it, optional)layer id(s) on wich perform zonal statistics.

If None, all layers are considered. Default is None.

names (str/it, optional)names of zones in the output.

If None, generic names are created with field and zone number (‘field_z0’, ‘field_z1’,…). Default is None.

trans (str/func, optional): function/function name to transform field values

before applying statistics. If None, field values are not transformed. Default is ‘none’.

Returns:

zstats_df (DataFrame) : DataFrame with rows MultiIndex (‘zone’, ‘layer’).

Examples:

stats = [‘mean’,’max’,’min’,’median’,’count’] polygons = shp_utils.read_shapefile(‘mypolygons.shp’)[‘coords’] zdf = mf.zonal_stats(stats, polygons, layer=[4,5,6])

to_vtk(filename=None, trans='none', masked_values=dmv, **kwargs)

Build vtk unstructured grid from model geometry and add current field to cell dataset.

**kwargs correspond to the arguments of the MartheModel.get_vtk() method.

Required python vtk package.

Parameters:

filename (str, optional)vtk file name to write without extension.

Extension will be inferred. If None, filename = field. Default is None.

trans (str, optional)transformation to apply to the values.

See pymarthe.utils.pest_utils.transform. Default is ‘none’.

masked_values (float/it, optional)values to mask of the current field data.

Default are [9999, 0, -9999].

vertical_exageration (float, kwargs)floating point value to scale vertical

exageration of the vtk points. Default is 0.05.

hws (str, kwargs)hanging wall state, flag to define whatever the superior

hanging walls of the model are defined as normal layers (explivitly) or not (implicitly). Can be:

‘implicit’

‘explicit’

Default is ‘implicit’.

smooth (bool, kwargs)boolean flag to enable interpolating vertex elevations

based on shared cell. Default is False.

binary (bool, kwargs)Enable binary writing, otherwise classic ASCII format

will be consider. Default is True. Note : binary is prefered as paraview can produced bug

representing NaN values from ASCII (non xml) files.

xml (bool, kwargs)Enable xml based VTK files writing.

Default is False.

shared_points (bool, kwargs)Enable sharing points in grid polyhedron construction.

Default is False. Note : False is prefered as paraview has a bug (8/4/2021)

where some polyhedron will not properly close when using shared points.

Returns:

vtk (pymarthe.utils.vtk_utils.Vtk) : Vtk class containg unstructured vtk grid

Example:

mf = mm.prop[‘permh’] myvtk = mf.to_vtk(filename = mf.field, trans=’log10’, vertical_exageration=0.02)

__str__(): Internal string method.

class pymarthe.utils.marthe_utils.MartheSoil(mm, martfile=None, pastpfile=None)

Wrapper Marthe –> python. Interface to handle soil properties.

property soilprops
Get array of unique soil property names

property zones
Get array of unique soil property zone ids

property nsoilprop
Get number of defined soil properties

property nzone
Get number of defined zone ids

get_data(soilprop=None, istep=None, zone=None, force=False, as_style='list-like', **kwargs)

Get soil property field as recarray. Wrapper to MartheField.get_data()

Parameters:

soilprop (str/it, optional)soil property name.: Can be cap_sol_progr, equ_ruis_perc, t_demi_percol, … If None, all soil properties in .mart file are consider. Default is None.
istep (int/it, optional)required time steps.: If None, all available time steps are considered. Default is None.
zone (int/it, optional)soil zone id(s).: If None, all soil zone in .zonep file are condider.
force (bool, optional)force getting soil property data for all required timesteps: even if there are not provided explicitly in Marthe. For a not provided required time step the nearest previous istep (npi) containing soil data will be considered. Note: can be slow if the model contains a lot of timesteps. Default is False.
as_style (str, optional)required output type.: Can be ‘list-like’ or ‘array-like’. If ‘list-like’ return a subset of MartheSoil data. If ‘array-like’ return a subset recarray (cell-by-cell) Default is ‘list-like’.
**kwargsarguments of MartheField.get_data() method.: Can be layer, inest.

Returns:

df (DataFrame) : soil data by soilprop/zone rec (recarray) : soil data for each model cell.

Examples:

ms = MartheSoil(mm) rec_i2 = ms.get_data(‘cap_sol_progr’, as_style=’array_like’, inest=2)

sample(soilprop, x, y, istep=0)

Get soil property at specific xy-location. Wrapper to MartheField.sample(). Note: the sample data will be performed

on first layer only

Parameters:

soilprop (str)soil property name.

Can be cap_sol_progr, equ_ruis_perc,: t_demi_percol, …

x, y (float/iterable) : xy-coordinate(s) of the required point(s)

istep (int, optional)required time step.: Default is 0.

Returns:

rec (np.recarray) : soil property data at xy-point(s)

Examples:

ms = MartheSoil(mm) rec = ms.sample(‘t_demi_percol’, x=456.32, y=567.1)

plot(soilprop, istep=0, **kwargs)

Plot soil property. Wrapper to MartheField.plot().

Parameters:

soilprop (str)soil property name.: Can be cap_sol_progr, equ_ruis_perc, t_demi_percol, …
istep (int, optional)required time step.: Default is 0.
**kwargsarguments of MartheField.plot() method.: Can be ax, layer, inest, vmin, vmax, log, masked_values, matplotlib.PathCollection arguments.

Returns:

ax (matplotlib.axes)standard ax with 2 collections:

1 for rectangles
1 for colorbar

Examples:

ms = MartheSoil(mm) ax = ms.plot(‘cal_sol_progr’, cmap = ‘Paired’)

to_shapefile(soilprop, filename, istep=0, **kwargs)

Export soil property to shapefile Wrapper to MartheField.to_shapefile().

Parameters:

soilprop (str)soil property name.

Can be cap_sol_progr, equ_ruis_perc,

t_demi_percol, def_sol_progr,: rumax, defic_sol, … (GARDENIA)

istep (int, optional)required time step.

Default is 0.

**kwargsarguments of MartheField.to_shapefile() method.

Can be layer, inest, masked_values, log, epsg, prj

Returns:

Write shape in filename.

Examples:

filename = os.path.join(‘gis’, ‘cap_sol_progr.shp’) ms.to_shapefile(‘cap_sol_progr’, filename)

set_data_from_parfile(parfile, keys, value_col, btrans)

set_data(soilprop, value, istep=None, zone=None)

Set soil property value(s).

Parameters:

soilprop (str)soil property name.

Can be cap_sol_progr, equ_ruis_perc,: t_demi_percol, …

value (int/float) : value to set.

zone (int/iterable, optional)required zone to set value.: If None, all soil zones are considered. Default is None.

Returns:

Set value inplace for required soil property/zone.

Examples:

ms.set_data(‘cap_sol_progr’, 34.6, zone = [2, 8, 11])

write_data(filename=None)

Write soil current soil property data.

Parameters:

filename (str, optional)path to the outfile to write.: By default, the .mart or .pastp (according to the implementation mode) will be overwrited.

Returns:

Write soil data inplace.

Examples:

ms.set_data(‘cap_sol_progr’, 34.6, zone = [2, 8, 11]) fn = f”file.{ms.mode.split(‘-‘)[0]}” ms.write_data(fn)

__str__(): Internal string method.

class pymarthe.utils.marthe_utils.MarthePump(mm, pastp_file=None, mode='aquifer', verbose=False)

Class for handling Marthe pumping data.

_verbose()

Perform some classic checks about pumping data validity and print bad behaviour as warnings

Search for pumpings in inactive cells ()

Search for multiple pumping on same cell

_extract_data(mode)

Extract pumping data from .past file according to the pumping mode. Wrapper to marthe_utils.extract_pastp_pumping()

Parameters:

mode (str)pumping mode.: Can be ‘aquifer’ or ‘river’.

Returns:

Set pumping data and meta data inplace (as attribute)

Examples:

mp._extract_data()

get_data(istep=None, node=None, layer=None, i=None, j=None, boundname=None, force=False, as_mask=False)

Function to select/subset pumping data.

Parameters:

istep (int, optional)required timestep id(s).: If None, all timesteps wil be considered. Default is None.
node (int, optional)cell id(s).: Must be 0 < node < nnodes. If None, all cells will be considered. Default is None.
layer (int, optional)required layer id(s).: If None, all layers will be considered. Default is None.
i (int, optional)required row id(s).: If None, all rows will be considered. Default is None.
j (int, optional)required column id(s).: If None, all columns will be considered. Default is None.
boundname (str, optional)required well name(s).: If None, all boundnames will be considered. Default is None.
force (bool, optional)force getting pumping data for all required timesteps: even if there are not provided explicitly in the pastp file. For a not provided required time step the nearest previous istep (npi) containing pumping data will be considered. Note: can be slow if the model contains a lot of timesteps.
as_mask (bool)returning data as boolean index.: Default is False.

Returns:

df (np.recarray) : subset DataFrame Note: if all arguments are set to None,

all data is returned.

Examples:

df1 = mp.get_data(istep=[3,6,9,14], boundname = [‘p1’,’p2’]) df2 = mp.get_data(layer=2, i=33, j=18)

set_data_from_parfile(parfile, keys, value_col, btrans)

set_data(value, istep=None, node=None, layer=None, i=None, j=None, boundname=None)

Function to set pumping data inplace.

Parameters:

value (int/float) : pumping rate value to set. node (int, optional) : cell id(s).

Must be 0 < node < nnodes. If None, all cells will be considered.

istep (int, optional)number(s) of timestep required.: If None, all timesteps are considered. Default is None.
layer (int, optional)number(s) of layer required.: If None, all layers are considered. Default is None.
i (int, optional)number(s) of line required.: If None, all lines are considered. Default is None.
j (int, optional)number(s) of column required.: If None, all columns are considered. Default is None.
boundname (str, optional)name(s) required pumping point.: If None, all boundnames are considered. Default is None.

Returns:

Set pumping rate value inplace.

Examples:

mp.set_data(value = -44,67, istep=0, boundname = [‘p1’,’p2’]) mp.set_data(value = -189,4, layer=2, i=33, j=18)

get_boundnames(istep=None, layer=None, i=None, j=None)

Function to get boundname on subset data.

Parameters:

istep (int, optional)number(s) of timestep required.: If None, all timesteps are considered. Default is None.
layer (int, optional)number(s) of layer required.: If None, all layers are considered. Default is None.
i (int, optional)number(s) of line required.: If None, all lines are considered. Default is None.
j (int, optional)number(s) of column required.: If None, all columns are considered. Default is None.

Returns:

boundnames (list) : available boundnames of selected data.

Examples:

steady_bdnmes = mp.get_boundnames(istep=0) bdnmes_l2 = mp.get_boundnames(layer=2)

switch_boundnames(switch_dic)

Function to change boundname of a pumping point by another.

Parameters:

switch_dic (dict)boundnames to switch: Format : {bdnme_source: bdnme_target, …}

Returns:

Replace new boundname inplace.

Examples:

mp.switch_boundnames(switch_dic = {‘B1951752/F1’: ‘F1’})

split_qtype(qtype=None)

Function to split pumping data into pandas Dataframe(s) according to the provided qtype (‘mail’, ‘record’ ,’listm’)

Parameters:

qtype (str/iterable)type of pumping data to return: Can be (list) ‘mail’, ‘record’, ‘listm’ or None. If None, all qtypes are provided Dataframe. Default is None.

Returns:

[mail_df, record_df, listm_df] (list) : if qtype is None mail_df or record_df or listm_df (Dataframe) : is qtype is provided

Examples:

mail_df = mp.split_qtype(‘mail’)[0]

_write_mail(): Function to write pumping data (as ‘mail’ qtype) inplace.

Parameters:

self (MarthePump) : instance.

Returns:

Write ‘mail’ pumping data in parent model .pastp file.

Examples:

mm.prop[‘aqpump’]._write_mail()

_write_record(): Function to write pumping data (as ‘record’ qtype) inplace.

Parameters:

self (MarthePump) : instance.

Returns:

Write ‘record’ pumping data in parent model .pastp file (steady-state data) and external file (transient data).

Examples:

mm.prop[‘aqpump’]._write_record()

_write_listm(): Function to write pumping data (as ‘listm’ qtype) inplace.

Parameters:

self (MarthePump) : instance.

Returns:

Write ‘listm’ pumping data in external file.

Examples:

mm.prop[‘aqpump’]._write_listm()

write_data(): Function to write pumping data inplace. (All qtypes are considered).

Parameters:

self : MarthePump instance

Returns:

Write data inplace. (record files, listm files, pastp file)

Examples:

mp.set_data(value = 3, istep=[3,5]) mp.write_data()

__str__(): Internal string method.

class pymarthe.utils.marthe_utils.MartheGrid(istep, layer, inest, nrow, ncol, xl, yl, dx, dy, xcc, ycc, array, field=None)

Class to handle Marthe single grid.

get_cell_vertices(i, j, closed=False): DOES NOT WORK PROPERLY!

to_records(fmt='light', base=0)

Convert grid values to flatten recarray.

Parameters:

fmt (str)output format.

Can be:

‘light’ : output columns: ‘layer,inest,i,j,x,y,value’
‘full’ : output columns: ‘node,layer,inest,i,j,x,y,dx,dy,vertices,value’

Default is ‘light’. Note: the ‘full’ format is obviously slower.

base (int)n-based array format

Can be :

0 (Python)
1 (Fortran)

Default is 0.

Returns:

Write data inplace. (record files, listm files, pastp file)

Examples:

mg.to_records(fmt=’light’)

to_string(maxlayer=None, maxnest=None, rlevel=None, keep_uniform_fmt=False)

Convert grid to a single string with Marthe Grid file format. Parameters: ———– maxlayer (int/None, optional) : maximum number of layer.

If None, value will be ‘0’. Default is None.

maxnest (int/None, optional)maximum number of nested grid.: If None, value will be ‘0’. Default is None.
rlevel (int/None, optional)refine level to extract adjacent: cells informations. Default is None.
keep_uniform_fmt (bool, optional)whatever to conserve marthe light format: for uniform grid. If True, light format will be conserved. If False, all grids will be written explictly. Default is False. /!/ CAREFULL /!/ keeping uniform light format on permh field can modify the model geometry.

Return:

lines_str (str)Marthe Grid string format: (ready to write)

Example

mygrid = MartheGrid(0, 0, 125, 126, 325., 750., dx, dy, xcc, ycc, array, field = ‘PERMEAB’) with open(‘mymarthegrid.prop’, ‘r’) as f:

f.write(mygrid.to_string())

to_pyshp()

Convert grid to list of polygons with vertices coordinates.

Parameters:

self (MartheGrid) : MartheGrid instance

Return:

pyshp_parts (list) = polygons parts with: xy-vertices coordinates.

Example

parts = mg.to_pyshp()

to_patches(): Convert grid to list of matplotlib.Path

Parameters:

self (MartheGrid) : MartheGrid instance

Return:

patches (list) = list of Path objects

Example

patches = mg.to_patches()

__str__(): Internal string method.

pymarthe.utils.marthe_utils.encoding = 'latin-1'

pymarthe.utils.marthe_utils.NO_DATA_VALUES

pymarthe.utils.marthe_utils.deprecated(func): This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used. Addtionnal message ‘use funcname instead.’ is written if provided.

pymarthe.utils.marthe_utils.unanimous(obj): Check if all elements in object (obj) has same length.

pymarthe.utils.marthe_utils.get_mlfiles(rma_file)

Extract all Marthe file paths frop .rma file

Parameters:

rma_file (str): Marthe .rma file path

Returns:

mfiles_dic (dict)all .rma file paths: Format: {‘permh’: ‘model.permh’, …}

Example

rma_file = ‘mymarthemodel.rma’ mlfiles = get_mlfiles(rma_file)

pymarthe.utils.marthe_utils.progress_bar(percent, barlen=50)

Function to print progress bar by percent according to a given bar length.

Parameters:

percent (float)progress percent: Must be between 0 and 1.
barlen (int,optional)bar length showed on console screen.: Default is 50

Returns:

Write in sys.stdout

Examples:

l = [‘azerty’] * 100000 for i, v in enumerate(l):

percent = i/len(l) var = l[1:] + ‘’.join(v) + l[:-1] progress_bar(percent, berlen=70)

pymarthe.utils.marthe_utils.get_layers_infos(layfile, base=1): Description:

Extract layer informations from Marthe .layer file

Parameters:

layfile (str): Marthe .rma file path base (int) : base for layer counting.

Python is 0-based. Marthe is compiled in 1-based (Fortran) Default is 1.

Returns:

nnest (int) : number of nested mesh (“gigogne”) layers_infos (DataFrame) : layer informations like

layer numbers, thickness, …

Format:

layer thickness epon_sup ke anisotropy name

0 1 50.0 0 0.0 0.0 layer_0 1 2 150.0 1 0.0 0.0 layer_1

Example

layfile = ‘mymarthemodel.layer’ nnest, layers_infos = get_layers_infos(layfile, base = 1)

pymarthe.utils.marthe_utils.has_soilprop(text)

Description:

Boolean response of zone soil data in string.

Parameters:

text (str) : string to test.

Returns:

res (bool) : Whatever the text contains soil property data

Example

s = “my string” if has_soilprop(s):

print(‘This string contains soil data.’)

else:: print(‘This string does not contain soil data’)

pymarthe.utils.marthe_utils.extract_soildf(text, istep=None)

Description:

Extract soil data in text to DataFrame.

Parameters:

text (str) : string to test. istep (int, optional): insert a additional ‘istep’ column

at first position. Default is None.

Returns:

soil_df (DataFrame)soil data with apply zone ids and value.

Format: (if istep is None)

property zone value

0 cap_sol_progr 54 10.2 1 ru_max 126 41.4

(if istep is not None)

istep property zone value

0 0 cap_sol_progr 54 10.2 1 0 ru_max 126 41.4

Example

soil_df = extract_soildf(mymartfielcontent, istep=0)

pymarthe.utils.marthe_utils.read_zonsoil_prop(martfile, pastpfile)

Description:

Detetct existence and location of zone soil property data and convert it to single DataFrame.

Parameters:

martfile (str) : path to the .mart file. pastpfile (str) : path to the .pastp file.

Returns:

mode (str)flag of the zone soil data implementation.

Can be :

‘mart-c’ (constant soil data in .mart file)
‘pastp-c’ (constant soil data in .pastp file)
‘pastp-t’ (transient soil data in .pastp file)

soil_df (DataFrame)soil data with apply zone ids and property values.

Format: (if istep is None)

property zone value

0 cap_sol_progr 54 10.2 1 ru_max 126 41.4

(if istep is not None)

istep property zone value

0 0 cap_sol_progr 54 10.2 1 0 ru_max 126 41.4

Example

mode, soil_df = read_zonsoil_prop(martfile, pastpfile)

pymarthe.utils.marthe_utils.remove_autocal(rmafile, martfile): Function to make marthe auto calibration / optimisation silent

Parameters:

martfile (str) : path to .mart file. martfile (str) : path to .mart file.

Returns:

Write in .mart/.rma file inplace

Examples:

remove_autocal(‘mymodel.rma’, ‘mymodel.mart’)

pymarthe.utils.marthe_utils.make_silent(martfile): Function to make marthe run silent

Parameters:

self : MartheModel instance martfile (str) : .mart file path

Default is None

Returns:

Write in .mart inplace

Examples:

make_silent(‘mymodel.mart’)

pymarthe.utils.marthe_utils.get_chasim_indexer(chasim)

Return a DataFrame with start/end columns using as character indexes to read grid in Marthe simulated grid file.

Parameters:

(str) (chasim) – If None, the ‘chasim.out’ in model path will be considered. Default is None.

Returns:

indexer (DataFrame) –

Format:

field istep start end

0 CHARGE 0 0 16789 1 CHARGE 0 16790 33578 2 CHARGE 0 33579 50367

Return type:

table indexer.

Examples

mm = MartheField(‘mona.rma’) mfs = MartheFieldSeries(mm, chasim=None)

pymarthe.utils.marthe_utils.read_grid_file(grid_file, keep_adj=False, start=None, end=None)

Function to read Marthe grid data in file. Only structured grids are supported.

Parameters:

grid_file (str) : Marthe Grid file full path

keep_adj (bool)whatever conserving adjacent cells

for nested grids. Default is False.

start/end (int, optional)first/last character index to

consider in whole grid file. If None, `start`=0 and `end`= len(N) (where N is the number of character

in the provided grid file)

Default is None.

Returns:

grid_list (list)contain one or more: MartheGrid instance

Examples:

grids = read_grid_file(‘mymodel.permh’)

pymarthe.utils.marthe_utils.replace_text_in_file(file, match, subs, flags=0)

Function to replace string by another in text file

Parameters:

file (str) : file name or full path match (str) : str/regex to match subs (str) : replaced string to write flags (re object) : flag to add in match expression

This is a regex object like:

re.IGNORECASE

re.VERBOSE

…

Default is 0

Returns:

Rewrite replaced text in file (inplace)

Examples:

file = ‘replace_text_in_file.txt’ match = ‘Imass’ subs = ‘Initial_mass’ replace_text_in_file(file, match, subs)

pymarthe.utils.marthe_utils.get_units_dic(martfile)

Description:

Extract units from “Unités des données” block in .mart file.

Parameters:

martfile (str): .mart file name

Returns:

units_dic (dict)dictionary of unit converters values: Format: {‘permh’: 1, ‘flow’: 1.15e-5 ,…}

Example

units = get_units_dic(‘mymodel.mart’)

pymarthe.utils.marthe_utils.get_dates(pastp_file, mart_file): Description:

Extract dates from .pastp file

Parameters:

pastp_file (str) : path to .pastp marthe file mart_file (str): .mart file name

Returns:

dates (DateTimeIndex): list of model dates

Example

mm = MartheModel(‘mymodel.rma’) dates = mm.get_dates()

pymarthe.utils.marthe_utils.read_prn(prnfile='historiq.prn')

Function to read simulated prn file

Parameters:

prnfile (str)prn file full path: Default is ‘historiq.prn’

Returns:

df (DataFrame)Multi-index DataFrame

index = ‘date’ (DateTimeIndex) columns = MultiIndex(level_0 = ‘type’, # Data type (‘Charge’, ‘Débit’, …)

level_1 = ‘gigogne’) # (optional) Refined grid number
(0 <= gigogne <= N_gigogne)

level_2 = ‘name’, # Custom name

Examples:

prn_df = read_mi_prn(prnfile = ‘historiq.prn’)

pymarthe.utils.marthe_utils.read_histo_file(histo_file)

Function to read .histo file. Support localisation by coordinates (XCOO) or by column, row (CL) Support additional label. Support older versions of Marthe .histo file.

Parameters:

histo_file (str) : .histo file full path

Returns:

df (DataFrame)information about data: to save by Marthe

Examples:

histo_df = read_histo_file(‘mymodel.histo’)

pymarthe.utils.marthe_utils.isiterable(object)

Detect if a object is a iterable. String are not considered as iterable.

Parameters:

object (?): instance to check.

Returns:

(bool)Trueobject is iterable.: False : object is not iterable.

Examples:

l = [4,5,6] if _isiterable(l):

print(sum(l))

pymarthe.utils.marthe_utils.make_iterable(var): Make any variable iterable

Parameters:

var (?): instance transform

Returns:

it (iterable) : any iterable object

Examples:

i = 9 it = make_iterable(var)

pymarthe.utils.marthe_utils.read_listm_qfile(qfile, istep, fmt)

pymarthe.utils.marthe_utils.read_record_qfile(i, j, k, v, qfile, qcol)

pymarthe.utils.marthe_utils.extract_pastp_pumping(pastpfile, mode='aquifer')

Description:

Extract pumping data from .pastp file content (by timestep blocks) NOTE : 2 types of pumping condition can be read:

LIST_MAIL (regional model)

MAILLE (local model) single value or record

Parameters:

content (dict)content of .pastp file by timestep blocks: Come from read_pastp() function
mode (str)type of cell localisation pumping: Can be ‘aquifer’ (columns, line, layer) or ‘river’ (‘affluent’, ‘troncon’) Default is ‘aquifer’

Returns:

pumping_data (dict) : all pumping data by timestep qfilenames (dict) : all qfiles (full) names by timestep

Example

lines, nstep = read_pastp(‘mm.pastp’) pumping_data, qfilenames = extract_pastp_aqpumping(lines, nstep)

pymarthe.utils.marthe_utils.convert_at2clp(pastpfile, mm): Function convert ‘affluent’ / ‘tronçon’ to column, line, plan (layer) and rewrite it inplace in pastp file. Warn user about the conversion.

Parameters:

pastpfile (str) : path to pastp file mm (object) : MartheModel instance

Returns:

Replace lines inplace in pastp file

Examples:

convert_at2clp(pastpfile, mm)

pymarthe.utils.marthe_utils.remove_no_data_values(df, column='value', nodata=NO_DATA_VALUES)

Description

Remove no data values in DataFrame on specific column

param - column (str):

type - column (str):

column name to search the no data values

param - nodata (list):

Default is [-9999., -8888., 9999.]

type - nodata (list):

list of no data values to remove

param ———–:

returns:

df (DataFrame) (clean table without no data value)
———–

Examples

clean_df = remove_no_data_values(df, nodata = [1e+30, -9999.])

pymarthe.utils.marthe_utils.read_obsfile(obsfile, nodata=None)

Simple function to read observation file. Format : header0 header1

09/05/1996 0.12 10/05/1996 0.88

Note: separator is anywhite space (tabulation is prefered)

Parameters:

obsfile (str): observation filename to read value.: Note: if locnme is not provided, the locnme is set as obsfile without file extension.
nodata (list/None)no data values to remove.: Default is None.

Returns:

df (DataFrame)observation table

Formatdate value: 1996-05-09 0.12 1996-05-10 0.88

Examples:

obs_df = read_obsfile(obsfile = ‘myobs.dat’)

pymarthe.utils.marthe_utils.write_obsfile(date, value, obsfile): Write a standard obsfile from observation dates and value.

Parameters:

date (DateTimeIndex) : observation date index value (iterable) : observation values obsfile (str): observation filename to read value.

Returns:

Write observation values. Format : date value

1996-05-09 0.12 1996-05-10 0.88

Examples:

locnme = ‘07065X0002’ obs_df = write_obsfile(date, values, obsfile = locnme + ‘.dat’)

pymarthe.utils.marthe_utils.get_run_times(logfile='bilandeb.txt')

Extract run times for model processes from log file.

Parameters:

logfile (str)log filename.: Default ‘bilandeb.txt’

Returns:

df (DataFrame)Summary run times

Format :: Process CPU time

process_1 time_1 process_2 time_2

… …

Examples:

rtdf = get_run_times(logfile=’model/bilandeb.txt’)

pymarthe.utils.marthe_utils.bordered_array(a, v)

Border an array with constant value.

Parameters:

a (ndarray)ndarray to border.: Format: array([[1, 1, 1, 1, 1],

[1, 1, 1, 1, 1], [1, 1, 1, 1, 1], [1, 1, 1, 1, 1], [1, 1, 1, 1, 1]])

Returns:

array (ndarray)bordered array.: Format: array([[v, v, v, v, v, v, v],

[v, 1, 1, 1, 1, 1, v], [v, 1, 1, 1, 1, 1, v], [v, 1, 1, 1, 1, 1, v], [v, 1, 1, 1, 1, 1, v], [v, 1, 1, 1, 1, 1, v], [v, v, v, v, v, v, v]])

Examples:

ba = bordered_array(np.ones((5,5)), 0)

pymarthe.utils.marthe_utils.read_budget(filename='histobil_nap_pastp.prn')

Global budget reader (.prn). The io.StringIO module is required.

Parameters:

filename (str, optional)budget text file to read.

Can be :

aquifer budget by timesteps –> ‘~/histobil_nap_pastp.prn’
cumulative aquifer budget –> ‘~/histobil_nap_cumu.prn’
climatic budget –> ‘~/histoclim.prn’
flow budjet –> ‘~/histobil_debit.prn’

Default is ‘histobil_nap_pastp.prn’.

Returns:

filename IS a flow budget file (‘histobil_debit.prn’):

bud_dfs (list)budget DataFrames.
Format: [global_flow_df, river_flow_df, cumulative_river_flow_df]
filename IS NOT a flow budget file:
dub_df (DataFrame) : global budget DataFrame.

Examples:

nap_cumul_df = read_budget(filename= ‘histobil_nap_cumu.prn’) nap_pastp_df = read_budget(filename= ‘histobil_nap_pastp.prn’) clim_df = read_budget(filename= ‘histoclim.prn’) flow_df, riv_df, criv_df = read_budget(filename= ‘histobil_debit.prn’)

pymarthe.utils.marthe_utils.read_zonebudget(filename='histobil_debit.prn')

Zone budget reader. The io.StringIO module is required.

Parameters:

filename (str, optional)flow budget text file to read.: Default is ‘histobil_debit.prn’.

Returns:

zb_df (DataFrame)zone budget MultiIndex DataFrame.

Format :

Entr_Limit_ext Sort_Limit_ext ..

zone date

100 01/01/2006 4658895 4667213 .. 100 02/01/2006 4658796 4649391 ..

920 01/01/2009 4697856 4263942 ..

Examples:

zb_df = read_zonebudget()

pymarthe.utils.marthe_utils.hydrodyn_periodicity(pastpfile, istep, external=False, new_pastpfile=None)

Helper function to manage hydrodynamic computation periodicity in .pastp file.

Parameters:

pastpfile (str) : path to the required model .pastp file.

istep (str/int/iterable)required istep to activate hydrodynamic computation.

Can be :

‘all’ : activate for all timesteps
‘none’: desactivate for all timesteps
‘start:end:step’ : string sequence
[0,1,2,..] : any integer iterables

external (bool, optional)whatever create a external file with required

hydrodynamic computation periodicity. Note: external optional will not be considered

for global istep such as ‘all’, ‘none’

Default is False.

new_pastpfile (str, optional)path to the new pastp file to write.

If None, will overwrite the input pastp file. Default is None.

Returns:

(Over-)write pastp file. If external == True, will also write ‘cacul_hydro.txt’.

.

Examples:

f = ‘mymodel.pastp’ # – All timesteps hydrodyn_periodicity(f, istep= ‘all’, external=False) # – Weekly hydrodyn_periodicity(f, istep= ‘::7’, external=True) # – Annual hydrodyn_periodicity(f, istep= ‘::365’, external=False) # – Specific hydrodyn_periodicity(f, istep= [0,5,6,7,9,11], external=True)

pymarthe.utils.marthe_utils.set_tw(start=None, end=None, mm=None, martfile=None, pastpfile=None)

Function to set/change model time window in .mart file. Note: the .pastp file will not be modify.

Parameters:

start (str/int, optional)string date or istep number of required: first timestep to consider. If None, the first istep (in .pastp file) will be considered. Default is None.
end (str/int, optional)string date or istep number of required: last timestep to consider. If None, the last istep (in .pastp file) will be considered. Default is None.
mm (MartheModel, optional)MartheModel with correct .mldates and .mlfiles.: If None, martfile and pastpfile arguments will be considered. Default is None.
martfile (str, optional)related model .mart file: Default is None.
pastpfile (str, optional)related model .mart file: Default is None.

Returns:

Change .mart file inplace with required time window.

Examples:

# – From isteps set_tw(start=10, end=35, mm=mm)

# – From dates set_tw(start=’1999/01/28’, end=65, mm=mm)

# – From external files set_tw(start=10, end=35,

martfile=’mymodel.mart’, pastpfile=’mymodel.pastp’)

pymarthe.utils.marthe_utils.get_tw(mm=None, martfile=None, pastpfile=None, tw_type='date')

Function to extract model time window in .mart file.

Parameters:

mm (MartheModel, optional)MartheModel with correct .mldates and .mlfiles.

If None, martfile and pastpfile arguments will be considered. Default is None.

martfile (str, optional)related model .mart file

Default is None.

pastpfile (str, optional)related model .mart file

Default is None.

tw_type (str, optional)time window output type.

Can be :

‘date’ : return pd.timestamp objects
‘istep’: return integers

Default is ‘date’.

Returns:

tw_min, tw_max (tuple): time window bounds (start/end)

Examples:

# – From isteps istart, iend = get_tw(mm=mm, tw_type=’istep’) # – Get time window dates start, end = get_tw(mm=mm, tw_type=’date’) # – From external files start, end = get_tw(martfile=’mymodel.mart’, pastpfile=’mymodel.pastp’)