sfepy.discrete.equations module

Classes of equations composed of terms.

class sfepy.discrete.equations.Equation(name, terms, setup=True)

collect_conn_info(conn_info)

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)

Evaluate the equation.

Parameters:

modeone of ‘eval’, ‘el_eval’, ‘el_avg’, ‘qp’, ‘weak’

The evaluation mode.

dw_modeone of ‘vector’, ‘matrix’, ‘sensitivity’

The particular evaluation mode if mode is 'weak'.

term_modestr

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

diff_varslist of str

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

asm_objndarray or spmatrix

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

Returns:

outresult

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:

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

Collect connectivity information as defined by the equations.

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, 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_connbool

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, cdcsarrays, optional

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

shapetuple, 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_onlybool

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

verbosebool

If False, reduce verbosity.

Returns:

matrixcsr_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_nameslist

The list of names of virtual variables.

known_var_nameslist

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

Returns:

subequationsEquations instance

The sub-equations.

create_vec()

eval_residuals(state, by_blocks=False, names=None)

Evaluate (assemble) residual vectors.

Parameters:

statearray

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

by_blocksbool

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’.

nameslist of str, optional

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

Returns:

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

Evaluate (assemble) tangent matrices.

Parameters:

statearray

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

tangent_matrixcsr_matrix

The preallocated CSR matrix with zero data.

by_blocksbool

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’.

nameslist of str, optional

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

Returns:

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

Evaluate the equations.

Parameters:

namesstr or sequence of str, optional

Evaluate only equations of the given name(s).

modeone of ‘eval’, ‘el_avg’, ‘qp’, ‘weak’

The evaluation mode.

dw_modeone of ‘vector’, ‘matrix’, ‘sensitivity’

The particular evaluation mode if mode is 'weak'.

term_modestr

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

diff_varslist of str

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

asm_objndarray or spmatrix

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

Returns:

outdict 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, active_only=True)

Get DOF connectivities needed for creating tangent matrix graph.

Parameters:

any_dof_connbool

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, cdcsarrays, optional

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

active_onlybool

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

Returns:

rdcs, cdcsarrays

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

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:

depsdict

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:

datadict

The dictionary of {variable_name : data vector}.

stepint, optional

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

ignore_unknownbool, 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, 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:

tsTimeStepper instance

The time stepper.

ebcsConditions instance, optional

The essential (Dirichlet) boundary conditions.

epbcsConditions instance, optional

The periodic boundary conditions.

lcbcsConditions instance, optional

The linear combination boundary conditions.

functionsFunctions instance, optional

The user functions for boundary conditions, materials, etc.

problemProblem instance, optional

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

active_onlybool

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

verbosebool

If False, reduce verbosity.

Returns:

graph_changedbool

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:

tsTimeStepper instance

The time stepper.

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

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

problemProblem instance, optional

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

verbosebool

If False, reduce verbosity.

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.