# sfepy.discrete.evaluate module

class sfepy.discrete.evaluate.Evaluator(problem, matrix_hook=None, assemble=None)

  This class provides the functions required by a nonlinear solver for a given problem.

  eval_residual(vec, is_full=False, select_term=None)
  eval_tangent_matrix(vec, mtx=None, is_full=False, select_term=None)
  make_full_vec(vec)
  static new_ulf_iteration(problem, nls, vec, it, err, err0)

sfepy.discrete.evaluate.apply_ebc_to_matrix(mtx, ebc_rows, epbc_rows=None)

  Apply E(P)BC to matrix rows: put 1 to the diagonal for EBC DOFs, 1 to the diagonal for master EPBC DOFs, -1 to the [master, slave] entries. It is assumed, that the matrix contains zeros in EBC and master EPBC DOFs rows and columns.

  When used within a nonlinear solver, the actual values on the EBC DOFs diagonal positions do not matter, as the residual is zero at those positions.

sfepy.discrete.evaluate.assemble_by_blocks(conf_equations, problem, ebcs=None, epbcs=None, dw_mode='matrix', active_only=True)

  Instead of a global matrix, return its building blocks as defined in conf_equations. The name and row/column variables of each block have to be encoded in the equation’s name, as in:

      conf_equations = {
        'A,v,u' : "dw_lin_elastic.i1.Y2( inclusion.D, v, u )",
      }

  Notes

  ebcs, epbcs must be either lists of BC names, or BC configuration dictionaries.

sfepy.discrete.evaluate.create_evaluable(expression, fields, materials, variables, integrals, regions=None, ebcs=None, epbcs=None, lcbcs=None, ts=None, functions=None, auto_init=False, mode='eval', extra_args=None, active_only=True, eterm_options=None, verbose=True, kwargs=None)

  Create evaluable object (equations and corresponding variables) from the expression string.

  Parameters:
    expression str

      The expression to evaluate.

    fields dict

      The dictionary of fields used in variables.

    materials Materials instance

      The materials used in the expression.

    variables Variables instance

      The variables used in the expression.

    integrals Integrals instance

      The integrals to be used.

    regions Region instance or list of Region instances

      The region(s) to be used. If not given, the regions defined within the fields domain are used.

    ebcs Conditions instance, optional

      The essential (Dirichlet) boundary conditions for ‘weak’ mode.

    epbcs Conditions instance, optional

      The periodic boundary conditions for ‘weak’ mode.

    lcbcs Conditions instance, optional

      The linear combination boundary conditions for ‘weak’ mode.

    ts TimeStepper instance, optional

      The time stepper.

    functions Functions instance, optional

      The user functions for boundary conditions, materials etc.

    auto_init bool

      Set values of all variables to all zeros.

    mode one of ‘eval’, ‘el_avg’, ‘qp’, ‘weak’

      The evaluation mode - ‘weak’ means the finite element assembling, ‘qp’ requests the values in quadrature points, ‘el_avg’ element averages and ‘eval’ means integration over each term region.

    extra_args dict, optional

      Extra arguments to be passed to terms in the expression.

    active_only bool

      If True, in ‘weak’ mode, the (tangent) matrices and residual vectors (right-hand sides) contain only active DOFs.

    eterm_options dict, optional

      The einsum-based terms evaluation options.

    verbose bool

      If False, reduce verbosity.

    kwargs dict, optional

      The variables (dictionary of (variable name) : (Variable instance)) to be used in the expression.

  Returns:
    equation Equation instance

      The equation that is ready to be evaluated.

    variables Variables instance

      The variables used in the equation.

sfepy.discrete.evaluate.eval_equations(equations, variables, names=None, preserve_caches=False, mode='eval', dw_mode='vector', term_mode=None, active_only=True, any_dof_conn=False, verbose=True)

  Evaluate the equations.

  Parameters:
    equations Equations instance

      The equations returned by `create_evaluable()`.

    variables Variables instance

      The variables returned by `create_evaluable()`.

    names str or sequence of str, optional

      Evaluate only equations of the given name(s).

    preserve_caches bool

      If True, do not invalidate evaluate caches of variables.

    mode one of ‘eval’, ‘el_avg’, ‘qp’, ‘weak’

      The evaluation mode - ‘weak’ means the finite element assembling, ‘qp’ requests the values in quadrature points, ‘el_avg’ element averages and ‘eval’ means integration over each term region.

    dw_mode‘vector’ or ‘matrix’

      The assembling mode for ‘weak’ evaluation mode.

    term_mode str

      The term call mode - some terms support different call modes and depending on the call mode different values are returned.

    active_only bool

      If True, in ‘weak’ mode, the (tangent) matrices and residual vectors (right-hand sides) contain only active DOFs.

    any_dof_conn bool

      If True, in ‘weak’ mode and ‘matrix’ dw_mode, all DOF connectivities are used to pre-allocate the matrix graph. If False, only cell region connectivities are used.

    verbose bool

      If False, reduce verbosity.

  Returns:
    out dict or result

      The evaluation result. In ‘weak’ mode it is the vector or sparse matrix, depending on dw_mode. Otherwise, it is a dict of results with equation names as keys or a single result for a single equation.

sfepy.discrete.evaluate.eval_in_els_and_qp(expression, iels, coors, fields, materials, variables, functions=None, mode='eval', term_mode=None, extra_args=None, active_only=True, verbose=True, kwargs=None)

  Evaluate an expression in given elements and points.

  Parameters:
    expression str

      The expression to evaluate.

    fields dict

      The dictionary of fields used in variables.

    materials Materials instance

      The materials used in the expression.

    variables Variables instance

      The variables used in the expression.

    functions Functions instance, optional

      The user functions for materials etc.

    mode one of ‘eval’, ‘el_avg’, ‘qp’

      The evaluation mode - ‘qp’ requests the values in quadrature points, ‘el_avg’ element averages and ‘eval’ means integration over each term region.

    term_mode str

      The term call mode - some terms support different call modes and depending on the call mode different values are returned.

    extra_args dict, optional

      Extra arguments to be passed to terms in the expression.

    active_only bool

      If True, in ‘weak’ mode, the (tangent) matrices and residual vectors (right-hand sides) contain only active DOFs.

    verbose bool

      If False, reduce verbosity.

    kwargs dict, optional

      The variables (dictionary of (variable name) : (Variable instance)) to be used in the expression.

  Returns:
    out array

      The result of the evaluation.