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.
-
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_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()
andeval_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_file
(conf_filename, required=None, other=None, init_fields=True, init_equations=True, init_solvers=True)[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_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_time_solver
(ts_conf=None, **kwargs)[source]¶ Create and return a TimeSteppingSolver instance.
Notes
Also sets self.ts attribute.
-
init_solvers
(nls_status=None, ls_conf=None, nls_conf=None, mtx=None, presolve=False)[source]¶ Create and initialize solvers.
-
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.
-
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_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.
-
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_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_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.
-
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
- matrix_hook
-
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.
-