sfepy.fem.problemDef module

class sfepy.fem.problemDef.ProblemDefinition(name, conf=None, functions=None, domain=None, fields=None, equations=None, auto_conf=True, nls=None, ls=None, ts=None, auto_solvers=True)

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

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

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

advance(ts=None)

clear_equations()

copy(name=None)

Make a copy of ProblemDefinition.

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, verbose=True, **kwargs)

Create evaluable object (equations and corresponding variables) from the expression string. Convenience function calling create_evaluable() with defaults provided by the ProblemDefinition 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.

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 ProblemDefinition instance.

>>> out = problem.create_evaluable('dq_state_in_volume_qp.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_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.

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, verbose=True, extra_args=None, **kwargs)

Evaluate an expression, convenience wrapper of ProblemDefinition.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 ProblemDefinition.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_evaluator(reuse=False)

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

get_integrals(names=None, kind=None)

Get integrals, initialized from problem configuration if available.

Parameters:

names : list, optional

If given, only the named integrals are returned.

kind : ‘v’ or ‘s’, optional

If given, only integrals of the given kind are returned.

Returns:

integrals : Integrals instance

The requested integrals.

get_materials()

get_mesh_coors()

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

get_solvers()

get_time_solver(ts_conf=None, **kwargs)

Create and return a TimeSteppingSolver instance.

Notes

Also sets self.ts attribute.

get_timestepper()

get_variables(auto_create=False)

init_solvers(nls_status=None, ls_conf=None, nls_conf=None, mtx=None, presolve=False)

Create and initialize solvers.

init_time(ts)

init_variables(state)

Initialize variables with history.

is_linear()

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 ProblemDefinition instance with the refined mesh.

remove_bcs()

Convenience function to remove boundary conditions.

reset()

save_ebc(filename, force=True, default=0.0)

Save essential boundary conditions as state variables.

save_field_meshes(filename_trunk)

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_state(filename, state=None, out=None, fill_value=None, post_process_hook=None, linearization=None, file_per_var=False, **kwargs)

Parameters:

file_per_var : bool or None

If True, data of each 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’, file_per_var is assumed True.

select_bcs(ebc_names=None, epbc_names=None, lcbc_names=None, create_matrix=False)

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_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_linear(is_linear)

set_materials(conf_materials=None)

Set definition of materials.

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

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)

set_solvers(conf_solvers=None, options=None)

Choose which solvers should be used. If solvers are not set in options, use first suitable in conf_solvers.

set_solvers_instances(ls=None, nls=None)

Set the instances of linear and nonlinear solvers that will be used in ProblemDefinition.solve() call.

set_variables(conf_variables=None)

Set definition of variables.

setup_default_output(conf=None, options=None)

Provide default values to ProblemDefinition.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 ProblemDefinition instance (self) as the first argument

setup_ic(conf_ics=None, functions=None)

setup_output(output_filename_trunk=None, output_dir=None, output_format=None, float_format=None, file_per_var=None, linearization=None)

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

solve(state0=None, nls_status=None, ls_conf=None, nls_conf=None, force_values=None, var_data=None)

Solve self.equations in current time step.

Parameters:

var_data : dict

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

time_update(ts=None, ebcs=None, epbcs=None, lcbcs=None, functions=None, create_matrix=False)

update_equations(ts=None, ebcs=None, epbcs=None, lcbcs=None, functions=None, create_matrix=False)

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.

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

Update materials used in equations.

update_time_stepper(ts)