seisflows.solver.specfem3d
==========================

.. py:module:: seisflows.solver.specfem3d

.. autoapi-nested-parse::

   This class provides utilities for the Seisflows solver interactions with
   Specfem3D Cartesian.



Classes
-------

.. autoapisummary::

   seisflows.solver.specfem3d.Specfem3D


Module Contents
---------------

.. py:class:: Specfem3D(source_prefix='CMTSOLUTION', export_vtk=True, prune_scratch=True, **kwargs)

   Bases: :py:obj:`seisflows.solver.specfem.Specfem`


   Solver SPECFEM3D
   ----------------
   SPECFEM3D-specific alterations to the base SPECFEM module

   Parameters
   ----------
   :type source_prefix: str
   :param source_prefix: Prefix of source files in path SPECFEM_DATA. Must be
       in ['CMTSOLUTION', 'FORCESOLUTION']. Defaults to 'CMTSOLUTION'
   :type export_vtk: bool
   :param export_vtk: at the finalization step of each iteration, convert
       all eligible model and gradient directories in the `path_output`
       to .vtk files for visualization using ParaView (or similar programs). 
       Files are exported to `path_output`/VTK
   :type prune_scratch: bool
   :param prune_scratch: prune/remove database files as soon as they are used,
       to keep overall filesystem burden down
       - removes *.vt? files after they're generated by a forward simulation
       - removes proc*_absorb_field.bin and proc*_save_forward_array.bin
           files after adjoint simulations

   Paths
   -----
   ***


   .. py:attribute:: __doc__


   .. py:attribute:: prune_scratch
      :value: True



   .. py:attribute:: export_vtk
      :value: True



   .. py:attribute:: _export_vtk
      :value: True



   .. py:attribute:: _available_materials
      :value: ['ACOUSTIC', 'ELASTIC', 'TRANSVERSE_ISOTROPIC', 'ANISOTROPIC']



   .. py:attribute:: _acceptable_source_prefixes
      :value: ['CMTSOLUTION', 'FORCESOLUTION']



   .. py:attribute:: _required_binaries
      :value: ['xspecfem3D', 'xmeshfem3D', 'xgenerate_databases', 'xcombine_sem', 'xcombine_vol_data_vtk']



   .. py:attribute:: _fwd_simulation_executables
      :value: ['bin/xmeshfem3D', 'bin/xgenerate_databases', 'bin/xspecfem3D']



   .. py:attribute:: _adj_simulation_executables
      :value: ['bin/xspecfem3D']



   .. py:attribute:: _absorb_wildcard
      :value: 'proc??????_absorb_field*'



   .. py:attribute:: _forward_array_wildcard
      :value: 'proc??????_save_forward_arrays*'



   .. py:attribute:: _model_databases
      :value: None



   .. py:method:: check()

      SPECFEM3D_Cartesian specific check tasks



   .. py:method:: setup()

      Generate .vtk files for the initial and target (if applicable) models,
      which the User can use for external visualization



   .. py:method:: data_wildcard(comp='?')

      Returns a wildcard identifier for synthetic data

      TODO where does SU put its component?

      :rtype: str
      :return: wildcard identifier for channels



   .. py:property:: model_databases

      The location of databases for model outputs, usually
      OUTPUT_FILES/DATABASES_MPI. This can be determined by 'LOCAL_PATH'
      in your Par_file



   .. py:property:: kernel_databases

      The location of databases for kernel outputs, usually the same as
      'model_databases'



   .. py:method:: forward_simulation(**kwargs)

      Calls SPECFEM3D forward solver, exports solver outputs to traces dir

      See `solver.specfem.forward_simulation` for info on required parameters



   .. py:method:: adjoint_simulation(**kwargs)

      Calls SPECFEM3D adjoint solver, creates the `SEM` folder with adjoint
      traces which is required by the adjoint solver

      See `solver.specfem.adjoint_simulation` for info on required parameters

      :type executables: list or None
      :param executables: list of SPECFEM executables to run, in order, to
          complete an adjoint simulation. This can be left None in most cases,
          which will select default values based on the specific solver
          being called (2D/3D/3D_GLOBE). It is made an optional parameter
          to keep the function more general for inheritance purposes.



   .. py:method:: combine_vol_data_vtk(input_path, output_path, hi_res=False, parameters=None)

      Wrapper for 'xcombine_vol_data_vtk'. Combines binary files together
      to generate a single .VTK file that can be visualized by external
      software like ParaView

      .. rubric::
          xcombine_data start end quantity input_dir output_dir hi/lo-res

      .. note::
          It is ASSUMED that this function is being called by
          system.run(single=True) so that we can use the main solver
          directory to perform the kernel summation task

      :type input_path: str
      :param input_path: path to database files to be summed.
      :type output_path: strs
      :param output_path: path to export the outputs of the binary
      :type hi_res: bool
      :param hi_res: Set the high resolution flag to 1 or True, which will
          generate .vtk files with data at EACH GLL point, rather than at each
          nodal vertex. These files are LARGE, and we discourage using
          `hi_res`==True unless you know you want these files.
      :type parameters: list
      :param parameters: optional list of parameters,
          defaults to `self._parameters`