# sfepy.discrete.problem module

class sfepy.discrete.problem.Problem(name, conf=None, functions=None, domain=None, fields=None, equations=None, auto_conf=True, active_only=True)

  Problem definition, the top-level class holding all data necessary to solve a problem.

  It can be constructed from a `ProblemConf` instance using Problem.from_conf() or directly from a problem description file using Problem.from_conf_file()

  For interactive use, the constructor requires only the equations, nls and ls keyword arguments, see below.

  Parameters:
    name str

      The problem name.

    conf ProblemConf instance, optional

      The `ProblemConf` describing the problem.

    functions Functions instance, optional

      The user functions for boundary conditions, materials, etc.

    domain Domain instance, optional

      The solution `Domain`.

    fields dict, optional

      The dictionary of `Field` instances.

    equations Equations instance, optional

      The `Equations` to solve. This argument is required when auto_conf is True.

    auto_conf bool

      If True, fields and domain are determined by equations.

    active_only bool

      If True, the (tangent) matrices and residual vectors (right-hand sides) contain only active DOFs, see below.

  Notes

  The Problem is by default created with active_only set to True. Then the (tangent) matrices and residual vectors (right-hand sides) have reduced sizes and contain only the active DOFs, i.e., DOFs not constrained by EBCs or EPBCs.

  Setting active_only to False results in full-size vectors and matrices. Then the matrix size non-zeros structure does not depend on the actual E(P)BCs applied. It must be False when using parallel PETSc solvers.

  The active DOF connectivities contain all DOFs, with the E(P)BC-constrained ones stored as -1 - <DOF number>, so that the full connectivities can be reconstructed for the matrix graph creation. However, the negative entries mean that the assembled matrices/residuals have zero values at positions corresponding to constrained DOFs.

  The resulting linear system then provides a solution increment, that has to be added to the initial guess used to compute the residual, just like in the Newton iterations. The increment of the constrained DOFs is automatically zero.

  When solving with a direct solver, the diagonal entries of a matrix at positions corresponding to constrained DOFs has to be set to ones, so that the matrix is not singular, see `sfepy.discrete.evaluate.apply_ebc_to_matrix()`, which is called automatically in `sfepy.discrete.evaluate.Evaluator.eval_tangent_matrix()`. It is not called automatically in `Problem.evaluate()`. Note that setting the diagonal entries to one might not be necessary with iterative solvers, as the zero matrix rows match the zero residual rows, i.e. if the reduced matrix would be regular, then the right-hand side (the residual) is orthogonal to the kernel of the matrix.

  advance(ts=None)
  block_solve(state0=None, status=None, save_results=True, step_hook=None, post_process_hook=None, report_nls_status=False, log_nls_status=False, verbose=True)

    Call `Problem.solve()` sequentially for the individual matrix blocks of a block-triangular matrix. It is called by `Problem.solve()` if the ‘block_solve’ option is set to True.

  clear_equations()
  copy(name=None)

    Make a copy of Problem.

  create_evaluable(expression, try_equations=True, auto_init=False, preserve_caches=False, copy_materials=True, integrals=None, ebcs=None, epbcs=None, lcbcs=None, ts=None, functions=None, mode='eval', var_dict=None, strip_variables=True, extra_args=None, active_only=True, eterm_options=None, verbose=True, **kwargs)

    Create evaluable object (equations and corresponding variables) from the expression string. Convenience function calling `create_evaluable()` with defaults provided by the Problem instance self.

    The evaluable can be repeatedly evaluated by calling `eval_equations()`, e.g. for different values of variables.

    Parameters:
      expression str

        The expression to evaluate.

      try_equations bool

        Try to get variables from self.equations. If this fails, variables can either be provided in var_dict, as keyword arguments, or are created automatically according to the expression.

      auto_init bool

        Set values of all variables to all zeros.

      preserve_caches bool

        If True, do not invalidate evaluate caches of variables.

      copy_materials bool

        Work with a copy of self.equations.materials instead of reusing them. Safe but can be slow.

      integrals Integrals instance, optional

        The integrals to be used. Automatically created as needed if not given.

      ebcs Conditions instance, optional

        The essential (Dirichlet) boundary conditions for ‘weak’ mode. If not given, self.ebcs are used.

      epbcs Conditions instance, optional

        The periodic boundary conditions for ‘weak’ mode. If not given, self.epbcs are used.

      lcbcs Conditions instance, optional

        The linear combination boundary conditions for ‘weak’ mode. If not given, self.lcbcs are used.

      ts TimeStepper instance, optional

        The time stepper. If not given, self.ts is used.

      functions Functions instance, optional

        The user functions for boundary conditions, materials etc. If not given, self.functions are used.

      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.

      var_dict dict, optional

        The variables (dictionary of (variable name) : (Variable instance)) to be used in the expression. Use this if the name of a variable conflicts with one of the parameters of this method.

      strip_variables bool

        If False, the variables in var_dict or kwargs not present in the expression are added to the actual variables as a context.

      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 keyword arguments

        Additional variables can be passed as keyword arguments, see var_dict.

    Returns:
      equations Equations instance

        The equations that can be evaluated.

      variables Variables instance

        The corresponding variables. Set their values and use `eval_equations()`.

    Examples

    problem is Problem instance.

        >>> out = problem.create_evaluable('ev_integrate.i1.Omega(u)')
        >>> equations, variables = out

    vec is a vector of coefficients compatible with the field of ‘u’ - let’s use all ones.

        >>> vec = nm.ones((variables['u'].n_dof,), dtype=nm.float64)
        >>> variables['u'].set_data(vec)
        >>> vec_qp = eval_equations(equations, variables, mode='qp')

    Try another vector:

        >>> vec = 3 * nm.ones((variables['u'].n_dof,), dtype=nm.float64)
        >>> variables['u'].set_data(vec)
        >>> vec_qp = eval_equations(equations, variables, mode='qp')

  create_materials(mat_names=None)

    Create materials with names in mat_names. Their definitions have to be present in self.conf.materials.

    Notes

    This method does not change self.equations, so it should not have any side effects.

  create_state()
  create_subproblem(var_names, known_var_names)

    Create a sub-problem with equations containing only terms with the given virtual variables.

    Parameters:
      var_names list

        The list of names of virtual variables.

      known_var_names list

        The list of names of (already) known state variables.

    Returns:
      subpb Problem instance

        The sub-problem.

  create_variables(var_names=None)

    Create variables with names in var_names. Their definitions have to be present in self.conf.variables.

    Notes

    This method does not change self.equations, so it should not have any side effects.

  eval_equations(names=None, preserve_caches=False, mode='eval', dw_mode='vector', term_mode=None, active_only=True, any_dof_conn=False, verbose=True)

    Evaluate (some of) the problem’s equations, convenience wrapper of `eval_equations()`.

    Parameters:
      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.

      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.

  evaluate(expression, try_equations=True, auto_init=False, preserve_caches=False, copy_materials=True, integrals=None, ebcs=None, epbcs=None, lcbcs=None, ts=None, functions=None, mode='eval', dw_mode='vector', term_mode=None, var_dict=None, strip_variables=True, ret_variables=False, any_dof_conn=False, active_only=True, eterm_options=None, verbose=True, extra_args=None, **kwargs)

    Evaluate an expression, convenience wrapper of `Problem.create_evaluable()` and `eval_equations()`.

    Parameters:
      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.

      ret_variables bool

        If True, return the variables that were created to evaluate the expression.

      other arguments

        See docstrings of `Problem.create_evaluable()`.

    Returns:
      out array

        The result of the evaluation.

      variables Variables instance

        The variables that were created to evaluate the expression. Only provided if ret_variables is True.

  static from_conf(conf, init_fields=True, init_equations=True, init_solvers=True)
  static from_conf_file(conf_filename, required=None, other=None, init_fields=True, init_equations=True, init_solvers=True)
  get_default_ts(t0=None, t1=None, dt=None, n_step=None, step=None)
  get_dim(get_sym=False)

    Returns mesh dimension, symmetric tensor dimension (if get_sym is True).

  get_ebc_indices()

    Get indices of E(P)BC-constrained DOFs in the full global state vector.

  get_evaluator(reuse=False)

    Either create a new Evaluator instance (reuse == False), or return an existing instance, created in a preceding call to Problem.init_solvers().

  get_initial_state(vec=None)

    Create a zero state and apply initial conditions.

  get_integrals(names=None)

    Get integrals, initialized from problem configuration if available.

    Parameters:
      names list, optional

        If given, only the named integrals are returned.

    Returns:
      integrals Integrals instance

        The requested integrals.

  get_ls()
  get_materials()
  get_mesh_coors(actual=False)
  get_meshes_from_region(reg_names)
  get_nls()
  get_nls_functions()

    Returns functions to be used by a nonlinear solver to evaluate the nonlinear function value (the residual) and its gradient (the tangent matrix) corresponding to the problem equations.

    Returns:
      fun function

        The function `fun(x)` for computing the residual.

      fun_grad function

        The function `fun_grad(x)` for computing the tangent matrix.

      iter_hook function

        The optional (user-defined) function to be called before each nonlinear solver iteration iteration.

  get_output_name(suffix=None, extra=None, mode=None)

    Return default output file name, based on the output directory, output format, step suffix and mode. If present, the extra string is put just before the output format suffix.

  get_restart_filename(ts=None)

    If restarts are allowed in problem definition options, return the restart file name, based on the output directory and time step.

  get_solver()
  get_solver_conf(name)
  get_timestepper()
  get_tss()
  get_tss_functions(update_bcs=True, update_materials=True, save_results=True, step_hook=None, post_process_hook=None)

    Get the problem-dependent functions required by the time-stepping solver during the solution process.

    Parameters:
      update_bcs bool, optional

        If True, update the boundary conditions in each prestep_fun call.

      update_materials bool, optional

        If True, update the values of material parameters in each prestep_fun call.

      save_results bool, optional

        If True, save the results in each poststep_fun call.

      step_hook callable, optional

        The optional user-defined function that is called in each poststep_fun call before saving the results.

      post_process_hook callable, optional

        The optional user-defined function that is passed in each poststep_fun to `Problem.save_state()`.

    Returns:
      init_fun callable

        The initialization function called before the actual time-stepping.

      prestep_fun callable

        The function called in each time (sub-)step prior to the nonlinear solver call.

      poststep_fun callable

        The function called at the end of each time step.

  get_variables(auto_create=False)
  init_solvers(status=None, ls_conf=None, nls_conf=None, tsc_conf=None, ts_conf=None, force=False)

    Create and initialize solver instances.

    Parameters:
      status dict-like, IndexedStruct, optional

        The user-supplied object to hold the time-stepping/nonlinear solver convergence statistics.

      ls_conf Struct, optional

        The linear solver options.

      nls_conf Struct, optional

        The nonlinear solver options.

      tsc_conf Struct, optional

        The time step contoller options.

      ts_conf Struct, optional

        The time stepping solver options.

      force bool

        If True, re-create the solver instances even if they already exist in self.nls attribute.

  init_time(ts)
  is_linear()
  load_restart(filename, ts=None)

    Load the current state and time step from a restart file.

    Alternatively, a regular output file in the HDF5 format can be used in place of the restart file. In that case the restart is only approximate, because higher order field DOFs (if any) were stripped out. Files with the adaptive linearization are not supported. Use with caution!

    Parameters:
      filename str

        The restart file name.

      ts TimeStepper instance, optional

        The time stepper. If not given, a default one is created. Otherwise, it is modified in place.

    Returns:
      variables Variables instance

        The loaded variables.

  refine_uniformly(level)

    Refine the mesh uniformly level-times.

    Notes

    This operation resets almost everything (fields, equations, …) - it is roughly equivalent to creating a new Problem instance with the refined mesh.

  remove_bcs()

    Convenience function to remove boundary conditions.

  reset()
  save_ebc(filename, ebcs=None, epbcs=None, force=True, default=0.0)

    Save essential boundary conditions as state variables.

    Parameters:
      filename str

        The output file name.

      ebcs Conditions instance, optional

        The essential (Dirichlet) boundary conditions. If not given, self.conf.ebcs are used.

      epbcs Conditions instance, optional

        The periodic boundary conditions. If not given, self.conf.epbcs are used.

      force bool

        If True, sequential nonzero values are forced to individual ebcs so that the conditions are visible even when zero.

      default float

        The default constant value of state vector.

  save_regions(filename_trunk, region_names=None)

    Save regions as meshes.

    Parameters:
      filename_trunk str

        The output filename without suffix.

      region_names list, optional

        If given, only the listed regions are saved.

  save_regions_as_groups(filename_trunk, region_names=None)

    Save regions in a single mesh but mark them by using different element/node group numbers.

    See `Domain.save_regions_as_groups()` for more details.

    Parameters:
      filename_trunk str

        The output filename without suffix.

      region_names list, optional

        If given, only the listed regions are saved.

  save_restart(filename, ts=None)

    Save the current state and time step to a restart file.

    Parameters:
      filename str

        The restart file name.

      ts TimeStepper instance, optional

        The time stepper. If not given, a default one is created.

    Notes

    Does not support terms with internal state.

  save_state(filename, state=None, out=None, fill_value=None, post_process_hook=None, linearization=None, split_results_by=None, **kwargs)
    Parameters:
      split_results_by None, ‘region’, ‘variable’

        If ‘region’ or ‘variable’, data of each region/variable are stored in a separate file. If None, it is set to the application option value.

      linearization Struct or None

        The linearization configuration for higher order approximations. If its kind is ‘adaptive’, split_results_by is assumed ‘variable’.

  select_bcs(ebc_names=None, epbc_names=None, lcbc_names=None, create_matrix=False, any_dof_conn=None)
  select_materials(material_names, only_conf=False)
  select_variables(variable_names, only_conf=False)
  set_bcs(ebcs=None, epbcs=None, lcbcs=None)

    Update boundary conditions.

  set_conf_solvers(conf_solvers=None, options=None)

    Choose which solvers should be used. If solvers are not set in options, use the ones named ls, nls, ts and optionally tsc. If such solver names do not exist, use the first of each required solver kind listed in conf_solvers.

  set_default_state(vec=None)

    Return variables with an initialized state.

    A convenience function that obtains the problem equations’ variables, initializes the state ones with zeros (default) or using vec and then returns the variables.

  set_equations(conf_equations=None, user=None, keep_solvers=False, make_virtual=False)

    Set equations of the problem using the equations problem description entry.

    Fields and Regions have to be already set.

  set_equations_instance(equations, keep_solvers=False)

    Set equations of the problem to equations.

  set_fields(conf_fields=None)
  set_ics(ics=None)

    Set the initial conditions to use.

  set_linear(is_linear)
  set_materials(conf_materials=None)

    Set definition of materials.

  set_mesh_coors(coors, update_fields=False, actual=False, clear_all=True, extra_dofs=False)

    Set mesh coordinates.

    Parameters:
      coors array

        The new coordinates.

      update_fields bool

        If True, update also coordinates of fields.

      actual bool

        If True, update the actual configuration coordinates, otherwise the undeformed configuration ones.

  set_output_dir(output_dir=None)

    Set the directory for output files.

    The directory is created if it does not exist.

  set_regions(conf_regions=None, conf_materials=None, functions=None, allow_empty=False)
  set_solver(solver, status=None)

    Set a time-stepping or nonlinear solver to be used in `Problem.solve()` call.

    Parameters:
      solver NonlinearSolver or TimeSteppingSolver instance

        The nonlinear or time-stepping solver.

      status dict-like, optional

        The user-supplied object to hold the solver convergence statistics.

    Notes

    A copy of the solver is used, and the nonlinear solver functions are set to those returned by `Problem.get_nls_functions()`, if not set already. If a nonlinear solver is set, a default StationarySolver instance is created automatically as the time-stepping solver. Also sets self.ts attribute.

    If self.conf.options.auto_transform_equations is True (the default is False), the problem equations are automatically transformed to a form suitable for the given solver. Implemented for `ElastodynamicsBaseTS`-based solvers. If it is False, solver.var_names have to be defined.

  set_variables(conf_variables=None)

    Set definition of variables.

  setup_default_output(conf=None, options=None)

    Provide default values to Problem.setup_output() from conf.options and options.

  setup_hooks(options=None)

    Setup various hooks (user-defined functions), as given in options.

    Supported hooks:

    > - matrix_hook

    >   - check/modify tangent matrix in each nonlinear solver iteration

    > - nls_iter_hook

    >   - called prior to every iteration of nonlinear solver, if the solver supports that

    >   - takes the Problem instance (self) as the first argument

  setup_output(output_filename_trunk=None, output_dir=None, output_format=None, file_format=None, float_format=None, split_results_by=None, linearization=None)

    Sets output options to given values, or uses the defaults for each argument that is None.

  solve(state0=None, status=None, force_values=None, var_data=None, update_bcs=True, update_materials=True, save_results=True, step_hook=None, post_process_hook=None, post_process_hook_final=None, report_nls_status=False, log_nls_status=False, verbose=True)

    Solve the problem equations by calling the top-level solver.

    Before calling this function the top-level solver has to be set, see `Problem.set_solver()`. Also, the boundary conditions and the initial conditions (for time-dependent problems) has to be set, see `Problem.set_bcs()`, `Problem.set_ics()`.

    Parameters:
      state0 array, optional

        If given, the initial state - then the initial conditions stored in the Problem instance are ignored. By default, the initial state is created and the initial conditions are applied automatically.

      status dict-like, optional

        The user-supplied object to hold the solver convergence statistics.

      force_values dict of floats or float, optional

        If given, the supplied values override the values of the essential boundary conditions.

      var_data dict, optional

        A dictionary of {variable_name : data vector} used to initialize parameter variables.

      update_bcs bool, optional

        If True, update the boundary conditions in each prestep_fun call. See `Problem.get_tss_functions()`.

      update_materials bool, optional

        If True, update the values of material parameters in each prestep_fun call. See `Problem.get_tss_functions()`.

      save_results bool, optional

        If True, save the results in each poststep_fun call. See `Problem.get_tss_functions()`.

      step_hook callable, optional

        The optional user-defined function that is called in each poststep_fun call before saving the results. See `Problem.get_tss_functions()`.

      post_process_hook callable, optional

        The optional user-defined function that is passed in each poststep_fun to `Problem.save_state()`. See `Problem.get_tss_functions()`.

      post_process_hook_final callable, optional

        The optional user-defined function that is called after the top-level solver returns.

      report_nls_status: bool, optional

        If True, print summary non-linear solver info.

      log_nls_status: bool, optional

        If True, log non-linear solver info into a CSV file.

    Returns:
      variables Variables

        The variables with the final time step state.

  time_update(ts=None, ebcs=None, epbcs=None, lcbcs=None, functions=None, create_matrix=False, is_matrix=True, any_dof_conn=None)
  try_presolve(mtx)
  update_equations(ts=None, ebcs=None, epbcs=None, lcbcs=None, functions=None, create_matrix=False, is_matrix=True, any_dof_conn=None)

    Update equations for current time step.

    The tangent matrix graph is automatically recomputed if the set of active essential or periodic boundary conditions changed w.r.t. the previous time step.

    Parameters:
      ts TimeStepper instance, optional

        The time stepper. If not given, self.ts is used.

      ebcs Conditions instance, optional

        The essential (Dirichlet) boundary conditions. If not given, self.ebcs are used.

      epbcs Conditions instance, optional

        The periodic boundary conditions. If not given, self.epbcs are used.

      lcbcs Conditions instance, optional

        The linear combination boundary conditions. If not given, self.lcbcs are used.

      functions Functions instance, optional

        The user functions for boundary conditions, materials, etc. If not given, self.functions are used.

      create_matrix bool

        If True, force the matrix graph computation.

      is_matrix bool

        If False, the matrix is not created. Has precedence over create_matrix.

      any_dof_conn bool or None, default False

        If True, all DOF connectivities are used to pre-allocate the matrix graph. If False, only cell region connectivities are used. If None, the value is, if available, taken from conf.options.

  update_materials(ts=None, mode='normal', verbose=True)

    Update materials used in equations.

    Parameters:
      ts TimeStepper instance

        The time stepper.

      mode‘normal’, ‘update’ or ‘force’

        The update mode, see `Material.time_update()`.

      verbose bool

        If False, reduce verbosity.

  update_time_stepper(ts)

sfepy.discrete.problem.make_is_save(options)

  Given problem options, return a callable that determines whether to save results of a time step.

sfepy.discrete.problem.prepare_matrix(problem, state)

  Pre-assemble tangent system matrix.