# sfepy.terms.terms module

class sfepy.terms.terms.ConnInfo(**kwargs)
  get_region(can_trace=True)
  get_region_name(can_trace=True)

class sfepy.terms.terms.Term(name, arg_str, integral, region, **kwargs)
  advance(ts)

    Advance to the next time step. Implemented in subclasses.

  arg_geometry_types = {}
  arg_shapes = {}
  arg_types = ()
  assemble_to(asm_obj, val, iels, mode='vector', diff_var=None)

    Assemble the results of term evaluation.

    For standard terms, assemble the values in val corresponding to elements/cells iels into a vector or a CSR sparse array asm_obj, depending on mode.

    For terms with a dynamic connectivity (e.g. contact terms), in ‘matrix’ mode, return the extra COO sparse array instead. The extra matrix has to be added to the global matrix by the caller. By default, this is done in `Equations.evaluate()`.

  assign_args(variables, materials, user=None)

    Check term argument existence in variables, materials, user data and assign the arguments to terms. Also check compatibility of field and term regions.

  call_function(out, fargs)
  call_get_fargs(args, kwargs)
  check_args()

    Common checking to all terms.

    Check compatibility of field and term regions.

  check_shapes(*args, **kwargs)

    Check term argument shapes at run-time.

  classify_args()

    Classify types of the term arguments and find matching call signature.

    A state variable can be in place of a parameter variable and vice versa.

  diff_info = {}
  eval_complex(shape, fargs, mode='eval', term_mode=None, diff_var=None, **kwargs)
  eval_real(shape, fargs, mode='eval', term_mode=None, diff_var=None, **kwargs)
  evaluate(mode='eval', diff_var=None, standalone=True, ret_status=False, **kwargs)

    Evaluate the term.

    Parameters:
      mode‘eval’ (default), or ‘weak’

        The term evaluation mode.

    Returns:
      val float or array

        In ‘eval’ mode, the term returns a single value (the integral, it does not need to be a scalar), while in ‘weak’ mode it returns an array for each element.

      status int, optional

        The flag indicating evaluation success (0) or failure (nonzero). Only provided if ret_status is True.

      iels array of ints, optional

        The local elements indices in ‘weak’ mode. Only provided in non-‘eval’ modes.

  static from_desc(constructor, desc, region, integrals=None)
  geometries = ['1_2', '2_3', '2_4', '3_4', '3_8']
  get(variable, quantity_name, bf=None, integration=None, step=None, time_derivative=None)

    Get the named quantity related to the variable.

    Notes

    This is a convenience wrapper of Variable.evaluate() that initializes the arguments using the term data.

  get_arg_name(arg_type, full=False, join=None)

    Get the name of the argument specified by arg_type.

    Parameters:
      arg_type str

        The argument type string.

      full bool

        If True, return the full name. For example, if the name of a variable argument is ‘u’ and its time derivative is requested, the full name is ‘du/dt’.

      join str, optional

        Optionally, the material argument name tuple can be joined to a single string using the join string.

    Returns:
      name str

        The argument name.

  get_args(arg_types=None, **kwargs)

    Return arguments by type as specified in arg_types (or self.ats). Arguments in **kwargs can override the ones assigned at the term construction - this is useful for passing user data.

  get_args_by_name(arg_names)

    Return arguments by name.

  get_assembling_cells(shape=None)

    Return the assembling cell indices into a DOF connectivity.

  get_conn_info()
  get_conn_key()

    The key to be used in DOF connectivity information.

  get_data_shape(variable)

    Get data shape information from variable.

    Notes

    This is a convenience wrapper of FieldVariable.get_data_shape() that initializes the arguments using the term data.

  get_dof_conn_type(var_name)
  get_kwargs(keys, **kwargs)

    Extract arguments from **kwargs listed in keys (default is None).

  get_mapping(variable, get_saved=False, return_key=False)

    Get the reference mapping from a variable.

    Notes

    This is a convenience wrapper of Field.get_mapping() that initializes the arguments using the term data.

  get_material_names(part=0)
  get_materials(join=False)
  get_parameter_names()
  get_parameter_variables()
  get_physical_qps()

    Get physical quadrature points corresponding to the term region and integral.

  get_qp_key()

    Return a key identifying uniquely the term quadrature points.

  get_region()
  get_state_names()

    If variables are given, return only true unknowns whose data are of the current time step (0).

  get_state_variables(unknown_only=False)
  get_str()
  get_user_names()
  get_variable_names()
  get_variables(as_list=True)
  get_vector(variable)

    Get the vector stored in variable according to self.arg_steps and self.arg_derivatives. Supports only the backward difference w.r.t. time.

  get_virtual_name()
  get_virtual_variable()
  integration = 'cell'
  integration_order = None
  name = ''
  static new(name_args, integral, region, **kwargs)

    Create a new Term instance.

    Parameters:
      name_args str

        The term name and arguments, e.g. ‘dw_laplace(m.coef, v, u)’.

      integral Integral instance

        The integral defining the term quadrature.

      region Region instance

        The term region (domain of integration for most terms).

      **kwargs keyword arguments, optional

        The actual term arguments. Their compatibility with name_args is checked when a term is added to an Equation instance, or when evaluated.

  set_arg_types()
  set_integral(integral)

    Set the term integral.

  setup(allow_derivatives=False)
  setup_args(**kwargs)
  setup_formal_args(allow_derivatives=False)
  setup_geometry_types()
  setup_integration()
  standalone_setup()
  static tile_mat(mat, nel)
  time_update(ts)
  static translate_fargs_mapping(function, fargs, force=False)

class sfepy.terms.terms.Terms(objs=None)
  append(obj)
  assign_args(variables, materials, user=None)

    Assign all term arguments.

  static from_desc(term_descs, regions, integrals=None)

    Create terms, assign each term its region.

  get_material_names()
  get_user_names()
  get_variable_names()
  insert(ii, obj)
  setup(**kwargs)
  update_expression()

sfepy.terms.terms.create_arg_parser(allow_derivatives=False)

sfepy.terms.terms.get_arg_kinds(arg_types)

  Translate arg_types of a Term to a canonical form.

  Parameters:
    arg_types tuple of strings

      The term argument types, as given in the arg_types attribute.

  Returns:
    arg_kinds list of strings

      The argument kinds - one of ‘virtual_variable’, ‘state_variable’, ‘parameter_variable’, ‘opt_material’, ‘ts’, ‘user’.

sfepy.terms.terms.get_shape_kind(integration)

  Get data shape kind for given integration type.

sfepy.terms.terms.split_complex_args(args)

  Split complex arguments to real and imaginary parts.

  Returns:
    newargs dictionary

      Dictionary with lists corresponding to args such that each argument of numpy.complex128 data type is split to its real and imaginary part. The output depends on the number of complex arguments in ‘args’:

      > - 0: list (key ‘r’) identical to input one

      > - 1: two lists with keys ‘r’, ‘i’ corresponding to real and imaginary parts

      > - 2: output dictionary contains four lists:

      >   - ‘r’ - real(arg1), real(arg2)

      >   - ‘i’ - imag(arg1), imag(arg2)

      >   - ‘ri’ - real(arg1), imag(arg2)

      >   - ‘ir’ - imag(arg1), real(arg2)