sfepy.fem.variables module

class sfepy.fem.variables.CloseNodesIterator(field, create_mesh=True, create_graph=True, strategy=None)

get_permutation(strategy=None)

next()

test_permutations(strategy='rcm')

class sfepy.fem.variables.FieldVariable(name, kind, field, n_components, order=None, primary_var_name=None, special=None, flags=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_bases()

Clear base functions, base function gradients and element data dimensions.

clear_current_group()

Clear current group data.

clear_evaluate_cache()

Clear current evaluate cache.

create_lcbc_operators(bcs, offset, ts=None, functions=None)

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(ig, mode='val', region=None, integral=None, integration=None, step=0, time_derivative=None, is_trace=False, 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:

ig : int

The element group index.

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 : one of ‘volume’, ‘surface’, ‘surface_extra’

The term integration type. If None, it is derived from integral.

step : int, default 0

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

derivative : None or ‘dt’

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

is_trace : bool, default False

Indicate evaluation 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, strategy='kdtree', close_limit=0.1, cache=None, ret_cells=False, ret_status=False, ret_ref_coors=False)

Evaluate self in the given physical coordinates. Convenience wrapper around Field.evaluate_at(), see its docstring for more details.

get_approximation(ig)

get_component_indices()

Return indices of variable components according to current term evaluation mode.

Returns:

indx : list of tuples

The list of (ii, slice(ii, ii + 1)) of the variable components. The first item is the index itself, the second item is a convenience slice to index components of material parameters.

get_data_shape(ig, integral, integration='volume', region_name=None)

Get element data dimensions for given approximation.

Parameters:

ig : int

The element group index.

integral : Integral instance

The integral describing used numerical quadrature.

integration : ‘volume’, ‘surface’, ‘surface_extra’ or ‘point’

The term integration type.

region_name : str

The name of surface region, required when shape_kind is ‘surface’.

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(dc_type, ig, active=False, is_trace=False)

Get active dof connectivity of a variable.

Note that primary and dual variables must have same Region!

get_dof_info(active=False)

get_element_diameters(cells, mode, square=False)

Get diameters of selected elements.

get_element_zeros()

Return array of zeros with correct shape and type for term evaluation.

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(ig, region, integral, integration, get_saved=False, return_key=False)

Get the reference element mapping of the underlying field.

See also

sfepy.fem.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, igs=None, reshape=True, step=0)

grad(ic=None, ider=None)

Return base function gradient (space elements) values in quadrature points.

Parameters:

ic : int, optional

The index of variable component.

ider : int, optional

The spatial derivative index. If not given, the whole gradient is returned.

grad_qp(ic=None, ider=None)

Return variable gradient evaluated in quadrature points.

Parameters:

ic : int, optional

The index of variable component.

ider : int, optional

The spatial derivative index. If not given, the whole gradient is returned.

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.

iter_dofs()

Iterate over element DOFs (DOF by DOF).

save_as_mesh(filename)

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

set_current_group(geo_key, ig)

Set current group data, initialize current DOF counter to None.

The current group data are the approximation, element data dimensions, base functions and base function gradients.

set_data_from_qp(data_qp, integral, step=0)

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

set_from_mesh_vertices(data)

Set the variable using values at the mesh vertices.

set_from_other(other, strategy='projection', search_strategy='kdtree', ordering_strategy='rcm', 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, 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.

If the other variable uses the same field mesh, only deformed slightly, it is advisable to provide directly the node ids as a hint where to start searching for a containing element; the order of nodes does not matter then.

Otherwise (large deformation, unrelated meshes, ...) there are basically two ways: a) query each node (its coordinates) using a KDTree of the other nodes - this completely disregards the connectivity information; b) iterate the mesh nodes so that the subsequent ones are close to each other - then also the elements of the other mesh should be close to each other: the previous one can be used as a start for the directional neighbour element crawling to the target point.

Not sure which way is faster, depends on implementation efficiency and the particular meshes.

setup_adof_conns(adof_conns, adi)

Translate dof connectivity of the variable to active dofs.

Active dof connectivity key:

(variable.name, region.name, type, ig)

setup_bases(geo_key, ig, geo, integral, shape_kind='volume')

Setup and cache base functions and base function gradients for given geometry. Also cache element data dimensions.

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.

val(ic=None)

Return base function values in quadrature points.

Parameters:

ic : int, optional

The index of variable component.

val_qp(ic=None)

Return variable evaluated in quadrature points.

Parameters:

ic : int, optional

The index of variable component.

class sfepy.fem.variables.Variable(name, kind, n_components, 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_full_state(step=0)

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()

static reset()

set_constant(val)

Set the variable to a constant value.

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.fem.variables.Variables(variables=None)

Container holding instances of Variable.

advance(ts)

apply_ebc(vec, force_values=None)

Apply essential (Dirichlet) and periodic boundary conditions defined for the state variables to vector vec.

apply_ic(vec, force_values=None)

Apply initial conditions defined for the state variables to vector vec.

check_vector_size(vec, stripped=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.

stripped : bool

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

create_state_vector()

create_stripped_state_vector()

equation_mapping(ebcs, epbcs, ts, functions, problem=None)

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

Returns:

active_bcs : set

The set of boundary conditions active in the current time.

static from_conf(conf, fields)

This method resets the variable counters for automatic order!

get_indx(var_name, stripped=False, allow_dual=False)

get_lcbc_operator()

get_matrix_shape()

get_state_part_view(state, var_name, stripped=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.

has_ebc(vec, force_values=None)

has_virtuals()

init_history()

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)

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

Passing a force_value overrides the EBC values.

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_data_from_state(var_names, state, var_names_state)

Set variables with names in var_names from state variables with names in var_names_state using DOF values in the state vector state.

set_state_part(state, part, var_name, stripped=False)

setup_adof_conns()

Translate dofs to active dofs. Active dof connectivity key = (variable.name, region.name, type, ig)

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.

setup_ordering()

Setup ordering of variables.

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

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

strip_state_vector(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.

time_update(ts, functions, verbose=True)

sfepy.fem.variables.create_adof_conn(eq, dc, indx)

Given a dof connectivity and equation mapping, create the active dof connectivity.