pymarthe.moptim

Contains the MartheOptim class Designed for structured grid

Attributes

NO_DATA_VALUES
base_obs
base_param
encoding

Classes

MartheModel	Wrapper MARTHE --> Python
MartheObs	Class to manage Marthe or external observations for PEST coupling purpose
MartheListParam	Class for handling Marthe list-like properties.
MartheGridParam	Class for handling Marthe grid-like properties.
MartheOptim	Wrapper Python --> PEST.

Module Contents

class pymarthe.moptim.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.moptim.MartheObs(iloc, locnme, date, value, obsfile=None, datatype='head', nodata=None, **kwargs)

Class to manage Marthe or external observations for PEST coupling purpose

get_obs_df(transformed=False)

Extract a copy of observation data.

Parameters:

transformed (bool, optional)whatever apply transformation on output DataFrame.

Default is False.

Returns:

obs_df (DataFrame) : standard observation DataFrame.

Examples:

mobs.get_obs_df(transformed=True)

write_insfile()

Write formatted instruction file (pest). Wrapper of pest_utils.write_insfile().

Parameters:

Returns:

Write insfile file.

Examples:

mobs.write_insfile()

write_simfile(prn='historiq.prn')

Write formatted simulated file (pest). Wrapper of pest_utils.extract_prn(). Note: to get the related simulated values don’t

forget to (re)run the Marthe model before.

Parameters:

prn (str, optinal)path to the simulated values file.

Default is ‘historiq.prn’.

Returns:

Write simfile file.

Examples:

mobs.write_simfile()

to_config()

Convert MartheObs main informations to string.

__str__()

Internal string method.

class pymarthe.moptim.MartheListParam(parname, mobj, kmi, value_col='value', trans='none', btrans='none', defaultvalue=None, **kwargs)

Class for handling Marthe list-like properties.

gen_parnmes()

Internal method to generate parmaeters names from kmi.

Returns:

parnmes (list) –

Notename will be created as ‘item0__item1__…_itemN’

where items are kmi possible values.

Return type:

parameters names according to keys values of kmi.

Examples

parnmes = mlp.gen_parnmes()

get_param_df(transformed=False)

Return internal parameter DataFrame.

Parameters:

• (bool (transformed) – Default is False.

• optional) (whatever apply transformation on output DataFrame.) – Default is False.

Returns:

param_df (DataFrame) –

Format:

parnme trans btrans parchglim defaultvalue parlbnd parubnd pargp scale offset dercom

parname cap_soil_progr_01 cap_soil_progr_01 log10 lambda x: 10**x factor 40 1.000000e-10 1.000000e+10 csp 1 0 1 cap_soil_progr_02 cap_soil_progr_02 log10 lambda x: 10**x factor 40 1.000000e-10 1.000000e+10 csp 1 0 1 … … … … … … … … … … … …

Return type:

parameter data as DataFrame.

Examples

parnmes = mlp.get_param_df()

to_config()

Return the essential informations of current set of parameters to be written in the configuration file as a new parameter section.

Returns:

section (str)

Return type:

parameter section as string.

Examples

print(mlp.to_config())

write_parfile(parpath=None)

Write parameter file(s) in parameter folder. (wrapper to pymarthe.utils.pest_utils.write_mlp_parfile())

Parameters:

• (str (parpath) – If None, name taken from .parpath. Default is None.

• optional) (path to the folder where parameter files should be writen.) – If None, name taken from .parpath. Default is None.

Examples

mlp.write_parfile(parpath=’par’)

write_tplfile(tplpath=None)

Write template file(s) in template folder. (wrapper to pymarthe.utils.pest_utils.write_mlp_tplfile())

Parameters:

• (str (tplpath) – If None, name taken from .tplpath. Default is None.

• optional) (path to the folder where template files should be writen.) – If None, name taken from .tplpath. Default is None.

Examples

mglp.write_tplfile(tplpath=’tpl’)

__str__()

Internal string method.

class pymarthe.moptim.MartheGridParam(parname, mobj, izone=None, pp_data=None, trans='none', btrans='none', defaultvalue=None, **kwargs)

Class for handling Marthe grid-like properties.

set_izone(izone=None)

Manage izone (MartheField) input. It will detect zone ids:

• izone < 0 : zone of piecewise constancy

• izone > 0 : zone with pilot points

• izone = -9999, 0, 9999 : inactive zone

Parameters:

• (str/MartheField (izone) – If None, a generic field will be created from the input mobj with a unique zpc zone (in active cells) for each layer. Default is None.

• optional) (field with required zone ids as values.) – If None, a generic field will be created from the input mobj with a unique zpc zone (in active cells) for each layer. Default is None.

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’]) active = mm.query_grid(active=1, layer=0, target=’node’).values izone[‘value’][active] = -2 mgp.set_izone(izone)

get_dv_from_lz(layer, zone, agg=None)

Extract ‘default value’ as field mean for a given layer and zone id.

Parameters:

• (int) (zone) –

• (int) –

• (func/str (agg) –

• optional) (string/function to aggregate value.) –

Returns:

dv (float)

Return type:

default value(s).

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’]) mgp.get_dv_from_lz(layer=2, zone=1)

get_dv_from_xy(x, y, layer, agg=None)

Extract ‘default value’ as field mean for at given xy-coordinates

Parameters:

• (float/it) (y) –

• (float/it) –

• (int) (layer) –

• (func/str (agg) –

• optional) (string/function to aggregate value.) –

Returns:

dv (float)

Return type:

default value(s).

Examples

ppx,ppy = pest_utils.shp2points(‘myppoints.shp’) mgp.get_dv_from_xy(ppx, ppy)

init_zpc_df()

Initialise zone of piecewise constancy DataFrame

set_zpc_value(value, layer=None, zone=None)

Set value of required zone of piecewise constancy.

Parameters:

• (float/int) (value) –

• (int/it (zone) – If None, all layers will be considered. Default is None.

• optional) (zone id to set value.) – If None, all layers will be considered. Default is None.

• (int/it – If None, all zones (zpc) will be considered. Default is None.

• optional) – If None, all zones (zpc) will be considered. Default is None.

Return type:

Set values in .zpc_df

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’]) mgp.set_zpc_value(value= 1e-3, layer=[0,1], zone=-1)

init_pp_dic()

Initialize pilot points dictionary. Format : { layer_0 : pp_df_0,

layer_1 : pp_df_1, …, layer_N: pp_df_N}

zone_interp_coords(layer, zone)

Fetch centroid coordinates of required zone to perform pilot points interpolation.

Parameters:

• (int) (zone) –

• (int) –

Returns:

(xc,yc) (tuple [1D-array])

Return type:

x,y coordinates of cell centers.

Examples

mgp.zone_interp_coords(layer=0, zone=-1)

default_pp_coords(layer, zone)

Infer pilot point coordinates for a specific zone in a required layer. Pilot points will be regularly spaced on each x,y direction with adefault spacing of two times the average distance between all centroids of the current active cells.

Parameters:

• (int) (zone) –

• (int) –

Returns:

pp_coords (np.ndarray [(N,2)])

Return type:

coordinates of generated pilot points.

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’], ipermh) pp_l2_z1 = mgp.pp_coords(layer=2, zone=1)

build_pp_df(coords, layer, zone)

Create pilot point Dataframe from xy-coordinates with generic names. Wrapper to PilotPoints.pp_df_from_coords().

Parameters:

• (list/array) (coords) – Format : [[ppx_0, ppy_0], …, [ppx_N, ppy_N]]

• (int) (zone) –

• (int) –

Returns:

pp_df (Dataframe) –

Format:

parname x y zone value

parname hk_l04_z01_00 hk_l04_z01_00 357.136364 209.0 1 1.780510e-05 hk_l04_z01_01 hk_l04_z01_01 373.681818 209.0 1 4.042830e-05 … … … … . … hk_l04_z01_N hk_l04_z01_N 357.136364 225.4 1 1.337280e-05

Return type:

pilot point standard DataFrame.

Examples

coords = shp_utils.shp2points(‘gis/pp_l04.shp’, stack=True) pp_df = mgp.build_pp_df(coords, layer=4, zone=1)

write_parfile(parpath=None, only_zpc=False, only_pp=False)

Write parameter file(s) in parameter folder. (wrapper to pymarthe.utils.pest_utils.write_mgp_parfile())

Parameters:

• (str (parpath) – If None, name taken from .parpath. Default is None.

• optional) (write pilot point parameter file(s) only.) – If None, name taken from .parpath. Default is None.

• (bool (only_pp) – Default is False.

• optional) – Default is False.

• (bool – Default is False.

• optional) – Default is False.

Examples

mgp.write_parfile(parpath=’par’, only_zpc=True)

write_tplfile(tplpath=None, only_zpc=False, only_pp=False)

Write template file(s) in template folder. (wrapper to pymarthe.utils.pest_utils.write_mgp_tplfile())

Parameters:

• (str (tplpath) – If None, name taken from .tplpath. Default is None.

• optional) (write pilot point template file(s) only.) – If None, name taken from .tplpath. Default is None.

• (bool (only_pp) – Default is False.

• optional) – Default is False.

• (bool – Default is False.

• optional) – Default is False.

Examples

mgp.write_tplfile(tplpath=’tpl’, only_zpc=True)

write_kfac(vgm_range, krig_transform='none', parpath=None, save_cov=False)

Compute and write kriging factor files (PEST-like) from exponential variogram ranges for each layer and zone of pilot points. Wrapper of some pyemu tools :

• pyemu.utils.geostats.ExpVario

• pyemu.utils.geostats.GeoStruct

• pyemu.utils.geostats.OrdinaryKrige

Note: the ranges must be in the same distance unit as the model fields.

Parameters:

• dict) (vgm_range (float/int/dict/nested) –

  Can be :

  • numeric

  • dictionary

    format: {layer_0range_0,

    …, layer_i : range_i }

  • nested dictionary

    format: {layer_0{zone_0: range_0_0, …, zone_i: range_0_i},

    …, layer_i : {zone_0: range_i_0, …, zone_i: range_i_i} }

• (str (parpath) –

  pyemu.utils.geostats.GeoStruct. Can be:

  • ’none’

  • ’log’

  Default is ‘none’.

• optional) (whatever write the covariance matrices as binary files.) –

  pyemu.utils.geostats.GeoStruct. Can be:

  • ’none’

  • ’log’

  Default is ‘none’.

• (str –

  If None, it will take the `.kfacpath’ argument. Default is None. Note: a kriging factor files will be written for each

  pilot point layer and zone. The file name will be generated as ‘{parname}_l{layer}_z{zone}.fac’.

• optional) –

  If None, it will take the `.kfacpath’ argument. Default is None. Note: a kriging factor files will be written for each

  pilot point layer and zone. The file name will be generated as ‘{parname}_l{layer}_z{zone}.fac’.

• (bool (save_cov) –

  Default is False. Note: the covariance matrices files will take the same

  names as kriging factor files with the ‘.jcb’ extension.

• optional) –

  Default is False. Note: the covariance matrices files will take the same

  names as kriging factor files with the ‘.jcb’ extension.

Returns:

• Write kriging factor file in parameter path (with ‘.fac’ extension).

• If save_cov is True, the covariance matrix will be written in

• parameter path too (with extension ‘.jcb’).

Examples

vgm_range= {2: {1:100}, 3: {1:200,2:150}} mgp.write_kfac(vgm_range, vgm_transform= ‘log’, save_cov=True)

get_param_df(transformed=False)

Join all parameter informations in a single DataFrame for the current field.

Parameters:

• (bool (transformed) – Default is False.

• optional) (whatever apply transformation on output DataFrame.) – Default is False.

Returns:

param_df (DataFrame)

Return type:

parameter information of current field.

Examples

mgp.get_param_df()

to_config()

Return the essential informations of current set of parameters to be written in the configuration file as a new parameter section.

Returns:

section (str)

Return type:

parameter section as string.

Examples

print(mgp.to_config())

__str__()

Internal string method.

pymarthe.moptim.NO_DATA_VALUES

pymarthe.moptim.base_obs = ['obsnme', 'date', 'obsval', 'datatype', 'locnme', 'obsfile', 'weight', 'obgnme', 'trans']

pymarthe.moptim.base_param = ['parnme', 'trans', 'btrans', 'parchglim', 'defaultvalue', 'parlbnd', 'parubnd', 'pargp',...

pymarthe.moptim.encoding = 'latin-1'

class pymarthe.moptim.MartheOptim(mm, name=None, **kwargs)

Wrapper Python –> PEST. Interface to prepare PEST usefull files such as instruction, template, control from a Marthe model and other external data.

get_obs_df(transformed=False)

Get all observations information in a large DataFrame.

Parameters:

transformed (bool, optional)whatever apply transformation on output DataFrame.

Default is False.

Returns:

obs_df (DataFrame) : merged provided observations

Examples:

moptim.get_obs_df(transformed=True)

get_param_df(transformed=False)

Get all parameters informations in a large DataFrame.

Parameters:

transformed (bool, optional)whatever apply transformation(s) on

parameter data sets. Default is False.

Returns:

param_df (DataFrame) : merged provided parameters

Examples:

moptim.get_param_df(transformed=True)

get_nobs(locnme=None, null_weight=True)

Function to fetch number of observation stored in MartheOptim instance.

Parameters:

locnme (str/it, optinonal) : name of a set of observation null_weight (bool, optional) : consider observation with null weight.

Default is True

Returns:

nobs (int) : number of observation

Examples:

print(f”There are {moptim.get_nobs()} observations.”)

get_nlocs(datatype=None)

Function to fetch number of set of observation stored in MartheOptim instance.

Parameters:

datatype (str/it, optional) : required data type

Returns:

nlocs (int) : number of set of observation

Examples:

print(f”There are {moptim.get_nlocs()} observations.”)

get_ndatatypes()

Function to fetch number of observation data types stored in MartheObs instance

Parameters:

self : MartheObs instance

Returns:

ndatatypes (int) : number of observation data types

Examples:

ndt = moptim.get_ndatatypes() print(f”There are {ndt} observation data types”)

check_loc(locnme, error='raise')

Check existence and uniqueness of a given locnme.

Parameters:

locnme (str)observation localisation

name to test

error (str)error type to handle.

Can be : - ‘raise’: assertions. - ‘silent’: boolean return. - ‘off’: inactive. Default is ‘raise’.

Returns:

exi (bool) : locnme validity/existence uni (bool) : locnme unicity

Examples:

moptim = MartheOptim(mm, ‘opti’) locnme = ‘mylocname’ exi, uni = moptim.check_loc(locnme)

add_obs(data, locnme=None, datatype='head', check_loc=True, nodata=None, **kwargs)

Add and set observations

Parameters:

data (object): observation data.

Can be a path to a observation file to read (wrapper to marthe_utils.read_obsfile()) or a pandas DataFrame with a column value and a pd.DatatimeIndex as index. Note: if loc_name is not provided, the loc_name is set as obsfile without file extension.

locnme (str, optional) : observation location name (ex. BSS id)

datatype (str, optional): data type of observation values.

Default is ‘head’.

check_loc (bool, optional)check loc_name existence and unicity

Default is True.

nodata (list/None, optional)no data values to remove reading observation data.

If None, all values are considered. Default is None. NOTE: can create issues with incomplete series sim/obs mismatch.

obgnme (str, kwargs): name of the group of related observation.

Default is locnme.

obnmes (list, kwargs): custom observation names

Default build as ‘loc{loc_name_id}n{obs_id}’

weight (list, kwargs): weight per each observations

trans (str/func, kwargs)keyword/function to use for transforming

observation values. Can be:

• function (np.log10, np.sqrt, …)

• string function name (‘log10’, ‘sqrt’)

Returns:

Add set of observation inplace.

Examples:

moptim.add_obs(data = ‘obs/07065X0002.dat’)

remove_obs(locnme=None, verbose=False)

Delete provided observation(s)

Parameters:

locnme (str/it, optional)observation location name (ex. BSS id).

If None, all locnmes will be removed. Default is None.

verbose (bool) : print message about deleted observation(s)

Returns:

Delete observation(s) by locnme in observation dictionary.

Examples:

moptim.delete_obs(‘p31’)

remove_param(parname=None, verbose=False)

Delete provided parameter(s).

Parameters:

parname (str/it, optional)parameter name(s) (ex. ‘p31’).

If None, all locnmes will be removed. Default is None.

verbose (bool) : print message about deleted parameter(s)

Returns:

Delete parameters(s) by parname in parameter dictionary.

Examples:

moptim.delete_param(‘p31’)

set_obs_trans(trans, datatype=None, locnme=None)

Set transformation keyword to observations values.

Parameters:

trans (str/func)keyword/function to use for transforming

observation values. Can be:

• function (np.log10, np.sqrt, …)

• string function name (‘log10’, ‘sqrt’)

datatype (str, optional): data type of observation values.

Default is ‘head’.

locnme (str, optional) : observation location name (ex. BSS id)

Returns:

Set trans argument for required observations.

Examples:

moptim.set_trans(‘log10’, datatype=[‘head’, ‘flow’])

set_param_trans(trans, btrans, parname=None, pargp=None)

Set transformation keyword to parameters values.

Parameters:

trans (str)keyword/function to use for transforming

parameter values.

btrans (str)keyword/function to use for back transforming

parameter values.

parname (str/it, optional): parameter name.

If None, all parameters will be consider. Default is None.

pargp (str/it, optional)parameter group.

If None, all parameter groups will be consider. Default is None.

Returns:

Set trans and btrans argument for required parameter values.

Examples:

moptim.set_param_trans(‘log’, ‘np.exp’, pargp = ‘pump’)

write_insfile(locnme=None, cleanup=True)

Write formatted instruction file in instruction directory (.ins_dir). Wrapper of pest_utils.write_insfile().

Parameters:

locnme (str, optional)observation location name (ex. BSS id)

If None all locnmes are considered. Default is None

cleanup (bool, optional)remove all existing file with .ins

extension in .ins_dir. Default is True.

Returns:

Write insfile file in ins_dir

Examples:

moptim.write_insfile(locnme = ‘myobs’)

write_simfile(locnme=None, prnfile=None)

Write formatted simulated file in simulate directory (.sim_dir). Wrapper of pest_utils.extract_prn(). Note: to write the related simulated values don’t

forget to (re)run the Marthe model before.

Parameters:

locnme (str, optional)observation location name (ex. BSS id)

If None all locnmes are considered. Default is None.

prnfile (str, optional)path to the simulated value file.

If None, prnfile = model_path + ‘historiq.prn’. Default is None.

Returns:

Write simfile file in .ins_dir

Examples:

moptim.write_simfile(locnme = ‘myobs’)

add_fluc(locnme=None, tag='', on='mean', **kwargs)

Add fluctuations to a existing observation set.

Parameters:

locnme (str/list, optional)observation location name(s) (ex. BSS id)

If locnme is None, all locnmes are considered Default is None

tag (str, optional)additional string to precise the type of fluctuation.

locnme build as locnme + tag + ‘fluc’. Default is ‘’.

on (str/numeric/fun, optional)function, function name or real number to substract

to the existing observation values. Function names can be ‘min’, ‘max’, ‘mean’, ‘std’, etc. See pandas.core.groupby.GroupBy documentation for more.

weight (list, kwargs): weight per each observations

Returns:

Write and add a new set of observation as a fluctuation of a existing one.

Examples:

moptim.add_fluc(locnme = [‘obs1’, ‘obs2’], tag = ‘md’, on = ‘median’)

compute_weights(lambda_dic=None, sigma_dic=None)

Compute weigths for all observations.

Parameters:

• (dict) (- sigma_dic) – Format: {datatype0 : lambda_0, … datatypeN : lambda_N} If None, all tuning factors are set to 1. Default is None.

• (dict) – Format: {datatype0 : sigma_0, … datatypeN : sigma_N} If None, all variaces are set to 1. Default is None

Return type:

Set weights in self.mobs_df[‘weight’] column.

Examples

mm.mobs.compute_weights(lambda_dic)

add_param(parname, mobj, **kwargs)

Add a parameter a set of parameters.

Parameters can be either:

• distributed (‘grid’): based on izone object which represent a pointer

  to a Marthefield instance where field values are gathered in zones like: - izone < 0 ==> zone of piecewise constancy - izone > 0 ==> zone with pilot points - izone = -9999, 0, 9999 ==> inactive zone

• globals (‘list’): based on kmi (KeysMultiIndex) which represent the

  referenced DataFrame columns names to be included in the parametrization. Note: the built-in fonction pymarthe.utils.pest_utils.get_kmi()

  make the kmi generation easier.

Parameters:

• (str) (- mobj) –

• (str) –

  Can be a:

  • MartheField instance (grid)

  • MartheSoil instance (list)

  • MarthePump instance (list)

Examples

# – Example on pumping data mm.load_prop(‘soil’) mp = mm.prop[‘aqpump’] kmi_p31 = pest_utils.get_kmi(mp, keys = [‘boundname’, ‘layer’, ‘istep’], boundname = ‘p31’) mgp.add_param(parname=’p31’, mobj=mp,

kmi=kmi_p31, defaultvalue=-1e-3)

# – Example on soil data mm.load_prop(‘soil’) ms = mm.prop[‘soil’] kmi_soil = pest_utils.get_kmi(ms, keys=[‘soilprop’, ‘zone’], istep=0) mopt.add_param(parname=’soil’, mobj=ms, kmi=kmi_soil)

# – Example on distributed parameter mm.load_prop(‘permh’) mf = mm.prop[‘permh’] pp_data = {1:{1:’gis/pp_l01.shp’}, 2:{1:’gis/pp_l02.shp’}} mopt.add_param(parname=’hk’, mobj=mf,

izone=’mymodel.ipermh’, pp_data=pp_data, trans=’log10’, btrans=’lambda x: 10**x’)

write_kriging_factors(vgm_range, parname=None, krig_transform='none', save_cov=False, cleanup=True)

Compute and write kriging factor files (PEST-like) from exponential variogram ranges for given distributed parameters. Wrapper to MartheGridParam.write_kfac().

Note: the ranges must be in the same distance unit as the model fields.

Parameters:

• dict) (vgm_range (float/int/dict/nested) –

  Can be :

  • numeric

  • dictionary

    format: {layer_0range_0,

    …, layer_i : range_i }

  • nested dictionary

    format: {layer_0{zone_0: range_0_0, …, zone_i: range_0_i},

    …, layer_i : {zone_0: range_i_0, …, zone_i: range_i_i} }

• (str (krig_transform) – If None, all distributed parameters will be considered. Default is None.

• optional) (remove all existing file with .fac) – If None, all distributed parameters will be considered. Default is None.

• (str –

  pyemu.utils.geostats.GeoStruct. Can be:

  • ’none’

  • ’log’

  Default is ‘none’.

• optional) –

  pyemu.utils.geostats.GeoStruct. Can be:

  • ’none’

  • ’log’

  Default is ‘none’.

• (bool (cleanup) –

  Default is False. Note: the covariance matrices files will take the same

  names as kriging factor files with the ‘.jcb’ extension.

• optional) –

  Default is False. Note: the covariance matrices files will take the same

  names as kriging factor files with the ‘.jcb’ extension.

• (bool – extension in .par_dir. Default is True.

• optional) – extension in .par_dir. Default is True.

Returns:

• Write kriging factor file in parameter path (with ‘.fac’ extension).

• If save_cov is True, the covariance matrix will be written in

• parameter path too (with extension ‘.jcb’).

Examples

vgm_range= {2: {1:100}, 3: {1:200,2:150}} mopt.write_kriging_factors(vgm_range, parname=’hk’, vgm_transform= ‘log’, save_cov=True)

write_config(filename=None)

Write a standard text (.config) with the essential informations about current parametrisation. The file is organised in 3 parts:

• Headersgeneral paths to Marthe model, spatial index, statistics

  about observations and parameters sets, …

• Observation sectionsblocks of informations about observation data.

  Each block (=section) is delimited by a:

  • start marker : ‘[START_OBS]’

  • end marker : ‘[END_OBS]’

• Parameter sectionsblocks of informations about parameter data.

  Each block (=section) is delimited by a:

  • start marker : ‘[START_PARAM]’

  • end marker : ‘[END_PARAM]’

Parameters:

(str) (filename) – If None, filename will be construct from the current MartheOptim parametrisation name with the extension ‘.config’. Default is None.

Examples

mopt.write_tplfile() mopt.write_parfile() mopt.write_kriging_factors(vgm_range=9) mopt.write_config(filename=’parametrisation.config’)

write_parfile(parname=None, cleanup=True)

Write parameter file(s) in parameter directory (par_dir).

Parameters:

• (str (parname) – If None, all provided parameters will be considered. Default is None.

• optional) (remove all existing file with .dat) – If None, all provided parameters will be considered. Default is None.

• (bool (cleanup) – extension in .par_dir. Default is True.

• optional) – extension in .par_dir. Default is True.

Examples

mopt.write_parfile([‘soil’, ‘hk’])

write_tplfile(parname=None, cleanup=True)

Write template file(s) in template directory (tpl_dir).

Parameters:

• (str (parname) – If None, all provided parameters will be considered. Default is None.

• optional) (remove all existing file with .tpl) – If None, all provided parameters will be considered. Default is None.

• (bool (cleanup) – extension in .tpl_dir. Default is True.

• optional) – extension in .tpl_dir. Default is True.

Examples

mopt.write_tplfile([‘soil’, ‘hk’])

write_forward_run(fr_file, configfile, extra_py_imports=[], extra_functions=[], preproc_functions=[], **kwargs)

Write forward run python file. Note : if some extra functions are provided, the inspect

python module will be required.

Parameters:

fr_file (str) : forward run python file to write.

configfile (str)pointer to .config file.

Note: used by pest_utils.run_from_config().

extra_py_imports (str/list[str], optional)additional python module to import.

Default is [].

extra_functions (str/list[str], optional)additional post-processing functions

to import. Default is [].

kwargsadditional argument of MartheModel.run_model() method.

Can be :

• exe_name (str)

• verbose (bool)

• silent (bool)

• …

Examples:

# – Set additional functions def foo():

s=’get upper case’ return s.upper()

def bar():

return glob.glob(‘.’)

# – Write forward run file mopt.write_forward_run(fr_file= ‘forward_run.py’,

configfile= ‘mysettings.config’, extra_py_imports=’glob’, extra_functions=[foo, bar], exe_name= ‘Marth_R8’)

collect_pest_files(ftypes=['tpl', 'par', 'ins', 'sim'])

Collect pest io files as list(s).

Parameters:

• (str/iterable (ftypes) –

  The file aliases can be:

  • Template files: ‘template’, ‘tpl_file’ , ‘tpl’

  • Input files: ‘parameter’, ‘in_file’ , ‘in’ , ‘par’

  • Instruction files: ‘instruction’, ‘ins_file’, ‘ins’

  • Output files: ‘simulated’, ‘out_file’, ‘out’, ‘sim’

  If not provided, ftypes will collect all pest io files required for pyemu.Pst.from_io_files() function. Default is [‘tpl’, ‘par’, ‘ins’, ‘sim’].

• optional) (pest file type aliases or list of pest file type aliases.) –

  The file aliases can be:

  • Template files: ‘template’, ‘tpl_file’ , ‘tpl’

  • Input files: ‘parameter’, ‘in_file’ , ‘in’ , ‘par’

  • Instruction files: ‘instruction’, ‘ins_file’, ‘ins’

  • Output files: ‘simulated’, ‘out_file’, ‘out’, ‘sim’

  If not provided, ftypes will collect all pest io files required for pyemu.Pst.from_io_files() function. Default is [‘tpl’, ‘par’, ‘ins’, ‘sim’].

Returns:

pest_files (list)

Return type:

required ordered collected pest files.

Examples

mopt.collect_pest_files(‘instruction’) mopt.collect_pest_files([‘tpl_file’, ‘in_file’])

build_pst(add_reg0=False, write_pst=False, write_config=False, write_fr=False, model_command=None, **kwargs)

Generate Pest Control File from the current observation and parameters sets added to MartheOptim instance.

Parameters:

• (bool (add_reg0) – Wrapper to pyemu.helpers.zero_order_tikhonov() Default is False.

• optional) (command(s) to launch forward run.) – Wrapper to pyemu.helpers.zero_order_tikhonov() Default is False.

• (bool/str (write_fr) – If True, the Pest Control File will be written with a generic name: ‘name_of_MartheOptim_instance.pst’. If string, the Pest Control File will be written with the user provided name. If False, the Pest Control File will not be written. Default is False.

• optional) – If True, the Pest Control File will be written with a generic name: ‘name_of_MartheOptim_instance.pst’. If string, the Pest Control File will be written with the user provided name. If False, the Pest Control File will not be written. Default is False.

• (bool/str – If True, the .config file will be written with a generic name: ‘name_of_MartheOptim_instance.config’. If string, the .config file will be written with the user provided name. If False, the .config file will not be written. Default is False.

• optional) – If True, the .config file will be written with a generic name: ‘name_of_MartheOptim_instance.config’. If string, the .config file will be written with the user provided name. If False, the .config file will not be written. Default is False.

• (bool/str – If True, the forward run file will be written with a generic name: ‘forward_run.py’. If string, the forward run file will be written with the user provided name. If False, the forward run file will not be written. Default is False.

• optional) – If True, the forward run file will be written with a generic name: ‘forward_run.py’. If string, the forward run file will be written with the user provided name. If False, the forward run file will not be written. Default is False.

• (str/list (model_command) – If None and write_fr == True|str the default command will be ‘python3 {forward_run_file}’. If None and write_fr == False, the default command will be ‘model.bat’ (no changes from pyemu). Default is None.

• optional) – If None and write_fr == True|str the default command will be ‘python3 {forward_run_file}’. If None and write_fr == False, the default command will be ‘model.bat’ (no changes from pyemu). Default is None.

• **kwargs –

  • control_data section:

    • noptmax

    • jcosaveitn

    • reisaveitn

    • parsaveitn

    • … (see pst.control_data.__dict__[‘_df’].index for more)

  • reg_data section:

    • phimlim

    • phimaccept

    • fracphim

    • iregadj

    • … (see pst.reg_data.__dict__.keys() for more)

• pyemu.Pst (additional internal arguments that refer to the) –

  • control_data section:

    • noptmax

    • jcosaveitn

    • reisaveitn

    • parsaveitn

    • … (see pst.control_data.__dict__[‘_df’].index for more)

  • reg_data section:

    • phimlim

    • phimaccept

    • fracphim

    • iregadj

    • … (see pst.reg_data.__dict__.keys() for more)

Returns:

pst (pyemu.pst.Pst)

Return type:

pyemu Pst instance.

Examples

pst = mopt.build_pst(add_reg0=True,

write_pst=’mycalibration.pst’, write_config=True, write_fr=True, noptmax=0, phimlim=1)

__str__()

Internal string method.