cashocs.ShapeOptimizationProblem#

class cashocs.ShapeOptimizationProblem(state_forms: list[ufl.Form] | ufl.Form, bcs_list: list[list[fenics.DirichletBC]] | list[fenics.DirichletBC] | fenics.DirichletBC, cost_functional_form: list[_typing.CostFunctional] | _typing.CostFunctional, states: list[fenics.Function] | fenics.Function, adjoints: list[fenics.Function] | fenics.Function, boundaries: fenics.MeshFunction, config: io.Config | None = None, shape_scalar_product: ufl.Form | 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, desired_weights: list[float] | None = None, temp_dict: dict | None = None, initial_function_values: list[float] | None = None, preconditioner_forms: list[ufl.Form] | 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: OptimizationProblem

A shape optimization problem.

This class is used to define a shape optimization problem, and to solve it subsequently. For a detailed documentation, we refer to the tutorial. For easier input, when consider single (state or control) variables, these do not have to be wrapped into a list. Note, that in the case of multiple variables these have to be grouped into ordered lists, where state_forms, bcs_list, states, adjoints have to have the same order (i.e. [y1, y2] and [p1, p2], where p1 is the adjoint of y1 and so on).

Initializes self.

Parameters:

  • state_forms (list[ufl.Form] | 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 (list[list[fenics.DirichletBC]] | list[fenics.DirichletBC] | 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 (list[fenics.Function] | fenics.Function) – The state variable(s), can either be a fenics.Function, or a list of these.

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

  • boundaries (fenics.MeshFunction) – A fenics.MeshFunction that indicates the boundary markers.

  • config (io.Config | None) – 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.

  • shape_scalar_product (ufl.Form | None) – The bilinear form for computing the shape gradient (or gradient deformation). This has to use fenics.TrialFunction and fenics.TestFunction objects to define the weak form, which have to be in a fenics.VectorFunctionSpace of continuous, linear Lagrange finite elements. Moreover, this form is required to be symmetric.

  • 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).

  • desired_weights (list[float] | None) – A list of values for scaling the cost functional terms. If this is supplied, the cost functional has to be given as list of summands. The individual terms are then scaled, so that term i has the magnitude of desired_weights[i] for the initial iteration. In case that desired_weights is None, no scaling is performed. Default is None.

  • temp_dict (dict | None) – This is a private parameter of the class, required for remeshing. This parameter must not be set by the user and should be ignored. Using this parameter may result in unintended side effects.

  • initial_function_values (list[float] | None) – This is a privatve parameter of the class, required for remeshing. This parameter must not be set by the user and should be ignored. Using this parameter may result in unintended side effects.

  • preconditioner_forms (list[ufl.Form] | 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

compute_adjoint_variables()

Solves the adjoint system.

compute_shape_gradient()

Solves the Riesz problem to determine the shape gradient.

compute_state_variables()

Solves the state system.

get_vector_field()

Returns the TestFunction for defining shape derivatives.

gradient_test([h, rng])

Performs a Taylor test to verify that the computed shape gradient is correct.

initialize_solve_parameters([algorithm, ...])

Solves the optimization problem by the method specified in the config file.

inject_post_callback(function)

Changes the a-posteriori callback of the OptimizationProblem to function.

inject_pre_callback(function)

Changes the a-priori callback of the OptimizationProblem to function.

inject_pre_post_callback(pre_function, ...)

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

shift_cost_functional([shift])

Shifts the cost functional by a constant.

solve([algorithm, rtol, atol, max_iter])

Solves the optimization problem by the method specified in the config file.

supply_adjoint_forms(adjoint_forms, ...)

Overwrites the computed weak forms of the adjoint system.

supply_custom_forms(shape_derivative, ...)

Overrides both adjoint system and shape derivative with user input.

supply_shape_derivative(shape_derivative)

Overrides the shape derivative of the reduced cost functional.

Attributes Summary

uses_custom_scalar_product

gradient

reduced_cost_functional

gradient_problem

output_manager

form_handler

optimization_variable_abstractions

adjoint_problem

state_problem

line_search

hessian_problem

solver

config

initial_guess

cost_functional_list

Methods Documentation

compute_adjoint_variables() → None#

Solves the adjoint system.

This can be used for debugging purposes and solver validation. Updates / overwrites the user input for the adjoint variables. The solution of the corresponding state system needed to determine the adjoints is carried out automatically.

Return type:

None

compute_shape_gradient() → list[fenics.Function][source]#

Solves the Riesz problem to determine the shape gradient.

This can be used for debugging, or code validation. The necessary solutions of the state and adjoint systems are carried out automatically.

Returns:

A list containing the shape gradient.

Return type:

list[fenics.Function]

compute_state_variables() → None#

Solves the state system.

This can be used for debugging purposes and to validate the solver. Updates and overwrites the user input for the state variables.

Return type:

None

get_vector_field() → dolfin.function.argument.Argument[source]#

Returns the TestFunction for defining shape derivatives.

Returns:

The TestFunction object.

Return type:

dolfin.function.argument.Argument

gradient_test(h: fenics.Function | None = None, rng: np.random.RandomState | None = None) → float[source]#

Performs a Taylor test to verify that the computed shape gradient is correct.

Parameters:

  • h (fenics.Function | None) – The direction used to compute the directional derivative. If this is None, then a random direction is used (default is None).

  • rng (np.random.RandomState | None) – A numpy random state for calculating a random direction

Returns:

The convergence order from the Taylor test. If this is (approximately) 2 or larger, everything works as expected.

Return type:

float

initialize_solve_parameters(algorithm: str | None = None, rtol: float | None = None, atol: float | None = None, max_iter: int | None = None) → None#

Solves the optimization problem by the method specified in the config file.

Parameters:

  • algorithm (str | None) – Selects the optimization algorithm. Valid choices are 'gradient_descent' or 'gd' for a gradient descent method, 'conjugate_gradient', 'nonlinear_cg', 'ncg' or 'cg' for nonlinear conjugate gradient methods, and 'lbfgs' or 'bfgs' for limited memory BFGS methods. This overwrites the value specified in the config file. If this is None, then the value in the config file is used. Default is None. In addition, for optimal control problems, one can use 'newton' for a truncated Newton method.

  • rtol (float | None) – The relative tolerance used for the termination criterion. Overwrites the value specified in the config file. If this is None, the value from the config file is taken. Default is None.

  • atol (float | None) – The absolute tolerance used for the termination criterion. Overwrites the value specified in the config file. If this is None, the value from the config file is taken. Default is None.

  • max_iter (int | None) – The maximum number of iterations the optimization algorithm can carry out before it is terminated. Overwrites the value specified in the config file. If this is None, the value from the config file is taken. Default is None.

Return type:

None

Notes

If either rtol or atol are specified as arguments to the .solve call, the termination criterion changes to:

  • a purely relative one (if only rtol is specified), i.e.,

\[|| \nabla J(u_k) || \leq \texttt{rtol} || \nabla J(u_0) ||.\]

  • a purely absolute one (if only atol is specified), i.e.,

\[|| \nabla J(u_K) || \leq \texttt{atol}.\]

  • a combined one if both rtol and atol are specified, i.e.,

\[|| \nabla J(u_k) || \leq \texttt{atol} + \texttt{rtol} || \nabla J(u_0) ||\]
inject_post_callback(function: Callable | None) → None#

Changes the a-posteriori callback of the OptimizationProblem to function.

Parameters:

function (Callable | 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) → None#

Changes the a-priori callback of the OptimizationProblem to function.

Parameters:

function (Callable | 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, post_function: Callable | None) → None#

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

Parameters:

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

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

Return type:

None

shift_cost_functional(shift: float = 0.0) → None#

Shifts the cost functional by a constant.

Parameters:

shift (float) – The constant, by which the cost functional is shifted.

Return type:

None

solve(algorithm: str | None = None, rtol: float | None = None, atol: float | None = None, max_iter: int | None = None) → None[source]#

Solves the optimization problem by the method specified in the config file.

Parameters:

  • algorithm (str | None) – Selects the optimization algorithm. Valid choices are 'gradient_descent' or 'gd' for a gradient descent method, 'conjugate_gradient', 'nonlinear_cg', 'ncg' or 'cg' for nonlinear conjugate gradient methods, and 'lbfgs' or 'bfgs' for limited memory BFGS methods. This overwrites the value specified in the config file. If this is None, then the value in the config file is used. Default is None.

  • rtol (float | None) – The relative tolerance used for the termination criterion. Overwrites the value specified in the config file. If this is None, the value from the config file is taken. Default is None.

  • atol (float | None) – The absolute tolerance used for the termination criterion. Overwrites the value specified in the config file. If this is None, the value from the config file is taken. Default is None.

  • max_iter (int | None) – The maximum number of iterations the optimization algorithm can carry out before it is terminated. Overwrites the value specified in the config file. If this is None, the value from the config file is taken. Default is None.

Return type:

None

Notes

If either rtol or atol are specified as arguments to the .solve call, the termination criterion changes to: - a purely relative one (if only rtol is specified), i.e.,

\[|| \nabla J(u_k) || \leq \texttt{rtol} || \nabla J(u_0) ||.\]

  • a purely absolute one (if only atol is specified), i.e.,

\[|| \nabla J(u_K) || \leq \texttt{atol}.\]

  • a combined one if both rtol and atol are specified, i.e.,

\[|| \nabla J(u_k) || \leq \texttt{atol} + \texttt{rtol} || \nabla J(u_0) ||\]
supply_adjoint_forms(adjoint_forms: ufl.Form | list[ufl.Form], adjoint_bcs_list: fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]]) → None#

Overwrites the computed weak forms of the adjoint system.

This allows the user to specify their own weak forms of the problems and to use cashocs merely as a solver for solving the optimization problems.

Parameters:

  • adjoint_forms (ufl.Form | list[ufl.Form]) – The UFL forms of the adjoint system(s).

  • adjoint_bcs_list (fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]]) – The list of Dirichlet boundary conditions for the adjoint system(s).

Return type:

None

supply_custom_forms(shape_derivative: ufl.Form, adjoint_forms: ufl.Form | list[ufl.Form], adjoint_bcs_list: fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]]) → None[source]#

Overrides both adjoint system and shape derivative with user input.

This allows the user to specify both the shape_derivative of the reduced cost functional and the corresponding adjoint system, and allows them to use cashocs as a solver.

Parameters:

  • shape_derivative (ufl.Form) – The shape derivative of the reduced (!) cost functional.

  • adjoint_forms (ufl.Form | list[ufl.Form]) – The UFL forms of the adjoint system(s).

  • adjoint_bcs_list (fenics.DirichletBC | list[fenics.DirichletBC] | list[list[fenics.DirichletBC]]) – The list of Dirichlet boundary conditions for the adjoint system(s).

Return type:

None

supply_shape_derivative(shape_derivative: ufl_legacy.Form) → None[source]#

Overrides the shape derivative of the reduced cost functional.

This allows users to implement their own shape derivative and use cashocs as a solver library only.

Parameters:

shape_derivative (ufl_legacy.Form) – The shape_derivative of the reduced cost functional.

Return type:

None

Attributes Documentation

uses_custom_scalar_product: bool = False#
gradient: list[fenics.Function]#
reduced_cost_functional: cost_functional.ReducedCostFunctional#
gradient_problem: _typing.GradientProblem#
output_manager: io.OutputManager#
form_handler: _forms.ShapeFormHandler#
optimization_variable_abstractions: ova.OptimizationVariableAbstractions#
adjoint_problem: _pde_problems.AdjointProblem#
state_problem: _pde_problems.StateProblem#
hessian_problem: _pde_problems.HessianProblem#
solver: optimization_algorithms.OptimizationAlgorithm | topology_optimization_algorithm.TopologyOptimizationAlgorithm#
config: io.Config#
initial_guess: list[fenics.Function] | None#
cost_functional_list: list[_typing.CostFunctional]#