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, active_only=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.

Notes

The Problem is by default created with active_only set to True. Then the (tangent) matrices and residual vectors (right-hand sides) have reduced sizes and contain only the active DOFs, i.e., DOFs not constrained by EBCs or EPBCs. Setting active_only to False results in full-size vectors and matrices. Then the matrix size non-zeros structure does not depend on the actual E(P)BCs applied. It must be False when using parallel PETSc solvers.

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_restart_filename(ts=None)[source]

If restarts are allowed in problem definition options, return the restart file name, based on the output directory and time step.

get_solver()[source]
get_solver_conf(name)[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, force=False)[source]

Create and initialize solver instances.

Parameters:

nls_status : dict-like, IndexedStruct, optional

The user-supplied object to hold nonlinear solver convergence statistics.

ls_conf : Struct, optional

The linear solver options.

nls_conf : Struct, optional

The nonlinear solver options.

force : bool

If True, re-create the solver instances even if they already exist in self.nls attribute.

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

Initialize variables with history.

is_linear()[source]
load_restart(filename, state=None, ts=None)[source]

Load the current state and time step from a restart file.

Alternatively, a regular output file in the HDF5 format can be used in place of the restart file. In that case the restart is only approximate, because higher order field DOFs (if any) were stripped out. Files with the adaptive linearization are not supported. Use with caution!

Parameters:

filename : str

The restart file name.

state : State instance, optional

The state instance. If not given, a new state is created using the variables in problem equations. Otherwise, its variables are modified in place.

ts : TimeStepper instance, optional

The time stepper. If not given, a default one is created. Otherwise, it is modified in place.

Returns:

new_state : State instance

The loaded state.

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_restart(filename, state=None, ts=None)[source]

Save the current state and time step to a restart file.

Parameters:

filename : str

The restart file name.

state : State instance, optional

The state instance. If not given, a new state is created using the variables in problem equations.

ts : TimeStepper instance, optional

The time stepper. If not given, a default one is created.

Notes

Does not support terms with internal state.

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_conf_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_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_ics(ics=None)[source]

Set the initial conditions to use.

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

Set the instance of nonlinear solver 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_ics(ics=None, functions=None)[source]

Setup the initial conditions for use.

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

create_matrix : bool

If True, force the matrix graph computation.

is_matrix : bool

If False, the matrix is not created. Has precedence over create_matrix.

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]