ogstools.meshseries package#

class ogstools.meshseries.MeshSeries[source]#

Bases: Sequence[UnstructuredGrid]

A wrapper around pyvista and meshio for reading of pvd and xdmf timeseries.

Initialize a MeshSeries object

param filepath:

Path to the PVD or XDMF file.

param spatial_unit:

Unit/s of the mesh points. See note.

param time_unit:

Unit/s of the timevalues. See note.

returns:

A MeshSeries object

Note:: If given as a single string, the data is read in SI units i.e. in seconds and meters and converted to the given units. If given as a tuple, the first str corresponds to the data_unit, the second to the output_unit. E.g.: ot.MeshSeries(filepath, "km", ("a", "d")) would read in the spatial data in meters and convert to kilometers and read in the timevalues in years and convert to days.

__init__(filepath=None, spatial_unit='m', time_unit='s')[source]#

Initialize a MeshSeries object

param filepath:

Path to the PVD or XDMF file.

param spatial_unit:

Unit/s of the mesh points. See note.

param time_unit:

Unit/s of the timevalues. See note.

returns:

A MeshSeries object

Note:: If given as a single string, the data is read in SI units i.e. in seconds and meters and converted to the given units. If given as a tuple, the first str corresponds to the data_unit, the second to the output_unit. E.g.: ot.MeshSeries(filepath, "km", ("a", "d")) would read in the spatial data in meters and convert to kilometers and read in the timevalues in years and convert to days.

classmethod from_data(meshes, timevalues, spatial_unit='m', time_unit='s')[source]#

Create a MeshSeries from a list of meshes and timevalues.

Return type:: MeshSeries

extend(mesh_series)[source]#

Extends self with mesh_series. If the last element of the mesh series is within epsilon to the first element of mesh_series to extend, the duplicate element is removed

resample_temporal(timevalues)[source]#

Return a new MeshSeries interpolated to the given timevalues.

Return type:: MeshSeries

probe(points, data_name=None, interp_method='linear')[source]#

Create a new MeshSeries by probing points on an existing MeshSeries.

Parameters:

points (ndarray) – The points at which to probe.
data_name (str | Variable | list[str | Variable] | None) – Data to extract. If None, use all point data.
interp_method (Literal['nearest', 'linear']) – The interpolation method to use.

Returns:

A MeshSeries (Pointcloud) containing the probed data.

Return type:

MeshSeries

interpolate(mesh, data_name=None)[source]#

Create a new MeshSeries by spatial interpolation.

Parameters:

mesh (DataSet) – The mesh on which to interpolate.
data_name (str | Variable | list[str | Variable] | None) – Data to extract. If None, use all point data.

Returns:

A spatially interpolated MeshSeries.

Return type:

MeshSeries

copy(deep=True)[source]#

Create a copy of MeshSeries object. Deep copy is the default.

Parameters:: deep (bool) – switch to choose between deep (default) and shallow (self.copy(deep=False)) copy.
Returns:: Copy of self.
Return type:: MeshSeries

__getitem__(index: int) → UnstructuredGrid[source]#
__getitem__(index: slice | Sequence) → MeshSeries
__getitem__(index: str) → ndarray

items()[source]#

Returns zipped tuples of timevalues and meshes.

Return type:: Sequence[tuple[float, UnstructuredGrid]]

aggregate_temporal(variable, func)[source]#

Aggregate data over all timesteps using a specified function.

Parameters:

variable (Variable | str) – The mesh variable to be aggregated.
func (Callable) – The aggregation function to apply. E.g. np.min, np.max, np.mean, np.median, np.sum, np.std, np.var

Returns:

A mesh with aggregated data according to the given function.

Return type:

UnstructuredGrid

clear_cache()[source]#

closest_timestep(timevalue)[source]#

Return the corresponding timestep from a timevalue.

Return type:: int

closest_timevalue(timevalue)[source]#

Return the closest timevalue to a timevalue.

Return type:: float

ip_tesselated()[source]#

Create a new MeshSeries from integration point tessellation.

Return type:: MeshSeries

mesh(timestep, lazy_eval=True)[source]#

Returns the mesh at the given timestep.

Return type:: UnstructuredGrid

rawdata_file()[source]#

Checks, if working with the raw data is possible. For example, OGS Simulation results with XDMF support efficient raw data access via h5py

Returns:: The location of the file containing the raw data. If it does not support efficient read (e.g., no efficient slicing), it returns None.
Return type:: Path | None

mesh_interp(timevalue, lazy_eval=True)[source]#

Return the temporal interpolated mesh for a given timevalue.

Return type:: UnstructuredGrid

property timevalues: ndarray#: Return the timevalues.

property timesteps: list#: Return the OGS simulation timesteps of the timeseries data. Not to be confused with timevalues which returns a list of times usually given in time units.

values(variable: str | Variable) → ndarray[source]#

values(variable: list[str | Variable]) → list[ndarray]

Get the data in the MeshSeries for all timesteps.

Adheres to time slicing via __getitem__ and an applied pyvista filter via transform if the applied filter produced ‘vtkOriginalPointIds’ or ‘vtkOriginalCellIds’ (e.g. clip(…, crinkle=True), extract_cells(…), threshold(…).)

Parameters:: variable – Data to read/process from the MeshSeries. Can also be a list of str or Variable.
Returns:: A numpy array of shape (n_timesteps, n_points/c_cells). If given an argument of type Variable is given, its transform function is applied on the data. If a list of str or Variable is given, a list of the individual values is returned.

property point_data: DataDict#: Useful for reading or setting point_data for the entire meshseries.

property cell_data: DataDict#: Useful for reading or setting cell_data for the entire meshseries.

property field_data: DataDict#: Useful for reading or setting field_data for the entire meshseries.

time_of_min(variable)[source]#

Returns a Mesh with the time of the variable minimum as data.

Return type:: UnstructuredGrid

time_of_max(variable)[source]#

Returns a Mesh with the time of the variable maximum as data.

Return type:: UnstructuredGrid

aggregate_spatial(variable, func)[source]#

Aggregate data over domain per timestep using a specified function.

Parameters:

variable (Variable | str) – The mesh variable to be aggregated.
func (Callable) – The aggregation function to apply. E.g. np.min, np.max, np.mean, np.median, np.sum, np.std, np.var

Returns:

A numpy array with aggregated data.

Return type:

ndarray

probe_values(points, data_name, interp_method='linear')[source]#

Return the sampled data of the MeshSeries at observation points.

Similar to probe() but returns the data directly instead of creating a new MeshSeries.

Parameters:

points (ndarray | list) – The observation points to sample at.
data_name (str | Variable | list[str | Variable]) – Data to sample. If provided as a Variable, the output will transformed accordingly. Can also be a list of str or Variable.
interp_method (Literal['nearest', 'linear']) – Interpolation method, defaults to linear

Returns:

numpy array/s of interpolated data at observation points with the following shape:

multiple points: (n_timesteps, n_points, [n_components])
single points: (n_timesteps, [n_components])

If data_name is a list, a corresponding list of arrays is returned.

Return type:

ndarray | list[ndarray]

plot_line(var1=None, var2=None, ax=None, sort=True, outer_legend=False, **kwargs)#

Plot some data of a (1D) dataset.

You can pass “x”, “y” or “z” to either of x_var or y_var to specify which spatial dimension should be used for the corresponding axis. By passing “time” the timevalues will be use for this axis. You can also pass two data variables for a phase plot. if no value is given, automatic detection of spatial axis is tried.

>>> line(ms, ot.variables.temperature)          # temperature over time
>>> line(ms, ot.variables.temperature, "time")  # time over temperature
>>> line(ms, "pressure", "temperature")     # temperature over pressure
>>> line(mesh, ot.variables.temperature)    # temperature over x, y or z
>>> line(mesh, "y", "temperature")          # temperature over y
>>> line(mesh, ot.variables.pressure, "y")  # y over pressure
>>> line(mesh)  # z=const: y over x, y=const: z over x, x=const: z over y

Parameters:

var1 (str | Variable | None) – Variable for the x-axis if var2 is given else for y-axis.
var2 (str | Variable | None) – Variable for the y-axis if var1 is given.
ax (Axes | None) – The matplotlib axis to use for plotting, if None a new figure will be created.
sort (bool) – Automatically sort the values along the dimension of the mesh with the largest extent (only for pointclouds).

Outer_legend:

Draw legend to the right next to the plot area. By default False (legend stays inside). User can pass a tuple of two floats (x, y), which will be passed to bbox_to_anchor parameter in matplotlib legend call. True will pass the default values (1.05, 1.0).

Return type:

Figure | None

Keyword Arguments:

figsize: figure size (default=[16, 10])
dpi: resolution of the figure
color: color of the line
linewidth: width of the line
linestyle: style of the line
label: label in the legend
grid: if True, show grid
monospace: if True, the legend uses a monospace font
loc: location of the legend (default=”upper right”)
clip_on: If True, clip the output to stay within the Axes.
(default=False)
all other kwargs get passed to matplotlib’s plot function

Note:

Using loc=”best” will take a long time, if you plot lines on top of a contourplot, as matplotlib is calculating the best position against all the underlying cells.

plot_time_slice(x, y, variable, time_logscale=False, fig=None, ax=None, cbar=True, **kwargs)[source]#

Create a heatmap for a variable over time and space.

Parameters:

x (Literal['x', 'y', 'z', 'time']) – What to display on the x-axis (x, y, z or time)
y (Literal['x', 'y', 'z', 'time']) – What to display on the y-axis (x, y, z or time)
variable (str | Variable) – The variable to be visualized.
time_logscale (bool) – Should log-scaling be applied to the time-axis?
fig (Figure | None) – matplotlib figure to use for plotting.
ax (Axes | None) – matplotlib axis to use for plotting.
cbar (bool) – If True, adds a colorbar.

Return type:

Figure | None

Keyword Arguments:

cb_labelsize: colorbar labelsize
cb_loc: colorbar location (‘left’ or ‘right’)
cb_pad: colorbar padding
cmap: colormap
vmin: minimum value for colorbar
vmax: maximum value for colorbar
num_levels: number of levels for colorbar
figsize: figure size
dpi: resolution
log_scaled: logarithmic scaling

property mesh_func: Callable[[UnstructuredGrid], UnstructuredGrid]#: Returns stored transformation function or identity if not given.

transform(mesh_func=lambda mesh: ...)[source]#

Apply a transformation function to the underlying mesh.

Parameters:: mesh_func (Callable[[UnstructuredGrid], UnstructuredGrid]) – A function which expects to read a mesh and return a mesh. Useful for slicing / clipping / thresholding.
Returns:: A deep copy of this MeshSeries with transformed meshes.
Return type:: MeshSeries

scale(spatial=1.0, time=1.0)[source]#

Scale the spatial coordinates and timevalues.

Useful to convert to other units, e.g. “m” to “km” or “s” to “a”. Converts from SI units (i.e. ‘m’ and ‘s’) to the given arguments. Does not create a copy, but modifies the calling object. If you want to have a scaled version without changing the original do

ms_scaled = ms.copy().scale(…)

Parameters:

spatial (int | float | str) – Float factor or str for target unit.
time (int | float | str) – Float factor or str for target unit.

Returns:

The scaled MeshSeries.

Return type:

MeshSeries

classmethod difference(ms_a, ms_b, variable=None)[source]#

Compute difference of variables between the two MeshSeries instances from which this method is called and a second MeshSeries instance passed as method parameter. Returns new instance of MeshSeries: ms = ms_a - ms_b

Parameters:

ms_a (MeshSeries) – The mesh from which data is to be subtracted.
ms_b (MeshSeries) – The mesh whose data is to be subtracted.
variable (Variable | str | None) – The variable of interest. If not given, all point and cell_data will be processed raw.

Returns:

MeshSeries containing the difference of variable` or of all datasets between both MeshSeries.

Return type:

MeshSeries

static compare(ms_a, ms_b, variable=None, point_data=True, cell_data=True, field_data=True, atol=0.0, *, strict=False)[source]#

Method to compare two ot.MeshSeries objects.

Returns True if they match within the tolerances, otherwise False.

Parameters:

ms_a (MeshSeries) – The reference base MeshSeries for comparison.
ms_b (MeshSeries) – The MeshSeries to compare against the reference.
variable (Variable | str | None) – The variable of interest. If not given, all point and cell data will be processed.
point_data (bool) – Compare all point data if variable is None. Default is True.
cell_data (bool) – Compare all cell data if variable is None. Default is True.
field_data (bool) – Compare all field data if variable is None. Default is True.
atol (float) – Absolute tolerance. Default is 0.0.
strict (bool) – Raises an AssertionError, if mismatch. Default is False.

Return type:

bool

extract(index, preference='points')[source]#

Extract a subset of the domain by point or cell indices.

Parameters:

index (slice | int | ndarray | list) – Indices of points or cells to extract.
preference (Literal['points', 'cells']) – Selected entities.

Returns:

A MeshSeries with the selected domain subset.

Return type:

MeshSeries

save(filename, deep=True, ascii=False)[source]#

Save mesh series to disk.

Parameters:

filename (str) – Filename to save the series to. Extension specifies the file type. Currently only PVD is supported.
deep (bool) – Specifies whether VTU/H5 files should be written.
ascii (bool) – Specifies if ascii or binary format should be used, defaults to binary (False) - True for ascii.

remove_array(name, data_type='field', skip_last=False)[source]#

Removes an array from all time slices of the mesh series.

Parameters:

name (str) – Array name
data_type (str) – Data type of the array. Could be either field, cell or point
skip_last (bool) – Skips the last time slice (e.g. for restart purposes).

ogstools.meshseries package#

Submodules#