PyGEOSX Tools

The pygeosx_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

pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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)
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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)
pygeosx_tools.file_io.load_tables(axes_names: Iterable[str], property_names: Iterable[str], table_root: str = './tables', extension: str = 'csv') → Tuple[Iterable[numpy.ndarray], Dict[str, numpy.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
pygeosx_tools.file_io.save_tables(axes: Iterable[numpy.ndarray], properties: Dict[str, numpy.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)
pygeosx_tools.mesh_interpolation.apply_to_bins(fn: Callable[[Union[float, numpy.ndarray]], float], position: numpy.ndarray, value: numpy.ndarray, bins: numpy.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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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
pygeosx_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