# sfepy.discrete.dg.fields module

Fields for Discontinous Galerkin method

class sfepy.discrete.dg.fields.DGField(name, dtype, shape, region, space='H1', poly_space_basis='legendre', approx_order=1, integral=None)

  Discontinuous Galerkin method approximation with Legendre basis.

  Class for usage with DG terms, provides functionality for Discontinous Galerkin method like neighbour look up, projection to discontinuous basis and correct DOF treatment.

  clear_facet_neighbour_idx_cache(region=None)

    If region is None clear all!

    Parameters:
      region sfepy.discrete.common.region.Region

        If None clear all.

  clear_facet_qp_basis()

    Clears facet_qp_basis cache

  clear_facet_vols_cache(region=None)

    Clears facet volume cache for given region or all regions.

    Parameters:
      region sfepy.discrete.common.region.Region

        region to clear cache or None to clear all

  clear_normals_cache(region=None)

    Clears normals cache for given region or all regions.

    Parameters:
      region sfepy.discrete.common.region.Region

        region to clear cache or None to clear all

  create_mapping(region, integral, integration, return_mapping=True)

    Creates and returns mapping

    Parameters:
      region sfepy.discrete.common.region.Region
      integral Integral
      integration str

        ‘volume’ is only accepted option

      return_mapping default True

        (Default value = True)

    Returns:
      mapping FEMapping
  create_output(dofs, var_name, dof_names=None, key=None, extend=True, fill_value=None, linearization=None)

    Converts the DOFs corresponding to the field to a dictionary of output data usable by Mesh.write().

    For 1D puts DOFs into vairables u_modal{0} … u_modal{n}, where n = approx_order and marks them for writing as cell data.

    For 2+D puts dofs into name_cell_nodes and creates sturct with: mode = “cell_nodes”, data and iterpolation scheme.

    Also get node values and adds them to dictionary as cell_nodes

    Parameters:
      dofs ndarray, shape (n_nod, n_component)

        The array of DOFs reshaped so that each column corresponds to one component.

      var_name str

        The variable name corresponding to dofs.

      dof_names tuple of str

        The names of DOF components. (Default value = None)

      key str, optional

        The key to be used in the output dictionary instead of the variable name. (Default value = None)

      extend bool, not used

        Extend the DOF values to cover the whole domain. (Default value = True)

      fill_value float or complex, not used

        The value used to fill the missing DOF values if extend is True. (Default value = None)

      linearization Struct or None, not used

        The linearization configuration for higher order approximations. (Default value = None)

    Returns:
      out dict
  family_name = 'volume_DG_legendre_discontinuous'
  get_bc_facet_idx(region)

    Caches results in self.boundary_facet_local_idx

    Parameters:
      region sfepy.discrete.common.region.Region

        surface region defining BCs

    Returns:
      bc2bfi ndarray

        index of cells on boundary along with corresponding facets

  get_bc_facet_values(fun, region, ret_coors=False, diff=0)

    Returns values of fun in facet QPs of the region

    Parameters:
      diff: derivative 0 or 1 supported
      fun: Function value or values to set qps values to
      region sfepy.discrete.common.region.Region

        boundary region

      ret_coors: default False,

        Return physical coors of qps in shape (n_cell, n_qp, dim).

    Returns:
      vals ndarray

        In shape (n_cell,) + (self.dim,) * diff + (n_qp,)

  get_both_facet_basis_vals(state, region, derivative=None)

    Returns values of the basis function in quadrature points on facets broadcasted to all cells inner to the element as well as outer ones along with weights for the qps broadcasted and transformed to elements.

    Contains quick fix to flip facet QPs for right integration order.

    Parameters:
      state used to get EPBC info
      region sfepy.discrete.common.region.Region for connectivity
      derivative if u need derivative

        (Default value = None)

    Returns:
      outer_facet_basis_vals:
      inner_facet_basis_vals:
        shape (n_cell, n_el_nod, n_el_facet, n_qp) or

          (n_cell, n_el_nod, n_el_facet, dim, n_qp)

        when derivative is True or 1

      whs: shape (n_cell, n_el_facet, n_qp)
  get_both_facet_state_vals(state, region, derivative=None, reduce_nod=True)

    Computes values of the variable represented by dofs in quadrature points located at facets, returns both values - inner and outer, along with weights.

    Parameters:
      state state variable containing BC info
      region sfepy.discrete.common.region.Region
      derivative compute derivative if truthy,

        compute n-th derivative if a number (Default value = None)

      reduce_nod if False DOES NOT sum nodes into values at QPs

        (Default value = True)

    Returns:
      inner_facet_values (n_cell, n_el_facets, n_qp),

        outer facet values (n_cell, n_el_facets, n_qp), weights, if derivative is True:

        > inner_facet_values (n_cell, n_el_facets, dim, n_qp), outer_facet values (n_cell, n_el_facets, dim, n_qp)

  get_cell_normals_per_facet(region)

    Caches results, use clear_normals_cache to clear the cache.

    Parameters:
      region: sfepy.discrete.common.region.Region

        Main region, must contain cells.

    Returns:
      normals: ndarray

        normals of facets in array of shape (n_cell, n_el_facets, dim)

  get_coor(nods=None)

    Returns coors for matching nodes # TODO revise DG_EPBC and EPBC matching?

    Parameters:
      nods

        if None use all nodes (Default value = None)

    Returns:
      coors ndarray

        coors on surface

  get_data_shape(integral, integration='cell', region_name=None)

    Returns data shape (n_nod, n_qp, self.gel.dim, self.n_el_nod)

    Parameters:
      integral integral used
      integration

        ‘volume’ is only supported value (Default value = ‘volume’)

      region_name not used

        (Default value = None)

    Returns:
      data_shape tuple
  get_dofs_in_region(region, merge=True)

    Return indices of DOFs that belong to the given region.

    Not Used in BC treatment

    Parameters:
      region sfepy.discrete.common.region.Region
      merge bool

        merge dof tuple into one numpy array, default True

    Returns:
      dofs ndarray
  get_econn(conn_type, region, trace_region=None)

    Getter for econn

    Parameters:
      conn_type tuple or string

        (‘cell’, dim) or ‘cell’ is only supported

      region sfepy.discrete.common.region.Region
      trace_region ignored

        (Default value = None)

    Returns:
      econn ndarray

        connectivity information

  get_facet_basis(derivative=False, basis_only=False)

    Returns values of basis in facets quadrature points, data shape is a bit crazy right now:

    > (number of qps, 1, n_el_facets, 1, n_el_nod)

    end for derivatine:

      (1, number of qps, (dim,) * derivative, n_el_facets, 1, n_el_nod)

    Parameters:
      derivative: truthy or integer
      basis_only: do not return weights
    Returns:
      facet_bf ndarray

        values of basis functions in facet qps

      weights ndarray, optionally

        weights of qps

  get_facet_neighbor_idx(region=None, eq_map=None)

    Returns index of cell neighbours sharing facet, along with local index of the facet within neighbour, also treats periodic boundary conditions i.e. plugs correct neighbours for cell on periodic boundary. Where there are no neighbours specified puts -1 instead of neighbour and facet id

    Cashes neighbour index in self.facet_neighbours

    Parameters:
      region sfepy.discrete.common.region.Region

        Main region, must contain cells.

      eq_map

        eq_map from state variable containing information on EPBC and DG EPBC. (Default value = None)

    Returns:
      facet_neighbours ndarray
        Shape is

          (n_cell, n_el_facet, 2),

        first value is index of the neighbouring cell, the second is index of the facet in said nb. cell.

  get_facet_qp()

    Returns quadrature points on all facets of the reference element in array of shape (n_qp, 1 , n_el_facets, dim)

    Returns:
      qps ndarray

        quadrature points

      weights ndarray

        Still needs to be transformed to actual facets!

  get_facet_vols(region)

    Caches results, use clear_facet_vols_cache to clear the cache

    Parameters:
      region sfepy.discrete.common.region.Region
    Returns:
      vols_out: ndarray

        volumes of the facets by cells shape (n_cell, n_el_facets, 1)

  get_nodal_values(dofs, region, ref_nodes=None)

    Computes nodal representation of the DOFs

    ## Parameters

    dofsarray_like

      dofs to transform to nodes

    region : ignored

    ref_nodes:

      reference node to use instead of default qps

    Parameters:
      dofs array_like
      region Region
      ref_nodes array_like

        (Default value = None)

    Returns:
      nodes ndarray
      nodal_vals ndarray
  static get_region_info(region)

    Extracts information about region needed in various methods of DGField

    Parameters:
      region sfepy.discrete.common.region.Region
    Returns:
      dim, n_cell, n_el_facets
  is_surface = False
  set_cell_dofs(fun=0.0, region=None, dpn=None, warn=None)

    Compute projection of fun onto the basis, in main region, alternatively set DOFs directly to provided value or values

    Parameters:
      fun callable, scallar or array corresponding to dofs

        (Default value = 0.0)

      region sfepy.discrete.common.region.Region

        region to set DOFs on (Default value = None)

      dpn number of dofs per element

        (Default value = None)

      warn not used

        (Default value = None)

    Returns:
      nods ndarray
      vals ndarray
  set_dofs(fun=0.0, region=None, dpn=None, warn=None)

    Compute projection of fun into the basis, alternatively set DOFs directly to provided value or values either in main volume region or in boundary region.

    Parameters:
      fun callable, scalar or array corresponding to dofs

        (Default value = 0.0)

      region sfepy.discrete.common.region.Region

        region to set DOFs on (Default value = None)

      dpn number of dofs per element

        (Default value = None)

      warn

        (Default value = None)

    Returns:
      nods ndarray
      vals ndarray
  set_facet_dofs(fun, region, dpn, warn)

    Compute projection of fun onto the basis on facets, alternatively set DOFs directly to provided value or values

    Parameters:
      fun callable, scalar or array corresponding to dofs
      region sfepy.discrete.common.region.Region

        region to set DOFs on

      dpn int

        number of dofs per element

      warn

        not used

    Returns:
      nods ndarray
      vals ndarray
  setup_extra_data(info)
    This is called in create_adof_conns(conn_info, var_indx=None,

      active_only=True, verbose=True)

    for each variable but has no effect.

    Parameters:
      info

        set to self.info

sfepy.discrete.dg.fields.get_gel(region)
  Parameters:
    region sfepy.discrete.common.region.Region
  Returns:
    gel

      base geometry element of the region

sfepy.discrete.dg.fields.get_raveler(n_el_nod, n_cell)

  Returns function for raveling i.e. packing dof data from two dimensional array of shape (n_cell, n_el_nod, 1) to (n_el_nod*n_cell, 1)

  The raveler returns view into the input array.

  Parameters:
    n_el_nod

      param n_el_nod, n_cell: expected dimensions of dofs array

    n_cell int
  Returns:
    ravel callable

sfepy.discrete.dg.fields.get_unraveler(n_el_nod, n_cell)

  Returns function for unraveling i.e. unpacking dof data from serialized array from shape (n_el_nod*n_cell, 1) to (n_cell, n_el_nod, 1).

  The unraveler returns non-writeable view into the input array.

  Parameters:
    n_el_nod int

      expected dimensions of dofs array

    n_cell int
  Returns:
    unravel callable