ogs5py.tools.tools

Tools for the ogs5py package.

Classes

Output(file_or_name[, print_log]) A class to duplicate an output stream to stdout.

Geometric tools

rotate_points(points, angle[, …]) Rotate points around a given rotation point and axis with a given angle.
shift_points(points, vector) Shift points with a given vector.
transform_points(points, xyz_func, \*\*kwargs) Transform points with a given function “xyz_func”.
hull_deform(x_in, y_in, z_in[, niv_top, …]) Providing a transformation function to deform a given mesh.
rotation_matrix(vector, angle) Create a rotation matrix.
volume(typ, \*pnt) Volume of a OGS5 Meshelement.
centroid(typ, \*pnt) Centroid of a OGS5 Meshelement.

Array tools

unique_rows(data[, decimals, fast]) Unique made row-data with respect to given precision.
replace(arr, inval, outval) Replace values of ‘arr’.
by_id(array[, ids]) Return a flattend array side-by-side with the array-element ids.
specialrange(val_min, val_max, steps[, typ]) Calculation of special point ranges.
generate_time(time_array[, time_start, …]) Return a dictionary for the “.tim” file.

class Output(file_or_name, print_log=True)[source]

Bases: object

A class to duplicate an output stream to stdout.

Parameters:
  • file_or_name (filename or open filehandle (writable)) – File that will be duplicated
  • print_log (bool, optional) – State if log should be printed. Default: True

Methods

close(self) Close the file and restore the channel.
flush(self) Flush both channels.
write(self, data) Write data to both channels.
close(self)[source]

Close the file and restore the channel.

flush(self)[source]

Flush both channels.

write(self, data)[source]

Write data to both channels.

by_id(array, ids=None)[source]

Return a flattend array side-by-side with the array-element ids.

Parameters:
  • array (array-like) – Input data. will be flattened.
  • ids (None or array-like) – You can provide specific ids if needed. As default, the array-ids are used. Default: None
Returns:

Return type:

zipped (id, array) object

centroid(typ, *pnt)[source]

Centroid of a OGS5 Meshelement.

Parameters:
  • typ (string) –

    OGS5 Meshelement type. Should be one of the following:

    • ”line” : 1D element with 2 nodes
    • ”tri” : 2D element with 3 nodes
    • ”quad” : 2D element with 4 nodes
    • ”tet” : 3D element with 4 nodes
    • ”pyra” : 3D element with 5 nodes
    • ”pris” : 3D element with 6 nodes
    • ”hex” : 3D element with 8 nodes
  • *pnt (Node Choordinates pnt = (x_0, x_1, ...)) – List of points defining the Meshelement. A point is given as an (x,y,z) tuple and for each point, there can be a stack of points, if the volume should be calculated for multiple elements of the same type.
Returns:

centroid – Array containing the Centroids of the give elements.

Return type:

ndarray

Notes

The calculation is performed by geometric decomposition of the elements.

https://en.wikipedia.org/wiki/Centroid#By_geometric_decomposition

find_key_in_list(key, key_list)[source]

Look for the right corresponding key in a list.

key has to start with an given key from the list and the longest key will be returned.

Parameters:
  • key (str) – Given key.
  • key_list (list of str) – Valid keys to be checked against.
Returns:

found_key – The best match. None if nothing was found.

Return type:

str or None

format_content(content)[source]

Format the content to be added to a 2D linewise array.

Parameters:content (anything) – Single object, or list of objects, or list of lists of objects.
format_content_line(content)[source]

Format a line of content to be a list of values.

Parameters:content (anything) – Single object, or list of objects
format_dict(dict_in)[source]

Format the dictionary to use upper-case keys.

Parameters:dict_in (dict) – input dictionary
generate_time(time_array, time_start=0, factors=1, is_diff=False)[source]

Return a dictionary for the “.tim” file.

Parameters:
  • time_array (array-like) – Input time. will be flattened. Either time step sizes for each step, (is_diff=True) or an array of time-points.
  • time_start (float, optional) – Starting point for time stepping. Default: 0
  • factors (int or array-like, optional) – Repeating factors for each time step. Default: 1
  • is_diff (bool, optional) – State if the given time array contains only the step size for each step. Default: False
Returns:

dict – keys: {“TIME_START”, “TIME_END”, “TIME_STEPS”}

Return type:

input dict for “.tim”.

get_key(sline)[source]

Get the key of a splitted line if there is any, else return “”.

Parameters:sline (list of str) – given splitted line
guess_type(string)[source]

Guess the type of a value given as string and return it accordingly.

Parameters:string (str) – given string containing the value
hull_deform(x_in, y_in, z_in, niv_top=10.0, niv_bot=0.0, func_top=None, func_bot=None, direction='z')[source]

Providing a transformation function to deform a given mesh.

Transformation is in a given direction by a self defined hull-functions z = func(x, y). Could be used with transform_mesh and transform_points.

Parameters:
  • x_in (ndarray) – Array of the x-positions
  • y_in (ndarray) – Array of the y-positions
  • z_in (ndarray) – Array of the z-positions
  • niv_top (float) – height of the top niveau to be deformed by func_top
  • niv_bot (float) – height of the bottom niveau to be deformed by func_bot
  • func_top (function or float) – function deforming the top niveau: z_top = func_top(x, y)
  • func_bot (function or float) – function deforming the bottom niveau: z_bot = func_bot(x, y)
  • direction (string, optional) – defining the direction of deforming. This direction will be used as z-value. Default: “z”
Returns:

x_out, y_out, z_out – transformed arrays

Return type:

ndarray

is_key(sline)[source]

Check if the given splitted line is an OGS key.

Parameters:sline (list of str) – given splitted line
is_mkey(sline)[source]

Check if the given splitted line is a main key.

Parameters:sline (list of str) – given splitted line
is_skey(sline)[source]

Check if the given splitted line is a sub key.

Parameters:sline (list of str) – given splitted line
is_str_array(array)[source]

A routine to check if an array contains strings.

Parameters:array (iterable) – array to check
Returns:
Return type:bool
replace(arr, inval, outval)[source]

Replace values of ‘arr’.

Replace values defined in ‘inval’ with values defined in ‘outval’.

Parameters:
  • arr (ndarray) – array containing the input data
  • inval (ndarray) – values appearing in ‘arr’ that should be replaced
  • outval (ndarray) – values that should be written in ‘arr’ instead of values in ‘inval’
Returns:

result – array of the same shape as ‘arr’ containing the new data

Return type:

ndarray

rotate_points(points, angle, rotation_axis=(0.0, 0.0, 1.0), rotation_point=(0.0, 0.0, 0.0))[source]

Rotate points around a given rotation point and axis with a given angle.

Parameters:
  • points (ndarray) – Array with all points postions.
  • angle (float) – rotation angle given in radial length
  • rotation_axis (array_like, optional) – Array containing the vector for ratation axis. Default: (0,0,1)
  • rotation_point (array_like, optional) – Array containing the vector for ratation base point. Default: (0,0,0)
Returns:

new_array – rotated array

Return type:

ndarray

rotation_matrix(vector, angle)[source]

Create a rotation matrix.

For rotation around a given vector with a given angle.

Parameters:
  • vector (ndarray) – array containing the vector for ratation axis
  • angle (float) – rotation angle given in radial length
Returns:

result – matrix to be used for matrix multiplication with vectors to be rotated.

Return type:

ndarray

search_mkey(fin)[source]

Search for the first main keyword in a given file-stream.

Parameters:fin (stream) – given opened file
search_task_id(task_root, search_ext=None)[source]

Search for OGS model names in the given path.

Parameters:
  • task_root (str) – Path to the destiny folder.
  • search_ext (str) – OGS extension that should be searched for. Default: All known.
Returns:

found_ids – List of all found task_ids.

Return type:

list of str

shift_points(points, vector)[source]

Shift points with a given vector.

Parameters:
  • points (ndarray) – Array with all points postions.
  • vector (ndarray) – array containing the shifting vector
Returns:

new_array – shifted array

Return type:

ndarray

specialrange(val_min, val_max, steps, typ='exp')[source]

Calculation of special point ranges.

Parameters:
  • val_min (float) – Starting value.
  • val_max (float) – Ending value
  • steps (int) – Number of steps.
  • typ (str or float, optional) –

    Setting the kind of range-distribution. One can choose between

    • "exp": for exponential behavior
    • "log": for logarithmic behavior
    • "geo": for geometric behavior
    • "lin": for linear behavior
    • "quad": for quadratic behavior
    • "cub": for cubic behavior
    • float: here you can specifi any exponent (“quad” would be equivalent to 2)

    Default: "exp"

Returns:

Array containing the special range

Return type:

numpy.ndarray

Examples

>>> specialrange(1,10,4)
array([ 1.        ,  2.53034834,  5.23167968, 10.        ])
split_file_path(path, abs_path=False)[source]

Decompose a path to a file.

Decompose into the dir-path, the basename and the file-extension.

Parameters:
  • path (string) – string containing the path to a file
  • abs_path (bool, optional) – convert the path to an absolut path. Default: False
Returns:

result – tuple containing the dir-path, basename and file-extension

Return type:

tuple of strings

transform_points(points, xyz_func, **kwargs)[source]

Transform points with a given function “xyz_func”.

kwargs will be forwarded to “xyz_func”.

Parameters:
  • points (ndarray) – Array with all points postions.
  • xyz_func (function) – the function transforming the points x_new, y_new, z_new = f(x_old, y_old, z_old, **kwargs)
Returns:

new_array – transformed array

Return type:

ndarray

uncomment(line)[source]

Remove OGS comments from a given line of an OGS file.

Comments are indicated by “;”. The line is then splitted by whitespaces.

Parameters:line (str) – given line
unique_rows(data, decimals=4, fast=True)[source]

Unique made row-data with respect to given precision.

this is constructed to work best if point-pairs appear. The output is sorted like the input data. data needs to be 2D

Parameters:
  • data (ndarray) – 2D array containing the list of vectors that should be made unique
  • decimals (int, optional) – Number of decimal places to round the ‘data’ to (default: 3). If decimals is negative, it specifies the number of positions to the left of the decimal point. This will not round the output, it is just for comparison of the vectors.
  • fast (bool, optional) – If fast is True, the vector comparison is executed by a decimal comparison. If fast is False, all pairwise distances are calculated. Default: True
Returns:

  • result (ndarray) – 2D array of unique rows of data
  • ix (ndarray) – index positions of output in input data (data[ix] = result) len(ix) = result.shape[0]
  • ixr (ndarray) – reversed index positions of input in output data (result[ixr] = data) len(ixr) = data.shape[0]

Notes

This routine will preserve the order within the given array as effectively as possible. If you use it with a stack of 2 arrays and the first one is already unique, the resulting array will still have the first array at the beginning.

unique_rows_old(data, decimals=4)[source]

Returns unique made data with respect to given precision in “decimals”.

The output is sorted like the input data. data needs to be 2D

Parameters:
  • data (ndarray) – 2D array containing the list of vectors that should be made unique
  • decimals (int, optional) – Number of decimal places to round the ‘data’ to (default: 3). If decimals is negative, it specifies the number of positions to the left of the decimal point. This will not round the output, it is just for comparison of the vectors.
Returns:

  • result (ndarray) – 2D array of unique rows of data
  • ix (ndarray) – index positions of output in input data (data[ix] = result) len(ix) = result.shape[0]
  • ixr (ndarray) – reversed index positions of input in output data (result[ixr] = data) len(ixr) = data.shape[0]

Notes

This routine will preserve the order within the given array as effectively as possible. If you use it with a stack of 2 arrays and the first one is already unique, the resulting array will still have the first array at the beginning.

volume(typ, *pnt)[source]

Volume of a OGS5 Meshelement.

Parameters:
  • typ (string) –

    OGS5 Meshelement type. Should be one of the following:

    • ”line” : 1D element with 2 nodes
    • ”tri” : 2D element with 3 nodes
    • ”quad” : 2D element with 4 nodes
    • ”tet” : 3D element with 4 nodes
    • ”pyra” : 3D element with 5 nodes
    • ”pris” : 3D element with 6 nodes
    • ”hex” : 3D element with 8 nodes
  • *pnt (Node Choordinates pnt = (x_0, x_1, ...)) – List of points defining the Meshelement. A point is given as an (x,y,z) tuple and for each point, there can be a stack of points, if the volume should be calculated for multiple elements of the same type.
Returns:

Volume – Array containing the volumes of the give elements.

Return type:

ndarray