cashocs.ConstrainedOptimalControlProblem#

class cashocs.ConstrainedOptimalControlProblem(state_forms: ufl.Form | list[ufl.Form], bcs_list: fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]], cost_functional_form: list[_typing.CostFunctional] | _typing.CostFunctional, states: fenics.Function | list[fenics.Function], controls: fenics.Function | list[fenics.Function], adjoints: fenics.Function | list[fenics.Function], constraint_list: _typing.Constraint | list[_typing.Constraint], config: io.Config | None = None, riesz_scalar_products: ufl.Form | list[ufl.Form] | None = None, control_constraints: list[list[float | fenics.Function]] | None = None, initial_guess: list[fenics.Function] | None = None, ksp_options: _typing.KspOption | list[_typing.KspOption] | None = None, adjoint_ksp_options: _typing.KspOption | list[_typing.KspOption] | None = None, gradient_ksp_options: _typing.KspOption | list[_typing.KspOption] | None = None, control_bcs_list: fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]] | None = None, preconditioner_forms: list[ufl.Form] | None = None, pre_callback: Callable | None = None, post_callback: Callable | None = None, linear_solver: _utils.linalg.LinearSolver | None = None, adjoint_linear_solver: _utils.linalg.LinearSolver | None = None, newton_linearizations: ufl.Form | list[ufl.Form] | None = None, excluded_from_time_derivative: list[int] | list[list[int]] | None = None)[source]#

Bases: ConstrainedOptimizationProblem

An optimal control problem with additional (in-)equality constraints.

Initializes self.

Parameters:

  • state_forms (ufl.Form | list[ufl.Form]) – The weak form of the state equation (user implemented). Can be either a single UFL form, or a (ordered) list of UFL forms.

  • bcs_list (fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]]) – The list of fenics.DirichletBC objects describing Dirichlet (essential) boundary conditions. If this is None, then no Dirichlet boundary conditions are imposed.

  • cost_functional_form (list[_typing.CostFunctional] | _typing.CostFunctional) – UFL form of the cost functional. Can also be a list of summands of the cost functional

  • states (fenics.Function | list[fenics.Function]) – The state variable(s), can either be a fenics.Function, or a list of these.

  • controls (fenics.Function | list[fenics.Function]) – The control variable(s), can either be a fenics.Function, or a list of these.

  • adjoints (fenics.Function | list[fenics.Function]) – The adjoint variable(s), can either be a fenics.Function, or a (ordered) list of these.

  • constraint_list (_typing.Constraint | list[_typing.Constraint]) – (A list of) additional equality and inequality constraints for the problem.

  • config (io.Config | None) – config: The config file for the problem, generated via cashocs.load_config(). Alternatively, this can also be None, in which case the default configurations are used, except for the optimization algorithm. This has then to be specified in the solve method. The default is None.

  • riesz_scalar_products (ufl.Form | list[ufl.Form] | None) – The scalar products of the control space. Can either be None, a single UFL form, or a (ordered) list of UFL forms. If None, the \(L^2(\Omega)\) product is used (default is None).

  • control_constraints (list[list[float | fenics.Function]] | None) – Box constraints posed on the control, None means that there are none (default is None). The (inner) lists should contain two elements of the form [u_a, u_b], where u_a is the lower, and u_b the upper bound.

  • initial_guess (list[fenics.Function] | None) – list of functions that act as initial guess for the state variables, should be valid input for fenics.assign(). Defaults to None, which means a zero initial guess.

  • ksp_options (_typing.KspOption | list[_typing.KspOption] | None) – A list of dicts corresponding to command line options for PETSc, used to solve the state systems. If this is None, then the direct solver mumps is used (default is None).

  • adjoint_ksp_options (_typing.KspOption | list[_typing.KspOption] | None) – A list of dicts corresponding to command line options for PETSc, used to solve the adjoint systems. If this is None, then the same options as for the state systems are used (default is None).

  • gradient_ksp_options (_typing.KspOption | list[_typing.KspOption] | None) – A list of dicts corresponding to command line options for PETSc, used to compute the (shape) gradient. If this is None, either a direct or an iterative method is used (depending on the configuration, section OptimizationRoutine, key gradient_method).

  • control_bcs_list (fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]] | None) – A list of boundary conditions for the control variables. This is passed analogously to bcs_list. Default is None.

  • preconditioner_forms (list[ufl.Form] | None) – The list of forms for the preconditioner. The default is None, so that the preconditioner matrix is the same as the system matrix.

  • pre_callback (Callable | None) – A function (without arguments) that will be called before each solve of the state system

  • post_callback (Callable | None) – A function (without arguments) that will be called after the computation of the gradient.

  • linear_solver (_utils.linalg.LinearSolver | None) – The linear solver (KSP) which is used to solve the linear systems arising from the discretized PDE.

  • adjoint_linear_solver (_utils.linalg.LinearSolver | None) – The linear solver (KSP) which is used to solve the (linear) adjoint system.

  • newton_linearizations (ufl.Form | list[ufl.Form] | None) – A (list of) UFL forms describing which (alternative) linearizations should be used for the (nonlinear) state equations when solving them (with Newton’s method). The default is None, so that the Jacobian of the supplied state forms is used.

  • excluded_from_time_derivative (list[int] | list[list[int]] | None) – For each state equation, a list of indices which are not part of the first order time derivative for pseudo time stepping. Example: Pressure for incompressible flow. Default is None.

Methods Summary

inject_post_callback(function)

Changes the a-posteriori callback of the OptimizationProblem.

inject_pre_callback(function)

Changes the a-priori callback of the OptimizationProblem.

inject_pre_post_callback(pre_function, ...)

Changes the a-priori (pre) and a-posteriori (post) callbacks of the problem.

solve([method, tol, max_iter, inner_rtol, ...])

Solves the constrained optimization problem.

total_constraint_violation()

Computes the total constraint violation.

Attributes Summary

solver

Methods Documentation

inject_post_callback(function: Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) → None#

Changes the a-posteriori callback of the OptimizationProblem.

Parameters:

function (Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) – A custom function without arguments, which will be called after the computation of the gradient(s)

Return type:

None

inject_pre_callback(function: Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) → None#

Changes the a-priori callback of the OptimizationProblem.

Parameters:

function (Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) – A custom function without arguments, which will be called before each solve of the state system

Return type:

None

inject_pre_post_callback(pre_function: Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None, post_function: Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) → None#

Changes the a-priori (pre) and a-posteriori (post) callbacks of the problem.

Parameters:

  • pre_function (Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) – A function without arguments, which is to be called before each solve of the state system

  • post_function (Callable[[], None] | Callable[[_typing.OptimizationProblem], None] | None) – A function without arguments, which is to be called after each computation of the (shape) gradient

Return type:

None

solve(method: Literal['Augmented Lagrangian', 'AL', 'Quadratic Penalty', 'QP'] = 'Augmented Lagrangian', tol: float = 0.01, max_iter: int = 25, inner_rtol: float | None = None, inner_atol: float | None = None, constraint_tol: float | None = None, mu_0: float | None = None, lambda_0: list[float] | None = None) → None#

Solves the constrained optimization problem.

Parameters:

  • method (Literal['Augmented Lagrangian', 'AL', 'Quadratic Penalty', 'QP']) – The solution algorithm, either an augmented Lagrangian method (“Augmented Lagrangian”, “AL”) or quadratic penalty method (“Quadratic Penalty”, “QP”)

  • tol (float) – An overall tolerance to be used in the algorithm. This will set the relative tolerance for the inner optimization problems to tol. Default is 1e-2.

  • max_iter (int) – Maximum number of iterations for the outer solver. Default is 25.

  • inner_rtol (float | None) – Relative tolerance for the inner problem. Default is None,

  • used. (so that inner_rtol = tol is)

  • inner_atol (float | None) – Absolute tolerance for the inner problem. Default is None, so that inner_atol = tol/10 is used.

  • constraint_tol (float | None) – The tolerance for the constraint violation, which is desired. If this is None (default), then this is specified as tol/10.

  • mu_0 (float | None) – Initial value of the penalty parameter. Default is None, which means that mu_0 = 1 is used.

  • lambda_0 (list[float] | None) – Initial guess for the Lagrange multipliers. Default is None, which corresponds to a zero guess.

Return type:

None

total_constraint_violation() → float#

Computes the total constraint violation.

Returns:

The 2-norm of the total constraint violation.

Return type:

float

Attributes Documentation

solver: solvers.AugmentedLagrangianMethod | solvers.QuadraticPenaltyMethod#