PyGEOS Tools

The pygeos-tools python package adds a variety of tools for working with pygeosx objects. These include common operations such as setting the value of geosx wrappers with python functions, parallel communication, and file IO. Examples using these tools can be found here: PYGEOSX Examples .

API

geos.pygeos_tools.wrapper.allgather_wrapper(problem, key, ghost_key='')

Get a global copy of a wrapper as a numpy ndarray on all ranks

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

Returns:

The wrapper as a numpy ndarray

Return type:

np.ndarray

geos.pygeos_tools.wrapper.gather_wrapper(problem, key, ghost_key='')

Get a global copy of a wrapper as a numpy ndarray on rank 0

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

Returns:

The wrapper as a numpy ndarray

Return type:

np.ndarray

geos.pygeos_tools.wrapper.get_global_value_range(problem, key)

Get the range of a target value across all processes

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

Returns:

The global min/max of the target

Return type:

tuple

geos.pygeos_tools.wrapper.get_matching_wrapper_path(problem, filters)

Recursively search the group and its children for wrappers that match the filters A successful match is identified if the wrapper path contains all of the strings in the filter. For example, if filters=[‘a’, ‘b’, ‘c’], the following could match any of the following: ‘a/b/c’, ‘c/b/a’, ‘d/e/c/f/b/a/a’

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • filters (list) – a list of strings

Returns:

Key of the matching wrapper

Return type:

str

geos.pygeos_tools.wrapper.get_wrapper(problem, target_key, write_flag=False)

Get a local copy of a wrapper as a numpy ndarray

Parameters:

  • filename (str) – Catalog file name

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

  • write_flag (bool) – Sets write mode (default=False)

Returns:

The wrapper as a numpy ndarray

Return type:

np.ndarray

geos.pygeos_tools.wrapper.get_wrapper_par(problem, target_key, allgather=False, ghost_key='')

Get a global copy of a wrapper as a numpy ndarray. Note: if ghost_key is set, it will try to remove any ghost elements

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

  • allgather (bool) – Flag to trigger allgather across ranks (False)

  • ghost_key (str) – Key for the corresponding ghost wrapper (default=’’)

Returns:

The wrapper as a numpy ndarray

Return type:

np.ndarray

geos.pygeos_tools.wrapper.plot_history(records, output_root='.', save_figures=True, show_figures=True)

Plot the time-histories for the records structure. Note: If figures are shown, the GEOSX process will be blocked until they are closed

Parameters:

  • records (dict) – A dict of dicts containing the queries

  • output_root (str) – Path to save figures (default = ‘./’)

  • save_figures (bool) – Flag to indicate whether figures should be saved (default = True)

  • show_figures (bool) – Flag to indicate whether figures should be drawn (default = False)

geos.pygeos_tools.wrapper.print_global_value_range(problem, key, header, scale=1.0, precision='%1.4f')

Print the range of a target value across all processes

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

  • header (str) – Header to print with the range

  • scale (float) – Multiply the range with this value before printing (default = 1.0)

  • precision (str) – Format for printing the range (default = %1.4f)

Returns:

The global min/max of the target

Return type:

tuple

geos.pygeos_tools.wrapper.run_queries(problem, records)

Query the current GEOSX datastructure Note: The expected record request format is as follows. For now, the only supported query is to find the min/max values of the target record = {‘path/of/wrapper’: {‘label’: ‘aperture (m)’, # A label to include with plots ‘scale’: 1.0, # Value to scale results by ‘history: [], # A list to store values over time ‘fhandle’: plt.figure() # A figure handle }}

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • records (dict) – A dict of dicts that specifies the queries to run

geos.pygeos_tools.wrapper.search_datastructure_wrappers_recursive(group, filters, matching_paths, level=0, group_path=[])

Recursively search the group and its children for wrappers that match the filters

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • filters (list) – a list of strings

  • matching_paths (list) – a list of matching values

geos.pygeos_tools.wrapper.set_wrapper_to_value(problem, key, value)

Set the value of a wrapper

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

  • value (float) – Value to set the wrapper

geos.pygeos_tools.wrapper.set_wrapper_with_function(problem, target_key, input_keys, fn, target_index=-1)

Set the value of a wrapper using a function

Parameters:

  • problem (pygeosx.Group) – GEOSX problem handle

  • target_key (str) – Key for the target wrapper

  • input_keys (str, list) – The input key(s)

  • fn (function) – Vectorized function used to calculate target values

  • target_index (int) – Target index to write the output (default = all)

geos.pygeos_tools.file_io.load_tables(axes_names: Iterable[str], property_names: Iterable[str], table_root: str = './tables', extension: str = 'csv') → Tuple[Iterable[ndarray], Dict[str, ndarray]]

Load a set of tables in GEOSX format

Parameters:

  • axes_names (list) – Axis file names in the target directory (with no extension)

  • property_names (list) – Property file names in the target directory (with not extension)

  • table_root (str) – Root path for the table directory

  • extension (str) – Table file extension (default = ‘csv’)

Returns:

List of axes values, and dictionary of table values

Return type:

tuple

geos.pygeos_tools.file_io.save_tables(axes: Iterable[ndarray], properties: Dict[str, ndarray], table_root: str = './tables', axes_names: List[str] = []) → None

Saves a set of tables in GEOSX format

The shape of these arrays should match the length of each axis in the specified order. The output directory will be created if it does not exist yet. If axes_names are not supplied, then they will be selected based on the dimensionality of the grid: 1D=[t]; 3D=[x, y, z]; 4D=[x, y, z, t].

Parameters:

  • axes (list) – A list of numpy ndarrays defining the table axes

  • properties (dict) – A dict of numpy ndarrays defning the table values

  • table_root (str) – The root path for the output directory

  • axes_names (list) – A list of names for each potential axis (optional)

geos.pygeos_tools.mesh_interpolation.apply_to_bins(fn: Callable[[float | ndarray], float], position: ndarray, value: ndarray, bins: ndarray, collapse_edges: bool = True)

Apply a function to values that are located within a series of bins Note: if a bin is empty, this function will fill a nan value

Parameters:

  • fn (function) – Function that takes a single scalar or array input

  • position (np.ndarray) – A 1D list/array describing the location of each sample

  • value (np.ndarray) – A 1D list/array of values at each location

  • bins (np.ndarray) – The bin edges for the position data

  • collapse_edges (bool) – Controls the behavior of edge-data (default=True)

Returns:

an array of function results for each bin

Return type:

np.ndarray

geos.pygeos_tools.mesh_interpolation.extrapolate_nan_values(x, y, slope_scale=0.0)

Fill in any nan values in two 1D arrays by extrapolating

Parameters:

  • x (np.ndarray) – 1D list/array of positions

  • y (np.ndarray) – 1D list/array of values

  • slope_scale (float) – value to scale the extrapolation slope (default=0.0)

Returns:

The input array with nan values replaced by extrapolated data

Return type:

np.ndarray

geos.pygeos_tools.mesh_interpolation.get_random_realization(x, bins, value, rand_fill=0, rand_scale=0, slope_scale=0)

Get a random realization for a noisy signal with a set of bins

Parameters:

  • x (np.ndarray) – 1D list/array of positions

  • bins (np.ndarray) – 1D list/array of bin edges

  • value (np.ndarray) – 1D list/array of values

  • rand_fill (float) – The standard deviation to use where data is not defined (default=0)

  • rand_scale (float) – Value to scale the standard deviation for the realization (default=0)

  • slope_scale (float) – Value to scale the extrapolation slope (default=0.0)

Returns:

An array containing the random realization

Return type:

np.ndarray

geos.pygeos_tools.mesh_interpolation.get_realizations(x, bins, targets)

Get random realizations for noisy signals on target bins

Parameters:

  • x (np.ndarray) – 1D list/array of positions

  • bins (np.ndarray) – 1D list/array of bin edges

  • targets (dict) – Dict of geosx target keys, inputs to get_random_realization

Returns:

Dictionary of random realizations

Return type:

dict

geos.pygeos_tools.well_log.convert_E_nu_to_K_G(E, nu)

Convert young’s modulus and poisson’s ratio to bulk and shear modulus

Parameters:

  • E (float, np.ndarray) – Young’s modulus

  • nu (float, np.ndarray) – Poisson’s ratio

Returns:

bulk modulus, shear modulus with same size as inputs

Return type:

tuple

geos.pygeos_tools.well_log.estimate_shmin(z, rho, nu)

Estimate the minimum horizontal stress using the poisson’s ratio

Parameters:

  • z (float, np.ndarray) – Depth

  • rho (float, np.ndarray) – Density

  • nu (float, np.ndarray) – Poisson’s ratio

Returns:

minimum horizontal stress

Return type:

float

geos.pygeos_tools.well_log.parse_las(fname, variable_start='~C', body_start='~A')

Parse an las format log file

Parameters:

  • fname (str) – Path to the log file

  • variable_start (str) – A string that indicates the start of variable header information (default = ‘~CURVE INFORMATION’)

  • body_start (str) – a string that indicates the start of the log body (default = ‘~A’)

Returns:

a dict containing the values and unit definitions for each variable in the log

Return type:

np.ndarray