seisflows.tools.model ===================== .. py:module:: seisflows.tools.model .. autoapi-nested-parse:: A Model class for interfacing with SPECFEM velocity models, used to read models into memory, manipulate and write to disk. Also contains plotting functions for SPECFEM2D models Classes ------- .. autoapisummary:: seisflows.tools.model.Model Module Contents --------------- .. py:class:: Model(path=None, fmt='', parameters=None, regions='123', flavor=None) A container for reading, storing and manipulating model/gradient/kernel parameters from SPECFEM2D/3D/3D_GLOBE. .. py:attribute:: acceptable_parameters :value: ['vp', 'vs', 'vpv', 'vph', 'vsv', 'vsh', 'eta', 'rho', 'rhop', 'kappa', 'mu', 'c11', 'c12',... .. py:attribute:: path :value: None .. py:attribute:: fmt :value: '' .. py:attribute:: flavor :value: None .. py:attribute:: model :value: None .. py:attribute:: coordinates :value: None .. py:attribute:: _parameters :value: None .. py:attribute:: _ngll :value: None .. py:attribute:: _nproc :value: None .. py:method:: setup(path=None) Set up the internal Model definition by guessing or ingesting the file format, solver flavor, reading the model values and metadata and assigning internal variables :type path: str :param path: optional path to Model files. If not given, defaults to the internal `path` attribute. :raises AssertionError: if the `path` does not exist or the `path` does not contain expected Model files .. py:method:: fnfmt(i='*', val='*', ext='*') Expected SPECFEM filename format with some checks to ensure that wildcards and numbers are accepted. An example filename is: 'proc000001_vs.bin' :type i: int or str :param i: processor number or wildcard. If given as an integer, will be converted to a 6 digit zero-leading value to match SPECFEM format :type val: str :param val: parameter value (e.g., 'vs') or wildcard :type ext: str :param ext: the file format (e.g., '.bin'). If NOT preceded by a '.' will have one prepended :rtype: str :return: filename formatter for use in model manipulation .. py:property:: parameters Returns a list of parameters which defines the model. .. py:property:: ngll Provide the number of GLL (Gauss Lobatto Legendre) points per processor chunk. Access hidden attribute `_ngll` in the case that the model is very large, we only want to count the GLL points once. :rtype: list of float :return: each float represents the number of GLL points for the chunk number that corresponds to its index .. py:method:: _update_ngll_from_model() Convenience function to count NGLL points as length of data arrays for each parameter processor chunk .. py:property:: nproc Returns the number of processors that define the model/gradient/kernel. :rtype: int :return: number of processors that define the model .. py:property:: vector Conveience property to access the merge() function which creates a linear vector defining all model parameters :rtype: np.array :return: a linear vector of all model parameters .. py:method:: copy() Returns a deep copy of self so that models can be transferred .. py:method:: read(parameters=None) Utility function to load in SPECFEM models/kernels/gradients saved in various formats. Will try to guess format of model. Assumes that models are saved using the following filename format: proc{num}_{val}.{format} where `num` is usually a 6 digit number representing the processor number (e.g., 000000), `val` is the parameter value of the model/kernel/gradient and `format` is the format of the file (e.g., bin) :type parameters: list of str :param parameters: unique parameters to load model for, if None will load all available parameters found in `path` :rtype: Dict of np arrays :return: Dictionary where keys correspond to model parameters and values are vectors (np.arrays) representing the model .. py:method:: read_coordinates_specfem2d() Attempt to read coordinate files from the given model definition. This is only really useful for SPECFEM2D, where we can plot the model, kernel and gradient using matplotlib. .. warning This will NOT work for SPECEFM3D. When you get to 3D, the coordinates don't match up one-to-one with the model values so you need external viewing software (e.g., ParaView) to plot. :rtype: Dict :return: a dictioanary with the X and Z coordinates read in from a SPECFEM2D model, if applicable .. py:method:: merge(parameter=None) Convert dictionary representation `model` to vector representation `m` where all parameters and processors are stored as a single 1D vector. This vector representation is used by the optimization library during model perturbation. :type parameter: str :param parameter: single parameter to retrieve model vector from, otherwise returns all parameters merged into single vector :rtype: np.array :return: vector representation of the model .. py:method:: write(path=None, fmt=None) Save a SPECFEM model/gradient/kernel vector loaded into memory back to disk in the appropriate format expected by SPECFEM .. py:method:: split(vector=None) Converts internal vector representation `m` to dictionary representation `model`. Does this by separating the vector based on how it was constructed, parameter-wise and processor-wise :type vector: np.array :param vector: allow Model to split an input vector. If none given, will split the internal vector representation :rtype: Dict of np.array :return: dictionary of model parameters split up by number of processors .. py:method:: print_stats() Print out all model parameters (min, mean, max) in the logger. Useful for checking if models are different, if a model is being satisfactorily udpated, or for debugging purposes. .. py:method:: check(min_pr=-1.0, max_pr=0.5) Checks parameters in the model. If Vs and Vp present, checks poissons ratio. Checks for negative velocity values. :type min_pr: float :para min_pr: minimum allowable Poisson's ratio, if applicable :type max_pr: float :param max_pr: maximum allowable Poisson's ratio, if applicable :raises AssertionError: - if the input model has no values for any of its parameters - if the model contains any NaN values .. py:method:: _check_2d3d_parameters(min_pr=-1.0, max_pr=0.5) Checks parameters for SPECFEM2D and SPECFEM3D derived models .. py:method:: _check_3dglobe_parameters(min_pr=-1.0, max_pr=0.5) Checks parameters for SPECFEM3D_GLOBE derived models .. py:method:: update(model=None, vector=None) Update internal model/vector defitions. Because these two quantities are tied to one another, updating one will update the other. This function simply makes that easier. .. py:method:: plot2d(parameter, vmin=None, vmax=None, cmap=None, levels=None, center_cmap=False, title='', show=True, save=None) Plot internal model parameters as a 2D image plot. .. warning:: This is only available for SPECFEM2D models. SPECFEM3D model coordinates do not match the model vectors (because the grids are irregular) and cannot be visualized like this. :type parameter: str :param parameter: chosen internal parameter value to plot. :type cmap: str :param cmap: colormap which match available matplotlib colormap. If None, will choose default colormap based on parameter choice. :type show: bool :param show: show the figure after plotting :type title: str :param title: optional title to prepend to some values that are provided by default. Useful for adding information about iteration, step count etc. :type save: str :param save: if not None, full path to figure to save the output image .. py:method:: _get_nproc_parameters() Get the number of processors and the available parameters from a list of output SPECFEM model files. :rtype: tuple (int, list) :return: (number of processors, list of available parameters in dir) .. py:method:: _guess_file_format() Guess the file format of model/kernel/gradient files if none provided by the user. Does so by checking file formats against formats expected from SPECFEM2D/3D/3D_GLOBE :rtype: str :return: file format suffix with a leading '.' e.g., '.bin' .. py:method:: _guess_specfem_flavor() Guess if SPECFEM2D/3D/3D_GLOBE was used to generate the model based on the format of the file. Check based on unique available files or properties :rtype: str :return: SPECFEM flavor, one of ['2D', '3D', '3DGLOBE'] .. py:method:: _read_model_fortran_binary(parameter) Load Fortran binary models into disk. This is the preferred model format for SeisFlows <-> SPECFEM interaction :type parameter: str :param parameter: chosen parameter to load model for :rtype: np.array :return: vector of model values for given `parameter` .. py:method:: _read_model_adios(parameter) :abstractmethod: Load ADIOS models into disk :type parameter: str :param parameter: chosen parameter to load model for :rtype: np.array :return: vector of model values for given `parameter` .. py:method:: _read_model_ascii(parameter) Load ASCII SPECFEM2D models into disk. ASCII models are generally saved all in a single file with all parameters together as a N column ASCII file where columns 1 and 2 are the coordinates of the mesh, and the remainder columns are data corresponding to the filenames e.g., proc000000_rho_vp_vs.dat, rho is column 3, vp is 4 etc. :type parameter: str :param parameter: chosen parameter to load model for :rtype: np.array :return: vector of model values for given `parameter` .. py:method:: _write_model_fortran_binary(path) Save a SPECFEM model back to Fortran binary format. Data are written as single precision floating point numbers .. note:: FORTRAN unformatted binaries are bounded by an INT*4 byte count. This function mimics that behavior by tacking on the boundary data as 'int32' at the top and bottom of the data array. https://docs.oracle.com/cd/E19957-01/805-4939/6j4m0vnc4/index.html