# sfepy.discrete.common.fields module

class sfepy.discrete.common.fields.Field(**kwargs)

  Base class for fields.

  clear_mappings(clear_all=False)

    Clear current reference mappings.

  create_eval_mesh()

    Create a mesh for evaluating the field. The default implementation returns None, because this mesh is for most fields the same as the one created by Field.create_mesh().

  evaluate_at(coors, source_vals, mode='val', strategy='general', close_limit=0.1, get_cells_fun=None, cache=None, ret_cells=False, ret_status=False, ret_ref_coors=False, verbose=False)

    Evaluate source DOF values corresponding to the field in the given coordinates using the field interpolation.

    Parameters:
      coors array, shape `(n_coor, dim)`

        The coordinates the source values should be interpolated into.

      source_vals array, shape `(n_nod, n_components)`

        The source DOF values corresponding to the field.

      mode{‘val’, ‘grad’, ‘div’, ‘cauchy_strain’}, optional

        The evaluation mode: the field value (default), the field value gradient, divergence, or cauchy strain.

      strategy{‘general’, ‘convex’}, optional

        The strategy for finding the elements that contain the coordinates. For convex meshes, the ‘convex’ strategy might be faster than the ‘general’ one.

      close_limit float, optional

        The maximum limit distance of a point from the closest element allowed for extrapolation.

      get_cells_fun callable, optional

        If given, a function with signature `get_cells_fun(coors, cmesh, **kwargs)` returning cells and offsets that potentially contain points with the coordinates coors. Applicable only when strategy is ‘general’. When not given, `get_potential_cells()` is used.

      cache Struct, optional

        To speed up a sequence of evaluations, the field mesh and other data can be cached. Optionally, the cache can also contain the reference element coordinates as cache.ref_coors, cache.cells and cache.status, if the evaluation occurs in the same coordinates repeatedly. In that case the mesh related data are ignored. See `Field.get_evaluate_cache()`.

      ret_ref_coors bool, optional

        If True, return also the found reference element coordinates.

      ret_status bool, optional

        If True, return also the enclosing cell status for each point.

      ret_cells bool, optional

        If True, return also the cell indices the coordinates are in.

      verbose bool

        If False, reduce verbosity.

    Returns:
      vals array

        The interpolated values with shape `(n_coor, n_components, 1)` or gradients with shape `(n_coor, n_components, dim)` according to the mode. If ret_status is False, the values where the status is greater than one are set to `numpy.nan`.

      ref_coors array

        The found reference element coordinates, if ret_ref_coors is True.

      cells array

        The cell indices, if ret_ref_coors or ret_cells or ret_status are True.

      status array

        The status, if ret_ref_coors or ret_status are True, with the following meaning: 0 is success, 1 is extrapolation within close_limit, 2 is extrapolation outside close_limit, 3 is failure, 4 is failure due to non-convergence of the Newton iteration in tensor product cells. If close_limit is 0, then for the ‘general’ strategy the status 5 indicates points outside of the field domain that had no potential cells.

  static from_args(name, dtype, shape, region, approx_order=1, space='H1', poly_space_basis='lagrange')

    Create a Field subclass instance corresponding to a given space.

    Parameters:
      name str

        The field name.

      dtype numpy.dtype

        The field data type: float64 or complex128.

      shape int/tuple/str

        The field shape: 1 or (1,) or ‘scalar’, space dimension (2, or (2,) or 3 or (3,)) or ‘vector’, or a tuple. The field shape determines the shape of the FE base functions and is related to the number of components of variables and to the DOF per node count, depending on the field kind.

      region Region

        The region where the field is defined.

      approx_order int/str

        The FE approximation order, e.g. 0, 1, 2, ‘1B’ (1 with bubble).

      space str

        The function space name.

      poly_space_basis str

        The name of polynomial space base.

    Notes

    Assumes one cell type for the whole region!

  static from_conf(conf, regions)

    Create a Field subclass instance based on the configuration.

  get_mapping(region, integral, integration, get_saved=False, return_key=False)

    For given region, integral and integration type, get a reference mapping, i.e. jacobians, element volumes and base function derivatives for Volume-type geometries, and jacobians, normals and base function derivatives for Surface-type geometries corresponding to the field approximation.

    The mappings are cached in the field instance in mappings attribute. The mappings can be saved to mappings0 using Field.save_mappings. The saved mapping can be retrieved by passing get_saved=True. If the required (saved) mapping is not in cache, a new one is created.

    Returns:
      geo PyCMapping instance

        The reference mapping.

      mapping FEMapping or IGMapping instance

        The mapping.

      key tuple

        The key of the mapping in mappings or mappings0.

  save_mappings()

    Save current reference mappings to mappings0 attribute.

  set_dofs(fun=0.0, region=None, dpn=None, warn=None)

    Set the values of DOFs in a given region using a function of space coordinates or value fun.

    If fun is a function, the l2 projection that is global for all region facets is used to set the DOFs.

    If dpn > 1, and fun is a function, it has to return the values point-by-point, i.e. all components in the first point, in the second point etc., concatenated to an array that is reshapable to the shape (n_point, dpn).

    Parameters:
      fun float or array of length dpn or callable

        The DOF values.

      region Region

        The region containing the DOFs.

      dpn int, optional

        The DOF-per-node count. If not given, the number of field components is used.

      warn str, optional

        The warning message printed when the region selects no DOFs.

    Returns:
      nods array, shape (n_dof,)

        The field DOFs (or node indices) given by the region.

      vals array, shape (n_dof, dpn)

        The values of the DOFs, node-by-node when raveled in C (row-major) order.

    Notes

    The nodal basis fields (lagrange) reimplement this function to set DOFs directly.

    The hierarchical basis field (lobatto) do not support surface mappings, so also reimplement this function.

sfepy.discrete.common.fields.fields_from_conf(conf, regions)

sfepy.discrete.common.fields.parse_approx_order(approx_order)

  Parse the uniform approximation order value (str or int).

sfepy.discrete.common.fields.parse_shape(shape, dim)

sfepy.discrete.common.fields.setup_extra_data(conn_info)

  Setup extra data required for non-volume integration.