sfepy.discrete.problem module

class sfepy.discrete.problem.Problem(name, conf=None, functions=None, domain=None, fields=None, equations=None, auto_conf=True, nls=None, ls=None, ts=None, auto_solvers=True)[source]

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

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

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

advance(ts=None)[source]
clear_equations()[source]
copy(name=None)[source]

Make a copy of Problem.

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)[source]

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

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()[source]
create_subproblem(var_names, known_var_names)[source]

Create a sub-problem with 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:

subpb : Problem instance

The sub-problem.

create_variables(var_names=None)[source]

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.

eval_equations(names=None, preserve_caches=False, mode='eval', dw_mode='vector', term_mode=None, verbose=True)[source]

Evaluate (some of) the problem’s equations, convenience wrapper of eval_equations().

Parameters:

names : str or sequence of str, optional

Evaluate only equations of the given name(s).

preserve_caches : bool

If True, do not invalidate evaluate caches of variables.

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.

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.

verbose : bool

If False, reduce verbosity.

Returns:

out : dict or result

The evaluation result. In ‘weak’ mode it is the vector or sparse matrix, depending on dw_mode. Otherwise, it is a dict of results with equation names as keys or a single result for a single equation.

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)[source]

Evaluate an expression, convenience wrapper of Problem.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 Problem.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)[source]
static from_conf_file(conf_filename, required=None, other=None, init_fields=True, init_equations=True, init_solvers=True)[source]
get_default_ts(t0=None, t1=None, dt=None, n_step=None, step=None)[source]
get_dim(get_sym=False)[source]

Returns mesh dimension, symmetric tensor dimension (if get_sym is True).

get_evaluator(reuse=False)[source]

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

get_integrals(names=None)[source]

Get integrals, initialized from problem configuration if available.

Parameters:

names : list, optional

If given, only the named integrals are returned.

Returns:

integrals : Integrals instance

The requested integrals.

get_materials()[source]
get_mesh_coors()[source]
get_output_name(suffix=None, extra=None, mode=None)[source]

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)[source]
get_solvers()[source]
get_time_solver(ts_conf=None, **kwargs)[source]

Create and return a TimeSteppingSolver instance.

Notes

Also sets self.ts attribute.

get_timestepper()[source]
get_variables(auto_create=False)[source]
init_solvers(nls_status=None, ls_conf=None, nls_conf=None, mtx=None, presolve=False)[source]

Create and initialize solvers.

init_time(ts)[source]
init_variables(state)[source]

Initialize variables with history.

is_linear()[source]
refine_uniformly(level)[source]

Refine the mesh uniformly level-times.

Notes

This operation resets almost everything (fields, equations, ...) - it is roughly equivalent to creating a new Problem instance with the refined mesh.

remove_bcs()[source]

Convenience function to remove boundary conditions.

reset()[source]
save_ebc(filename, ebcs=None, epbcs=None, force=True, default=0.0)[source]

Save essential boundary conditions as state variables.

Parameters:

filename : str

The output file name.

ebcs : Conditions instance, optional

The essential (Dirichlet) boundary conditions. If not given, self.conf.ebcs are used.

epbcs : Conditions instance, optional

The periodic boundary conditions. If not given, self.conf.epbcs are used.

force : bool

If True, sequential nonzero values are forced to individual ebcs so that the conditions are visible even when zero.

default : float

The default constant value of state vector.

save_field_meshes(filename_trunk)[source]
save_regions(filename_trunk, region_names=None)[source]

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)[source]

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)[source]
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)[source]
select_materials(material_names, only_conf=False)[source]
select_variables(variable_names, only_conf=False)[source]
set_bcs(ebcs=None, epbcs=None, lcbcs=None)[source]

Update boundary conditions.

set_equations(conf_equations=None, user=None, keep_solvers=False, make_virtual=False)[source]

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)[source]

Set equations of the problem to equations.

set_fields(conf_fields=None)[source]
set_linear(is_linear)[source]
set_materials(conf_materials=None)[source]

Set definition of materials.

set_mesh_coors(coors, update_fields=False, actual=False, clear_all=True)[source]

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)[source]

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)[source]
set_solvers(conf_solvers=None, options=None)[source]

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)[source]

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

set_variables(conf_variables=None)[source]

Set definition of variables.

setup_default_output(conf=None, options=None)[source]

Provide default values to Problem.setup_output() from conf.options and options.

setup_hooks(options=None)[source]

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 Problem instance (self) as the first argument
setup_ic(conf_ics=None, functions=None)[source]
setup_output(output_filename_trunk=None, output_dir=None, output_format=None, float_format=None, file_per_var=None, linearization=None)[source]

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)[source]

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)[source]
update_equations(ts=None, ebcs=None, epbcs=None, lcbcs=None, functions=None, create_matrix=False)[source]

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', verbose=True)[source]

Update materials used in equations.

Parameters:

ts : TimeStepper instance

The time stepper.

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

The update mode, see Material.time_update().

verbose : bool

If False, reduce verbosity.

update_time_stepper(ts)[source]