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[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
- pygeosx_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)
- pygeosx_tools.mesh_interpolation.apply_to_bins(fn: Callable[[Union[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
- 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