# sfepy.discrete.variables module

Classes of variables for equations/terms.

class sfepy.discrete.variables.DGFieldVariable(name, kind, field, order=None, primary_var_name=None, special=None, flags=None, history=None, **kwargs)

  Fieald variable specificaly intended for use with DGFields, bypasses application of EBC and EPBC as this is done in DGField.

  Is instance checked in create_adof_conns.

  apply_ebc(vec, offset=0, force_values=None)

    Apply essential (Dirichlet) and periodic boundary conditions to vector vec, starting at offset.

  get_full(r_vec, r_offset=0, force_value=None, vec=None, offset=0)

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

    Notes

    The reduced vector starts in r_vec at r_offset. Passing a force_value overrides the EBC values. Optionally, vec argument can be provided to store the full vector (in place) starting at offset.

class sfepy.discrete.variables.FieldVariable(name, kind, field, order=None, primary_var_name=None, special=None, flags=None, history=None, **kwargs)

  A finite element field variable.

  field .. field description of variable (borrowed)

  apply_ebc(vec, offset=0, force_values=None)

    Apply essential (Dirichlet) and periodic boundary conditions to vector vec, starting at offset.

  apply_ic(vec, offset=0, force_values=None)

    Apply initial conditions conditions to vector vec, starting at offset.

  clear_evaluate_cache()

    Clear current evaluate cache.

  create_output(vec=None, key=None, extend=True, fill_value=None, linearization=None)

    Convert the DOF vector to a dictionary of output data usable by Mesh.write().

    Parameters:
      vec array, optional

        An alternative DOF vector to be used instead of the variable DOF vector.

      key str, optional

        The key to be used in the output dictionary instead of the variable name.

      extend bool

        Extend the DOF values to cover the whole domain.

      fill_value float or complex

        The value used to fill the missing DOF values if extend is True.

      linearization Struct or None

        The linearization configuration for higher order approximations.

  equation_mapping(bcs, var_di, ts, functions, problem=None, warn=False)

    Create the mapping of active DOFs from/to all DOFs.

    Sets n_adof.

    Returns:
      active_bcs set

        The set of boundary conditions active in the current time.

  evaluate(mode='val', region=None, integral=None, integration=None, step=0, time_derivative=None, trace_region=None, dt=None, bf=None)

    Evaluate various quantities related to the variable according to mode in quadrature points defined by integral.

    The evaluated data are cached in the variable instance in evaluate_cache attribute.

    Parameters:
      mode one of ‘val’, ‘grad’, ‘div’, ‘cauchy_strain’

        The evaluation mode.

      region Region instance, optional

        The region where the evaluation occurs. If None, the underlying field region is used.

      integral Integral instance, optional

        The integral defining quadrature points in which the evaluation occurs. If None, the first order volume integral is created. Must not be None for surface integrations.

      integration‘cell’, ‘facet’, ‘facet_extra’, or ‘point’

        The term integration type. If None, it is derived from the region kind.

      step int, default 0

        The time step (0 means current, -1 previous, …).

      time_derivative None or ‘dt’

        If not None, return time derivative of the data, approximated by the backward finite difference.

      trace_region None or str

        If not None, evaluate of trace of the variable on a boundary region.

      dt float, optional

        The time step to be used if derivative is ‘dt’. If None, the dt attribute of the variable is used.

      bf Base function, optional

        The base function to be used in ‘val’ mode.

    Returns:
      out array

        The 4-dimensional array of shape (n_el, n_qp, n_row, n_col) with the requested data, where n_row, n_col depend on mode.

  evaluate_at(coors, 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 the variable in the given physical coordinates. Convenience wrapper around `Field.evaluate_at()`, see its docstring for more details.

  get_data_shape(integral, integration='cell', region_name=None)

    Get element data dimensions for given approximation.

    Parameters:
      integral Integral instance

        The integral describing used numerical quadrature.

      integration‘cell’, ‘facet’, ‘facet_extra’, ‘point’ or ‘custom’

        The term integration mode.

      region_name str

        The name of the region of the integral.

    Returns:
      data_shape 5 ints

        The (n_el, n_qp, dim, n_en, n_comp) for volume shape kind, (n_fa, n_qp, dim, n_fn, n_comp) for surface shape kind and (n_nod, 0, 0, 1, n_comp) for point shape kind.

    Notes

    - n_el, n_fa = number of elements/facets

    - n_qp = number of quadrature points per element/facet

    - dim = spatial dimension

    - n_en, n_fn = number of element/facet nodes

    - n_comp = number of variable components in a point/node

    - n_nod = number of element nodes

  get_dof_conn(region_name, dct, trace_region=None)

    Get active dof connectivity of a variable.

    Notes

    The primary and dual variables must have the same Region.

  get_dof_info(active=False)
  get_element_diameters(cells, mode, square=False)

    Get diameters of selected elements.

  get_field()
  get_full(r_vec, r_offset=0, force_value=None, vec=None, offset=0)

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

    Notes

    The reduced vector starts in r_vec at r_offset. Passing a force_value overrides the EBC values. Optionally, vec argument can be provided to store the full vector (in place) starting at offset.

  get_interp_coors(strategy='interpolation', interp_term=None)

    Get the physical coordinates to interpolate into, based on the strategy used.

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

    Get the reference element mapping of the underlying field.

    See also

    `sfepy.discrete.common.fields.Field.get_mapping`
  get_reduced(vec, offset=0, follow_epbc=False)

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

    Notes

    The full vector starts in vec at offset. 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.

  get_state_in_region(region, reshape=True, step=0)

    Get DOFs of the variable in the given region.

    Parameters:
      region Region

        The selected region.

      reshape bool

        If True, reshape the DOF vector to a 2D array with the individual components as columns. Otherwise a 1D DOF array of the form [all DOFs in region node 0, all DOFs in region node 1, …] is returned.

      step int, default 0

        The time step (0 means current, -1 previous, …).

    Returns:
      out array

        The selected DOFs.

  has_ebc(vec=None, force_values=None)
  has_same_mesh(other)
    Returns:
      flag int

        The flag can be either ‘different’ (different meshes), ‘deformed’ (slightly deformed same mesh), or ‘same’ (same).

  invalidate_evaluate_cache(step=0)

    Invalidate variable data in evaluate cache for time step given by step (0 is current, -1 previous, …).

    This should be done, for example, prior to every nonlinear solver iteration.

  save_as_mesh(filename)

    Save the field mesh and the variable values into a file for visualization. Only the vertex values are stored.

  set_from_function(fun, step=0)

    Set the variable data (the vector of DOF values) using a function of space coordinates.

    Parameters:
      fun callable

        The function of coordinates returning DOF values of shape (n_coor, n_components).

      step int, optional

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

  set_from_mesh_vertices(data)

    Set the variable using values at the mesh vertices.

  set_from_other(other, strategy='projection', close_limit=0.1)

    Set the variable using another variable. Undefined values (e.g. outside the other mesh) are set to numpy.nan, or extrapolated.

    Parameters:
      strategy‘projection’ or ‘interpolation’

        The strategy to set the values: the L^2 orthogonal projection (not implemented!), or a direct interpolation to the nodes (nodal elements only!)

    Notes

    If the other variable uses the same field mesh, the coefficients are set directly.

  set_from_qp(data_qp, integral, step=0)

    Set DOFs of variable using values in quadrature points corresponding to the given integral.

  setup_initial_conditions(ics, di, functions, warn=False)

    Setup of initial conditions.

  time_update(ts, functions)

    Store time step, set variable data for variables with the setter function.

class sfepy.discrete.variables.Variable(name, kind, order=None, primary_var_name=None, special=None, flags=None, **kwargs)
  advance(ts)

    Advance in time the DOF state history. A copy of the DOF vector is made to prevent history modification.

  static from_conf(key, conf, fields)
  get_dual()

    Get the dual variable.

    Returns:
      var Variable instance

        The primary variable for non-state variables, or the dual variable for state variables.

  get_initial_condition()
  get_primary()

    Get the corresponding primary variable.

    Returns:
      var Variable instance

        The primary variable, or self for state variables or if primary_var_name is None, or None if no other variables are defined.

  get_primary_name()
  init_data(step=0)

    Initialize the dof vector data of time step step to zeros.

  init_history()

    Initialize data of variables with history.

  is_complex()
  is_finite(step=0, derivative=None, dt=None)
  is_kind(kind)
  is_parameter()
  is_real()
  is_state()
  is_state_or_parameter()
  is_virtual()
  set_constant(val=0.0, step=0)

    Set the variable dof vector data of time step step to a scalar val.

  set_data(data=None, indx=None, step=0, preserve_caches=False)

    Set data (vector of DOF values) of the variable.

    Parameters:
      data array

        The vector of DOF values.

      indx int, optional

        If given, data[indx] is used.

      step int, optional

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

      preserve_caches bool

        If True, do not invalidate evaluate caches of the variable.

  time_update(ts, functions)

    Implemented in subclasses.

class sfepy.discrete.variables.Variables(variables=None)

  Container holding instances of Variable.

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

    Apply essential (Dirichlet) and periodic boundary conditions to state all variables or the given vector vec.

  apply_ic(vec=None, force_values=None)

    Apply initial conditions to all state variables or the given vector vec.

  check_vec_size(vec, reduced=False)

    Check whether the shape of the DOF vector corresponds to the total number of DOFs of the state variables.

    Parameters:
      vec array

        The vector of DOF values.

      reduced bool

        If True, the size of the DOF vector should be reduced, i.e. without DOFs fixed by boundary conditions.

  create_output(vec=None, fill_value=None, var_info=None, extend=True, linearization=None)

    Creates an output dictionary with state variables data, that can be passed as ‘out’ kwarg to `Mesh.write()`.

    Then the dictionary entries are formed by components of the state vector corresponding to unknown variables according to kind of linearization given by linearization.

  create_reduced_vec()
  create_vec()
  equation_mapping(ebcs, epbcs, ts, functions, problem=None, active_only=True)

    Create the mapping of active DOFs from/to all DOFs for all state variables.

    Parameters:
      ebcs Conditions instance

        The essential (Dirichlet) boundary conditions.

      epbcs Conditions instance

        The periodic boundary conditions.

      ts TimeStepper instance

        The time stepper.

      functions Functions instance

        The user functions for boundary conditions.

      problem Problem instance, optional

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

      active_only bool

        If True, the active DOF info `self.adi` uses the reduced (active DOFs only) numbering. Otherwise it is the same as `self.di`.

    Returns:
      active_bcs set

        The set of boundary conditions active in the current time.

  fill_state(value)

    Fill the DOF vector with given value.

  static from_conf(conf, fields)
  get_dual_names()

    Get names of pairs of dual variables.

    Returns:
      duals dict

        The dual names as virtual name : state name pairs.

  get_indx(var_name, reduced=False, allow_dual=False)
  get_lcbc_operator()
  get_matrix_shape()
  get_reduced_state(follow_epbc=False, force=False)

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

  get_state(reduced=False, follow_epbc=False, force=False)
  get_state_parts(vec=None)

    Return parts of a state vector corresponding to individual state variables.

    Parameters:
      vec array, optional

        The state vector. If not given, then the data stored in the variables are returned instead.

    Returns:
      out dict

        The dictionary of the state parts.

  get_vec_part(vec, var_name, reduced=False)
  has_ebc(vec=None, force_values=None, verbose=False)
  has_virtuals()
  init_history()
  init_state(vec=None)
  invalidate_evaluate_caches(step=0)
  iter_state(ordered=True)
  link_duals()

    Link state variables with corresponding virtual variables, and assign link to self to each variable instance.

    Usually, when solving a PDE in the weak form, each state variable has a corresponding virtual variable.

  make_full_vec(svec, force_value=None, vec=None)

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

    Parameters:
      svec array

        The reduced DOF vector.

      force_value float, optional

        Passing a force_value overrides the EBC values.

      vec array, optional

        If given, the buffer for storing the result (zeroed).

    Returns:
      vec array

        The full DOF vector.

  reduce_vec(vec, follow_epbc=False, svec=None)

    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.

  set_adof_conns(adof_conns)

    Set all active DOF connectivities to self as well as relevant sub-dicts to the individual variables.

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

    Set data (vectors of DOF values) of variables.

    Parameters:
      data array

        The state vector or 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.

      preserve_caches bool

        If True, do not invalidate evaluate caches of variables.

  set_full_state(vec, force=False, preserve_caches=False)

    Set the full DOF vector (including EBC and PBC DOFs). If var_name is given, set only the DOF sub-vector corresponding to the given variable. If force is True, setting variables with LCBC DOFs is allowed.

  set_reduced_state(r_vec, preserve_caches=False)

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

    Parameters:
      r_vec array

        The reduced DOF vector corresponding to the variables.

      preserve_caches bool

        If True, do not invalidate evaluate caches of variables.

  set_state(vec, reduced=False, force=False, preserve_caches=False, apply_ebc=False)
  set_state_parts(parts, vec=None, force=False)

    Set parts of the DOF vector corresponding to individual state variables.

    Parameters:
      parts dict

        The dictionary of the DOF vector parts.

      force bool

        If True, proceed even with LCBCs present.

  set_vec_part(vec, var_name, part, reduced=False)
  setup_dof_info(make_virtual=False)

    Setup global DOF information.

  setup_dtype()

    Setup data types of state variables - all have to be of the same data type, one of nm.float64 or nm.complex128.

  setup_initial_conditions(ics, functions)
  setup_lcbc_operators(lcbcs, ts=None, functions=None)

    Prepare linear combination BC operator matrix and right-hand side vector.

  setup_ordering()

    Setup ordering of variables.

  time_update(ts, functions, verbose=True)
  update_adof_conns(adof_conns)

    Update active DOF connectivities stored in self as well as relevant sub-dicts to the individual variables.

sfepy.discrete.variables.create_adof_conn(eq, conn, dpn, offset)

  Given a node connectivity, number of DOFs per node and equation mapping, create the active dof connectivity.

  Locally (in a connectivity row), the DOFs are stored DOF-by-DOF (u_0 in all local nodes, u_1 in all local nodes, …).

  Globally (in a state vector), the DOFs are stored node-by-node (u_0, u_1, …, u_X in node 0, u_0, u_1, …, u_X in node 1, …).

sfepy.discrete.variables.create_adof_conns(conn_info, var_indx=None, active_only=True, regions_changed=None, verbose=True)

  Create active DOF connectivities for all variables referenced in conn_info.

  If a variable has not the equation mapping, a trivial mapping is assumed and connectivity with all DOFs active is created.

  DOF connectivity key is a tuple `(primary variable name, region name, type, trace_region)`.

  Notes

  If active_only is False, the 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.

sfepy.discrete.variables.expand_basis(basis, dpn)

  Expand basis for variables with several components (DOFs per node), in a way compatible with `create_adof_conn()`, according to dpn (DOF-per-node count).