pymarthe.mfield

Contains the classes related to field data. Designed for handling distributed Marthe properties (structured and unstructured grid)

Attributes

encoding
dmv

Classes

MartheGrid	Class to handle Marthe single grid.
MartheField	Wrapper Marthe --> python
MartheFieldSeries	Wrapper Marthe --> python

Module Contents

class pymarthe.mfield.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.mfield.encoding = 'latin-1'

pymarthe.mfield.dmv

class pymarthe.mfield.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.mfield.MartheFieldSeries(mm, chasim=None)

Wrapper Marthe –> python Manage series of MartheField instances.

check_fieldname(fieldname, raise_error=True)

Check if field name exist and is already added to main .data dictionary.

Parameters:

• (str) (fieldname) –

• (bool (raise_error) – just returning boolean response.

• optional) (whatever raising error on checks or) – just returning boolean response.

• Returns –

• -------- –

• (tuple[bool]) (res) – (only available when raise_error is False).

Examples

exist, load = mfs.check_fieldnames(‘%saturation’, raise_error=False)

load_field(field, istep=None)

Set dictionary of MartheField instances in .data. Format: { istep_0: MartheField_0,

…, istep_N: Marthefield_N}

Parameters:

• (str) (field) –

  Notemust be written with the same

  typology as written in the chasim file.

• (int/it (istep) – sequence of timesteps. If None, all simulated timesteps will be considered. Default is None.

• optional) (required timestep number or) – sequence of timesteps. If None, all simulated timesteps will be considered. Default is None.

Examples

mm = MartheField(‘mona.rma’) mfs = MartheFieldSeries(mm, chasim=None) mfs.load_field(‘CHARGE’, istep= list(range(20)))

get_tseries(field, x, y, layer, names=None, index='date', masked_values=dmv[::2], base=0)

Sample field data by x, y, layer coordinates and stack timeseries in a DataFrame. It will perform simple a spatial intersection with field data.

Parameters:

field (str) : required field names.

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

layer (int/iterable) : layer id(s) to intersect data.

names (str/list of str, optional)additional names of each required point coordinates.

If None, standard names are given according to the coordinates. Example: ‘23i_45j_6k’ Default is None.

masked_values (None/list): values to ignore during the sampling process

Default are [-9999, 0, 9999].

index (str, optional)type of index required for the output DataFrame.

Can be:

• ‘date’: index is a pd.DatetimeIndex.

• ‘istep’: index is a pd.index

• ‘combined’: index is a pd.MultiIndex(pd.index, pd.DatetimeIndex)

Default is ‘date’.

base (int, optional)spatial coordinates base reference.

Default is 0. Note : only use to build default output DataFrame columns

when names is not provided.

Reminder : Python is 0-based and Marthe is compiled in 1-based (Fortran).

Returns:

df (DataFrame): Output timeseries stack in DataFrame.

Examples:

x, y = [343., 385.3], [223., 217.2] layer = 0 names = [‘rec1’, ‘rec2’] df = mfs.get_tseries(‘CHARGE’, x, y, layer, names)

save_animation(field, filename, dpf=0.25, dpi=200, **kwargs)

Build a .gif animation from a series of field data. /!/ Package imageio required /!/

Parameters:

field (str) : required field names.

filename (str)required output file name.

Example: ‘myfieldanimation.gif’

dpf (float, optional)duration per frame (in second).

Default is 0.25.

dpi (int, optional)dots per inch (=image/plot resolution).

Default is 200.

**kwargs : MartheField.plot arguments.

Returns:

Save .gif animation in filename.

Examples:

mfs.save_animation(‘CHARGE’, ‘chargeout.gif’, dpf = 0.2, dpi=200, layer=5, cmap=’jet’)

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

Save field series in shapefile.

Parameters:

field (str) : required field name.

filename (str, optional)shapefile name 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:

Save vectorial geometries and records in filename.

Examples:

mfs.to_shapefile(layer=3)

__str__()

Internal string method.