Content

Accessing Nodal and Elemental Model Data

  • doc.c.mesh (.df / .gdf): Generate lists / DataFrames of nodes and elements (including parameter values), Discrete Feature Elements, Multi-Layer-Wells and more.

  • doc.c.sel: Query information and item lists of elemental and nodal selections. Also provides operations like conversions.

  • doc.c.content: Get Content Panel readouts as DataFrame.

Plotting and Visualization

  • doc.c.plot: Create 2D matplotlib figures similar to the Slice View. Supports a number of items known from the View Components Panel of the GUI. Default settings are chosen to mimic the appearance of the FEFLOW GUI (including colormaps).

  • doc.c.plot.gdf: Create fringes and isolines as vector data (GeoDataFrames). Similar to the export plots… function of the View Components Panel.

History charts and Time Series

Observation Points

  • doc.c.obs.gdf: get observatoin point information as GeoDataFrames

Accessing Nodal and Elemental Model Data

doc.c.mesh - Model Properties

class ifm_contrib.contrib_lib.mesh.Mesh(doc)

Functions to obtain data of FEFLOWs Data Panel.

getCentroid(item, localcos=False, itemtype=1)

Return the centroid of an element as (X, Y, Z) coordinate Tuple

Parameters

  • item (int) – item number (e.g. element number)

  • localcos (bool) – Return local coordinate system if true, global otherwise (default).

  • itemtype (int (ifm.Enum.SEL_*)) – item type (E

Returns

coordinate (x,y,z) of the centroid

Return type

tuple

get_borders()

Return border nodes as a dictionary {key: border number, value: list of node numbers}.

Returns

get_imatrix(layer=None, split_quads_to_triangles=False, ignore_inactive=False, return_elements=False)

return the incidence matrix as [[int]].

Parameters

  • layer – specifies a layer number to return. If None (default), return all layers

  • split_quads_to_triangles – split 4/8-nodes elements into two 3/6-noded elements

  • ignore_inactive – do not include inactive elements

Returns

list (len=n_elements) of lists of node numbers

get_imatrix2d(slice=1, split_quads_to_triangles=False, ignore_inactive=False, return_elements=False)

return the incidence matrix as [[int]] of a slice.

Parameters

  • split_quads_to_triangles – split 4/8-nodes elements into two 3/6-noded elements

  • ignore_inactive – do not include inactive elements

Returns

list (len=n_elements) of lists of node numbers

imatrix_as_array(global_cos=True, split_quads_to_triangles=False, layer=None, ignore_inactive=False, use_cache=True, as_2d=False)

load the nodes coordinates, the incidence matrix into a numpy matrix

Parameters

global_cos – If True, use global coordinate system (default: local)

Returns

tuple(numpy.Array) (x, y, imat)

mlw(global_cos=True)

Return a dictionary with information on all Multi-Layer wells in the model.

Returns

dictionary

Return type

dict

doc.c.mesh.df - Model Properties (Pandas)

class ifm_contrib.contrib_lib.mesh_pandas.MeshPd(doc)

Functions to obtain data of FEFLOWs Data Panel as geopandas.GeoDataFrames

dfe()

Reutrn a DataFrame with information on Discrete Feature Elements in the model.

Returns

DataFrame with information on DFE

Return type

pandas.DataFrame

edges()

Return a DataFrame with Edges and corresponding properties. :return:

elements(par=None, expr=None, distr=None, layer=None, selection=None, centroids=False, content=None)

Create a Pandas Dataframe with information on the model elements.

Parameters

  • par (dict, list or ifm.Enum) – Create additional columns with parameter values. Parameter are provided as ifm.Enum. Multiple columns are created if a list is provided. Columns can be givens custom names if a dict {column name : parid} is provided.

  • distr (str or list) – Name or list of names of user distributions. For each uer distribution provided, a column with distribution values will be added to the DataFrame.

  • expr (str or list) – Name or list of names of user expressions. For each uer expression provided, a column with with distribution values will be added to the DataFrame.

  • layer (int) – if provided in a 3D model, return only elements of this layer

  • selection (str) – if provided in a 3D model, return only elements of this selection

  • centroids (bool) – if True, add coordinates of centroids to DataFrame.

  • content (None, bool, int, list[int]) – Add elemental content to datafrane. see doc.c.conent.df.info for available items. If True, all content items are returned. if int or list(int), specific items are returned.

Returns

DataFrame, index of element index, all requested information as columns.

Return type

pandas.DataFrame

faces()

Return a DataFrame with Faces properties. :return:

get_available_items(Type=None)

Return a list of available Parameters that can be obtained by calling doc.c.mesh.df.nodes or doc.c.mesh.df.elements, respectively.

Parameters

Type (str) – Filter by Type (“elemental” or “nodal”)

Returns

DataFrame with available items

Return type

pandas.DataFrame

mlw(global_cos=True)

Return a pandas.DataFrame with information on all Multi-Layer wells in the model.

Returns

Dataframe with information on Mullti-Layer-wells

Return type

pandas.DataFrame

nodes(par=None, expr=None, distr=None, global_cos=True, slice=None, selection=None, budget=None, velocity=None)

Create a Pandas Dataframe with information on the model nodes.

Parameters

  • par (dict, list or ifm.Enum) – Create additional columns with parameter values. Parameter are provided as ifm.Enum. Multiple columns are created if a list is provided. Columns can be givens custom names if a dict {column name : parid} is provided.

  • distr (str or list) – Name or list of names of user distributions. For each uer distribution provided, a column with distribution values will be added to the DataFrame.

  • expr (str or list) – Name or list of names of user expressions. For each uer expression provided, a column with with distribution values will be added to the DataFrame.

  • global_cos (bool) – if True (default), use global instead of local coordinate system

  • slice (int) – if provided in a 3D model, return only nodes of this slice

  • selection (str) – if provided, return only nodes of this selection

  • budget (bool, str or [str], None.) – add nodal budget values to dataframe. Can be “flow”, “mass”, “heat”, or a list like [“flow”, “mass]. If True, all available budgets will be created. If None, no budget is calculated (default).

Returns

DataFrame, index of element nodes, all requested information as columns.

Return type

pandas.DataFrame

doc.c.mesh.gdf - Model Properties (Geopandas)

class ifm_contrib.contrib_lib.mesh_geopandas.MeshGpd(doc)

Functions to obtain data of FEFLOWs Data Panel as geopandas.GeoDataFrames.

dfe()

Return a geoPandas.GeoDataFrame with information on all DFE in the model. :return:

elements(par=None, expr=None, distr=None, global_cos=True, layer=None, selection=None, as_2d=False, content=None, polygons_as_2d=False)

Create a GeoPandas GeoDataframe with information on the model elements.

Parameters

  • par (dict, list or ifm.Enum) – Create additional columns with parameter values. Parameter are provided as ifm.Enum. Multiple columns are created if a list is provided. Columns can be givens custom names if a dict {column name : parid} is provided.

  • distr (str or list) – Name or list of names of user distributions. For each uer distribution provided, a column with distribution values will be added to the DataFrame.

  • expr (str or list) – Name or list of names of user expressions. For each uer expression provided, a column with with distribution values will be added to the DataFrame.

  • global_cos (bool) – If True (default), use global instead of local coordinate system.

  • layer (int) – if provided in a 3D model, return only elements of this layer

  • selection (str) – if provided in a 3D model, return only elements of this selection

Returns

geopandas.GeoDataFrame

mlw(global_cos=True)

Return a geoPandas.GeoDataFrame with information on all Multi-Layer wells in the model. :return:

model_area(selection=None)

Get the model area as a single 2D polygon.

Parameters

selection (str) – if provided, return model area related to this elemental selection.

Returns

geopandas.GeoDataFrame.

model_borders()

Return a GeoDataFrame with all model borders.

Returns

Return type

shapely.geometry.LinearRing

nodes(*args, **kwargs)

Create a Pandas Dataframe with information on the model nodes.

Parameters

  • par (dict, list or ifm.Enum) – Create additional columns with parameter values. Parameter are provided as ifm.Enum. Multiple columns are created if a list is provided. Columns can be givens custom names if a dict {column name : parid} is provided.

  • distr (str or list) – Name or list of names of user distributions. For each uer distribution provided, a column with distribution values will be added to the DataFrame.

  • expr (str or list) – Name or list of names of user expressions. For each uer expression provided, a column with with distribution values will be added to the DataFrame.

  • global_cos (bool) – if True (default), use global instead of local coordinate system

  • slice (int) – if provided in a 3D model, return only nodes of this slice

  • selection (str) – if provided, return only nodes of this selection

Returns

geopandas.GeoDataFrame

doc.c.sel - Selections

class ifm_contrib.contrib_lib.sel.Sel(doc)

Functions for working with selections.

clear(selname, seltype=None)
Parameters

  • selname (str) – name of the selection to be updates

  • seltype (list) – list of allowed types of the selections (optional, default None - type will be determined)

Returns

bool

convert(selection, to_type)

Converts a selection to a selection of the given type. Currently only support elemental to nodal.

Parameters

  • selection (str) – Name of the selection to be converted

  • to_type (ifm.Enum) – type of the selection to return

Returns

list of converted items

create(seltype, selname, itemlist=None, overwrite_existing=False)

create a new selection of given type and name. Populate the selection if itemlist if provided.

Parameters

  • seltype (ifm.Enum) – Type of selection type

  • selname (str) – Name of selection

  • itemlist ([int]) – list of item indices (optional)

  • overwrite_existing (bool) – If True, overwrite an existing selection (will raise ValueError otherwise)

Returns

the id of the selection

delete(selname, seltype=None, ignore_if_missing=False)

Delete a selection of the given name. Return True if successful.

Parameters

  • selname (str) – name of the selection to be updates

  • seltype (list) – list of allowed types of the selections (optional, default None - type will be determined)

  • ignore_if_missing (bool) – If False (default), raise ValueError if selection is not found.

Returns

bool

getSelectionNames(seltype=None)

Legacy, use selections() instead

getSelectionType(selection)

Returns the type of a given selection. Returns -1 (=Enum.SEL_INVALID) if selection does not exist.

Parameters

selection (str) – name of the selection

Returns

type of selection

Return type

ifm.Enum

get_xybounds(selection, global_cos=True, zoom=1.0)

Return the bounding box of the given selection as tuple (minx, maxx, miny, maxy). If elemental selection, bounding box is calculated from centroids. :param selection: the name of the selection. :param zoom: zoom factor to be applied. :return:

list(selname, seltype=None)

Return the item indices of the given selection as a list.

Parameters

  • selname (str) – name of the selection

  • seltype (ifm.Enum or None) – type of the selection (optional)

Returns

list of item indices

selections(seltype=None)

Return a list of names of selections in the model

Parameters

seltype (ifm.Enum or None.) – Selection type (return all if None).

Returns

set(selname, seltype=None)

Return the item indices of the given selection as a set.

Parameters

  • selname (str) – name of the selection

  • seltype (ifm.Enum or None) – type of the selection

Returns

set of item indices

update(selname, itemlist, seltype=None)

Updates a selection to match the current item list :param selname: name of the selection to be updates :type selname: str :param itemlist: list with item numbers :type itemlist: list :param seltype: list of allowed types of the selections (optional, default None - type will be determined) :type seltype: list :return: bool

doc.c.content.df - Content (Pandas)

class ifm_contrib.contrib_lib.content_pandas.ContentPd(doc)

Functions regarding accessing information from the Content Panel as pandas.DataFrames.

content(model_domain=True, selection=None, content_types=True)

Get the model domains content (all content items).

Returns

DataFrame with all contents

Return type

pandas.DataFrame

info()

Return infomation on available content items.

Returns

information on content items

Return type

pandas.DataFrame

Plotting and Visualization

These objects provide functionality to create plots of the model. These are mostly used in interactive scripting environments like Jupyter or Spyder.

doc.c.plot - Matplotlib

class ifm_contrib.contrib_lib.plot.Plot(doc)

Functions for creating visual plots using the matplotlib. The function resemble the functionality of the View Components panel; The default plot styles are chosen to minmic output from FEFLOW’s user interface. Useful for visualization of the model in an interactive environments like Jupyter, or for batch processing of images. See examples for further info.

continuous(slice=1, alpha=0.5, cmap='feflow_rainbow', *args, **kwargs)

Add an interpolated color plot of the given nodal model property to the plot. Corresponds to the continuous style in FEFLOW. Note: Avoid usage when creating vector graphics (svg).

Parameters

  • slice (int) – specified the slice to be plotted in a 3D model.

  • args – see matplotlib.org/api/_as_gen/matplotlib.axes.Axes.tripcolor.html

  • kwargs – matplotlib.org/api/_as_gen/matplotlib.axes.Axes.tripcolor.html

edges(color='black', alpha=0.5, lw=1, ignore_inactive=False, *args, **kwargs)

Add the edges of the mesh to the plot. Corresponds to the geometrie > edges style in FEFLOW.

faces(color='grey', alpha=1.0, ignore_inactive=False, *args, **kwargs)

Add the faces of the model to the plot. Corresponds to the geometrie : faces style in FEFLOW.

fringes(slice=1, alpha=0.5, cmap='feflow_rainbow', *args, **kwargs)

Add fringe polygons of the given nodal model property to the plot. Corresponds to the fringes style in FEFLOW.

Parameters

slice (int) – specified the slice to be plotted in a 3D model.

Returns

matplotlib.contour.ContourSet

isolines(slice=1, alpha=1.0, *args, **kwargs)

Add isolines of the given nodal model property to the plot. Corresponds to the Isolines style in FEFLOW.

Parameters

slice (int) – specified the slice to be plotted in a 3D model.

Returns

matplotlib.contour.ContourSet

obs_labels(attribute='label', horizontalalignment='center', filter_by=None, *args, **kwargs)

Add observation point labels to the plot. Corresponds to Obs. Labels in FEFLOW.

Parameters

  • attribute (str) – “label”, “x”, “y”, “node” or “h” (modelled head)

  • args – arguments for plt.annotate

  • kwargs – arguments for plt.annotate

Returns

obs_markers(color='lightgreen', filter_by=None, *args, **kwargs)

Add observation point markers to the plot. Corresponds to Obs. Markers in FEFLOW.

Parameters

  • args – arguments for plt.scatter

  • kwargs – arguments for plt.scatter

Returns

patches(layer=1, alpha=0.5, cmap='feflow_rainbow', *args, **kwargs)

Add plot of the given elemental model property to the plot. Corresponds to the patches style in FEFLOW (for elemental property). Note: Avoid usage when creating vector graphics (svg).

Parameters

  • slice (int) – specified the slice to be plotted in a 3D model.

  • args – see matplotlib.org/api/_as_gen/matplotlib.axes.Axes.tripcolor.html

  • kwargs – matplotlib.org/api/_as_gen/matplotlib.axes.Axes.tripcolor.html

doc.c.plot.gdf - Plot Output

class ifm_contrib.contrib_lib.plot_geopandas.PlotGpd(doc)

Functions for exporting plotted data like isocontours as GeoDataFrame. Results are similar to the output of the View Components Panel of the FEFLOW GUI.

fringes(attribute_name=None, suppress_output=True, *args, **kwargs)

Create fringes polygons of a given nodal parameter, expression or distribution. Return the plot as a polygonal GeoDataFrame.

Returns

geopandas.GeoDataFrame

isolines(attribute_name=None, suppress_output=True, *args, **kwargs)

Create isolines of a given nodal parameter, expression or distribution. Return the plot as a LineString geometry-type GeoDataFrame.

Parameters

  • par (ifm.Enum) – Type of parameter to evaluate. Parameter are provided as ifm.Enum.

  • distr (str) – Name of user distribution to evaluate.

  • expr (str) – Name of user expression to evaluate.

  • slice – if provided in a 3D model, create isolines on this slice.

  • global_cos (bool) – If True, use global coordinate system (default: local)

Returns

geopandas.GeoDataFrame

History Charts and Time Series

doc.c.hist.df - History Charts

class ifm_contrib.contrib_lib.hist_pandas.HistPd(doc)

Functions to obtain data of FEFLOWs chart panels as pandas.DataFrames

all_hist_items()
getDataframe(hist_type=None, hist_subtype=0, force_time_axis=False, reference_time=None)
history(hist_type=None, hist_subtype=0, force_time_axis=False, reference_time=None, sync_to_index=None)

Returns the values of any history charting window as a dataframe. Calling the function without arguments returns a dictionary of all available histories

Parameters

  • hist_type (str, int, ifm.Enum or None.) – History Type.

  • hist_subtype (int) – History Sub-Type (int)

  • force_time_axis (bool) – If True, the index of the dataframe will be the simulation time in days. If False (default), the index type will be of type datetime if a reference time is set in the model, and simulation time in days otherwise.

  • reference_time (datetime.datetime) – Specify (or override) a reference time. Note that this only accounts for this export and is not a permanent change of the model settings.

doc.c.ts - Time Series

class ifm_contrib.contrib_lib.ts.Ts(doc)

Functions regarding time series (aka power functions)

clear(tsid)

Clear all data points in time series.

Parameters

tsid (int) – ID of time series to be cleared

Returns

exists(tsid)

Test if time series (formerly power function) exists.

Parameters

tsid (int or convertible to int) – time series ID

Returns

info()

Returns information on existing time series (formerly power functions) as a list of tuples: [(Time Series ID, Comment, Number of Points, cyclic, interpolation kind)]

points(tsid)

Returns the values of a given time series as a list of (time, value) tuples.

Parameters

tsid (int or convertible to int) – time series ID

Returns

list of tuples

doc.c.ts - Time Series (Pandas)

class ifm_contrib.contrib_lib.ts_pandas.TsPd(doc)

Functions regarding time series (aka power functions)

create_from_series(tsid, series, comment=None, cyclic=False, interpolation=2, warn_on_overwrite=True, error_on_overwrite=False)

Create a FEFLOW time series from a pandas.Series.

Parameters

  • tsid – time series id

  • series – pd.Series. index will be

  • comment – comment to be set

  • cyclic – True of cyclic (default: False)

  • interpolation – Interpolation kind (default: ifm.Enum.INTERPOL_LINEAR)

  • warn_on_overwrite – warn if ts id is occupied (default: True)

  • error_on_overwrite – raise error if ts id is occupied (default: False)

Returns

info()

Returns a pandas.DataFrame with information on existing time series (formerly power functions).

points(tsid=None, force_time_axis=False, reference_time=None)

Returns the values of a given time series (formerly power function) as a dataframe. Time Series can be identified by id or comment (will raise Warning if comment is not unique). Returns a DataFrame with multiple timeseries if tsid is provided as a list (will have nan-values if indices do not match).

Parameters

  • tsid (int, or str, or [int or str]) – time series ID or list of time series IDs, or None (default, return all)

  • force_time_axis (bool) – If True, the index of the dataframe will be the simulation time in days. If False (default), the index type will be of type datetime if a reference time is set in the model, and simulation time in days otherwise.

  • reference_time (datetime.datetime) – Specify (or override) a reference time. Note that this only accounts for this export and is not a permanent change of the model settings.

Returns

time series as a pandas.DataFrame

Return type

pandas.DataFrame

Observation Points

doc.c.obs.gdf - Observations (Geopandas)

class ifm_contrib.contrib_lib.obs_geopandas.ObsGpd(doc)

Functions to obtain data of Observation Points as geoPandas.GeoDataFrames.

obspoints(global_cos=True, filter_by=None)

Get the observation points as a GeoPandas GeoDataFrame.

Parameters

  • global_cos (Bool) – If True, use global coordinate system (default)

  • filter_by (dict {str : list}) – dictionary {str : list} defining a filter. Return only observation points whose attributes defined by the key of the dictionary is member of a list provided as the value.

Returns

GeoDataFrame

Return type

geopandas.GeoDataFrame

[sphinx:ifm_contrib.contrib_lib.rst]