# sfepy.discrete.equations module

Classes of equations composed of terms.

class sfepy.discrete.equations.Equation(name, terms, setup=True)
  collect_conn_info(conn_info, condition=None)
  collect_materials()

    Collect materials present in the terms of the equation.

  collect_variables()

    Collect variables present in the terms of the equation.

    Ensures that corresponding primary variables of test/parameter variables are always in the list, even if they are not directly used in the terms.

  evaluate(mode='eval', dw_mode='vector', term_mode=None, diff_vars=None, asm_obj=None, select_term=None, assemble=None)

    Evaluate the equation.

    Parameters:
      mode one of ‘eval’, ‘el_eval’, ‘el_avg’, ‘qp’, ‘weak’

        The evaluation mode.

      dw_mode one of ‘vector’, ‘matrix’, ‘sensitivity’

        The particular evaluation mode if mode is `'weak'`.

      term_mode str

        The term evaluation mode, used mostly if mode is `'eval'` in some terms.

      diff_vars list of str

        The names of parameters with respect to the equation is differentiated if dw_mode is `'sensitivity'`.

      asm_obj ndarray or spmatrix

        The object for storing the evaluation result in the `'weak'` mode.

      select_term function(term)

        Optional boolean function returning True for terms that should be evaluated.

      assemble function(*args, **kwargs)

        Optional alternative FE assembling function with arguments: (equation, it, term, asm_obj, vals, iels, mode=, diff_var=), where term is the evaluated term, it is the term’s order in the equation and (asm_obj, vals, iels, mode=, diff_var=) are the Term.assemble_to() arguments.

    Returns:
      out result

        The evaluation result. In ‘weak’ mode it is the asm_obj.

  static from_desc(name, desc, variables, regions, materials, integrals, user=None, eterm_options=None, allow_derivatives=False)

class sfepy.discrete.equations.Equations(equations)
  add_equation(equation)

    Add a new equation.

    Parameters:
      equation Equation instance

        The new equation.

  advance(ts)
  apply_ebc(vec=None, force_values=None)

    Apply essential (Dirichlet) boundary conditions to equations’ variables, or a given vector.

  apply_ic(vec=None, force_values=None)

    Apply initial conditions to equations’ variables, or a given vector.

  collect_conn_info(regions_changed=None)

    Collect connectivity information as defined by the equations.

    If regions_changed argument is None, new data are collecterd. Otherwise, update already collected data of terms that use the changed regions.

    Parameters:
      regions_changed str or iterable of str or None

        Name(s) of changed regions.

  collect_materials()

    Collect materials present in the terms of all equations.

  collect_variables()

    Collect variables present in the terms of all equations.

  create_matrix_graph(any_dof_conn=False, rdcs=None, cdcs=None, shape=None, active_only=True, chunk_size=200000, verbose=True)

    Create tangent matrix graph, i.e. preallocate and initialize the sparse storage needed for the tangent matrix. Order of DOF connectivities is not important.

    Parameters:
      any_dof_conn bool

        By default, only cell region DOF connectivities are used, with the exception of trace facet DOF connectivities. If True, any DOF connectivities are used.

      rdcs, cdcs arrays, optional

        Additional row and column DOF connectivities, corresponding to the variables used in the equations.

      shape tuple, optional

        The required shape, if it is different from the shape determined by the equations variables. This may be needed if additional row and column DOF connectivities are passed in.

      active_only bool

        If True, the matrix graph has reduced size and is created with the reduced (active DOFs only) numbering.

      chunk_size int

        The maximum number of cells added to the graph in one `create_dof_graph()` call.

      verbose bool

        If False, reduce verbosity.

    Returns:
      matrix csr_matrix

        The matrix graph in the form of a CSR matrix with preallocated structure and zero data.

  create_reduced_vec()
  create_subequations(var_names, known_var_names=None)

    Create sub-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:
      subequations Equations instance

        The sub-equations.

  create_vec()
  eval_residuals(state, by_blocks=False, names=None, by_terms=False, select_term=None, assemble=None)

    Evaluate (assemble) residual vectors.

    Parameters:
      state array

        The vector of DOF values. Note that it is needed only in nonlinear terms.

      by_blocks bool

        If True, return the individual blocks composing the whole residual vector. Each equation should then correspond to one required block and should be named as ‘block_name, test_variable_name, unknown_variable_name’.

      names list of str, optional

        Optionally, select only blocks with the given names, if by_blocks is True.

      by_terms bool

        If True, return a dict of the individual term residuals indexed by (<equation name>, <term index>).

      select_term function(term)

        Optional boolean function returning True for terms that should be evaluated.

      assemble function(*args, **kwargs)

        Optional alternative FE assembling function with arguments: (equation, it, term, asm_obj, vals, iels, mode=, diff_var=), where term is the evaluated term, it is the term’s order in the equation and (asm_obj, vals, iels, mode=, diff_var=) are the Term.assemble_to() arguments.

    Returns:
      out array or dict of array

        The assembled residual vector. If by_blocks is True, a dictionary is returned instead, with keys given by block_name part of the individual equation names.

  eval_tangent_matrices(state, tangent_matrix, by_blocks=False, names=None, by_terms=False, select_term=None, assemble=None)

    Evaluate (assemble) tangent matrices.

    Parameters:
      state array

        The vector of DOF values. Note that it is needed only in nonlinear terms.

      tangent_matrix csr_matrix

        The preallocated CSR matrix with zero data.

      by_blocks bool

        If True, return the individual blocks composing the whole matrix. Each equation should then correspond to one required block and should be named as ‘block_name, test_variable_name, unknown_variable_name’.

      names list of str, optional

        Optionally, select only blocks with the given names, if by_blocks is True.

      by_terms bool

        If True, return a dict of the individual term matrices indexed by (<equation name>, <term index>).

      select_term function(term)

        Optional boolean function returning True for terms that should be evaluated.

      assemble function(*args, **kwargs)

        Optional alternative FE assembling function with arguments: (equation, it, term, asm_obj, vals, iels, mode=, diff_var=), where term is the evaluated term, it is the term’s order in the equation and (asm_obj, vals, iels, mode=, diff_var=) are the Term.assemble_to() arguments.

    Returns:
      out csr_matrix or dict of csr_matrix

        The assembled matrix. If by_blocks is True, a dictionary is returned instead, with keys given by block_name part of the individual equation names.

  evaluate(names=None, mode='eval', dw_mode='vector', term_mode=None, diff_vars=None, asm_obj=None, select_term=None, assemble=None)

    Evaluate the equations.

    Parameters:
      names str or sequence of str, optional

        Evaluate only equations of the given name(s).

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

        The evaluation mode.

      dw_mode one of ‘vector’, ‘matrix’, ‘sensitivity’

        The particular evaluation mode if mode is `'weak'`.

      term_mode str

        The term evaluation mode, used mostly if mode is `'eval'` in some terms.

      diff_vars list of str

        The names of parameters with respect to the equations are differentiated if dw_mode is `'sensitivity'`.

      asm_obj ndarray or spmatrix

        The object for storing the evaluation result in the `'weak'` mode.

      select_term function(term)

        Optional boolean function returning True for terms that should be evaluated.

      assemble function(*args, **kwargs)

        Optional alternative FE assembling function with arguments: (equation, it, term, asm_obj, vals, iels, mode=, diff_var=), where term is the evaluated term, it is the term’s order in the equation and (asm_obj, vals, iels, mode=, diff_var=) are the Term.assemble_to() arguments.

    Returns:
      out dict or result

        The evaluation result. In ‘weak’ mode it is the asm_obj. Otherwise, it is a dict of results with equation names as keys or a single result for a single equation.

  static from_conf(conf, variables, regions, materials, integrals, user=None, eterm_options=None, allow_derivatives=False, verbose=True)
  get_domain()
  get_graph_conns(any_dof_conn=False, rdcs=None, cdcs=None, irs=None, ics=None, active_only=True)

    Get DOF connectivities needed for creating tangent matrix graph.

    Parameters:
      any_dof_conn bool

        By default, only cell DOF connectivities are used, with the exception of trace facet DOF connectivities. If True, any kind of DOF connectivities is allowed.

      rdcs, cdcs list of arrays, optional

        Additional row and column DOF connectivities, corresponding to the variables used in the equations.

      irs, ics: list of ints, optional

        Additional row and column block indices for each row and column connectivity pair.

      active_only bool

        If True, the active DOF connectivities have reduced size and are created with the reduced (active DOFs only) numbering.

    Returns:
      rdcs, cdcs list of arrays

        The row and column DOF connectivities defining the matrix graph blocks.

      irs, ics list of ints

        Row and column block indices for each row and column connectivity pair.

  get_lcbc_operator()
  get_variable(name)
  get_variable_dependencies()

    For each virtual variable get names of state/parameter variables that are present in terms with that virtual variable.

    The virtual variables define the actual equations and their dependencies define the variables needed to evaluate the equations.

    Returns:
      deps dict

        The dependencies as a dictionary with virtual variable names as keys and sets of state/parameter variables as values.

  get_variable_names()

    Return the list of names of all variables used in equations.

  init_state(vec=None)
  init_time(ts)
  invalidate_term_caches()

    Invalidate evaluate caches of variables present in equations.

  make_full_vec(svec, force_value=None)

    Make a full DOF vector satisfying E(P)BCs from a reduced DOF vector.

  print_terms()

    Print names of equations and their terms.

  reduce_vec(vec, follow_epbc=False)

    Get the reduced DOF vector, with EBC and PBC DOFs removed.

    Notes

    If ‘follow_epbc’ is True, values of EPBC master dofs are not simply thrown away, but added to the corresponding slave dofs, just like when assembling. For vectors with state (unknown) variables it should be set to False, for assembled vectors it should be set to True.

  reset_materials()

    Clear material data so that next materials.time_update() is performed even for stationary materials.

  set_data(data, step=0, ignore_unknown=False)

    Set data (vectors of DOF values) of variables.

    Parameters:
      data dict

        The dictionary of {variable_name : data vector}.

      step int, optional

        The time history step, 0 (default) = current.

      ignore_unknown bool, optional

        Ignore unknown variable names if data is a dict.

  set_state(vec, reduced=False, force=False, preserve_caches=False)
  setup_initial_conditions(ics, functions=None)
  time_update(ts, ebcs=None, epbcs=None, lcbcs=None, functions=None, problem=None, active_only=True, regions_changed=None, verbose=True)

    Update the equations for current time step.

    The update involves creating the mapping of active DOFs from/to all DOFs for all state variables, the setup of linear combination boundary conditions operators and the setup of active DOF connectivities.

    Parameters:
      ts TimeStepper instance

        The time stepper.

      ebcs Conditions instance, optional

        The essential (Dirichlet) boundary conditions.

      epbcs Conditions instance, optional

        The periodic boundary conditions.

      lcbcs Conditions instance, optional

        The linear combination boundary conditions.

      functions Functions instance, optional

        The user functions for boundary conditions, materials, etc.

      problem Problem instance, optional

        The problem that can be passed to user functions as a context.

      active_only bool

        If True, the active DOF connectivities and matrix graph have reduced size and are created with the reduced (active DOFs only) numbering.

      regions_changed str or iterable of str or None

        Name(s) of changed regions that need new active connectivities.

      verbose bool

        If False, reduce verbosity.

    Returns:
      graph_changed bool

        The flag set to True if the current time step set of active boundary conditions differs from the set of the previous time step.

  time_update_materials(ts, mode='normal', problem=None, verbose=True)

    Update data materials for current time and possibly also state.

    Parameters:
      ts TimeStepper instance

        The time stepper.

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

        The update mode, see `sfepy.discrete.materials.Material.time_update()`.

      problem Problem instance, optional

        The problem that can be passed to user functions as a context.

      verbose bool

        If False, reduce verbosity.

sfepy.discrete.equations.create_dof_graph(rdc, cdc, shape, active_only=False)

  Create the DOF graph corresponding to a row and column DOF connectivity.

sfepy.discrete.equations.create_matrix_graph(rdcs, cdcs, irs, ics, rdi, cdi, active_only=True, chunk_size=200000)

  Created the matrix graph using (active) DOF connectivities.

  Parameters:
    rdcs, cdcs list of arrays

      Row and column DOF connectivities, corresponding to the variables used in the equations.

    irs, ics list of ints

      Row and column block indices for each row and column connectivity pair.

    rdi, cdi DofInfo

      Row and column DOF info.

    active_only bool

      If True, the matrix graph has reduced size and is created with the reduced (active DOFs only) numbering.

    chunk_size int

      The maximum number of cells added to the graph in one `create_dof_graph()` call.

  Returns:
    graph boolean csr_matrix

      The matrix graph.

sfepy.discrete.equations.get_expression_arg_names(expression, strip_dots=True)

  Parse expression and return set of all argument names. For arguments with attribute-like syntax (e.g. materials), if strip_dots is True, only base argument names are returned.

sfepy.discrete.equations.parse_definition(equation_def)

  Parse equation definition string to create term description list.