# Release Notes#

These are cashocs’ release notes. Note, that only major and minor releases are covered here as they add new functionality or might change the API. For a documentation of the maintenance releases, please take a look at sblauth/cashocs.

## 2.1.0 (February 6, 2024)#

The class

`cashocs.DeformationHandler`

cannot be used anymore. Instead, use the class by calling`cashocs.geometry.DeformationHandler`

.Add the keyword arguments

`pre_callback`

and`post_callback`

to define callbacks when an optimization problem is instanciated.Callbacks can now have one parameter - the parameter supplied when being called during runtime is the optimization problem itself

Add a new function

`cashocs.io.extract_mesh_from_xdmf()`

which extracts (any, not only Gmsh) meshes from some XDMF state file (e.g. written by cashocs) and saves the underlying mesh in Gmsh file format.Add a new command line interface

`cashocs-extract_mesh`

which can be used to invoke`cashocs.io.extract_mesh_from_xdmf()`

.The output routines save the xdmf files not in a folder called xdmf anymore, but the folder is called checkpoints

The output parameter

`save_mesh`

does now not only save the optimized mesh, but also writes a Gmsh .msh file of the current iterated mesh for each iteration. This is very useful for restarting simulations.Added the function

`cashocs.io.import_function()`

which can be used to load a XDMF Function with a function space. This is very useful for checkpointing (first, read the saved mesh, define the function space, then call`cashocs.io.import_function()`

.`cashocs.import_mesh()`

can now also directly import a Gmsh mesh file. Internally, the mesh is directly converted to xdmf and then read. At the moment, this only supports the conversion mode physical.Add the kwargs linear_solver and (where applicable) adjoint_linear_solver. These can be used to define custom python KSP objects via petsc4py, most importantly, custom python-based preconditioners can be used with these. The feature is covered in the undocumented demo “demos/shape_optimization/python_pc”.

Add the kwarg newton_linearization to the optimization problem classes. This can be used to specify which (alternative) linearization techniques can be used for solving the nonlinear state systems.

The function

`cashocs.newton_solve()`

does not change the user-specified tolerance (in the ksp_options) anymore, unless the kwarg inexact=True is set. This means, that the user can use custom “inexact Newton” schemes (e.g., gain one digit in accuracy) too. The old default was to use the relative tolerance of the nonlinear iteration multiplied with a safety factor (0.1).New configuration file parameters:

Section LineSearch

`fail_if_not_converged`

determines, whether the line search is cancelled once the state system cannot be solved or if a new iterate is tried instead.

Section ShapeGradient

`inhomogeneous_exponent`

is a float, which specifies an exponent for the inhomogeneous mesh stiffness

Section MeshQuality

`remesh_iter`

is used to perform a remeshing after a certain amount of iterations.

## 2.0.0 (May 16, 2023)#

cashocs has a new docstyle. It now uses the pydata-sphinx-theme.

Added space mapping methods to cashocs. The space mapping methods can utilize parallelism via MPI.

Added polynomial based models for computing trial stepsizes in an extended Armijo rule.

implemented a wrapper for

`cashocs-convert`

, so that this can be used from inside python too. Simply call`cashocs.convert()`

.`cashocs-convert`

now has a default output argument (which is the same name as the input file). This can be invoked with the`-o`

or`--outfile flag`

.`cashocs-convert`

now has an additional quiet flag, which can be invoked with`-q`

or`--quiet`

. Analogously,`cashocs.convert()`

also has a keyword argument`quiet`

. These arguments / flags suppress its output.cashocs now saves files in XDMF file format for visualization and does not use .pvd files anymore. This greatly reduces the number of files needed and also enables better visualization for remeshing.

cashocs’ print calls now flush the output buffer, which helps when sys.stdout is a file.

The “hook” methods of cashocs (

`pre_hook`

and`post_hook`

) are renamed to “callback”, see, e.g.,`inject_pre_callback`

.cashocs now uses pathlib over os.path

cashocs’ loggers are now not colored anymore, which makes reading the log easier if one logs to a file

Added i/o possibilites to read meshes and functions from the data saved in the xdmf files for visualization. This is documented here.

Deprecated functions have been removed. In particular, the functions

`create_bcs_list()`

,`create_config()`

,`damped_newton_solve()`

are removed. They are replaced by`create_dirichlet_bcs`

,`load_config`

, and`newton_solve`

.The usage of the keyword arguments

`scalar_tracking_forms`

and`min_max_terms`

in`ShapeOptimizationProblem`

and`OptimalControlProblem`

has been removed. Instead, every cost functional is now passed via the`cost_functional_list`

parameter. Scalar tracking forms are now realized via`ScalarTrackingFunctional`

and min-max terms via`MinMaxFunctional`

, see https://cashocs.readthedocs.io/en/stable/user/demos/optimal_control/demo_scalar_control_tracking.BFGS methods can now be used in a restarted fashion, if desired.

The BFGS method can now be used in a damped fashion. This ensures that the inverse Hessian approximation stays positive definite.

The options for defining parameters which are to be supplied to PETSc KSP objects have changed their datatype: They are now given by (lists of) dictionaries instead of nested lists. For options without a value in the command line (e.g. the option

`-ksp_view`

) have a value of`None`

in the dictionary (so`'ksp_view': None`

can be used inside the dictionary to supply the aforementioned option).cashocs now includes a

`cashocs.linear_solve()`

that can be used to solve linear problems.Optimization problems, constrained problems, space mapping problems, and linear and nonlinear solvers now include the keyword argument

`preconditioner_forms`

, which is a list of UFL forms used to define the preconditioner matrices for solving the respective PDEs.Added different mesh conversion modes for

`cashocs.convert()`

, which are`"physical"`

,`"geometrical"`

, and`"none"`

. These are used to either use the physical or geometrical entities of Gmsh for the definition of the boundaries and subdomains (or neither of these).Changed configuration file parameters

Section OptimizationRoutine

`maximum_iterations`

is now called`max_iter`

Section Output

`save_pvd`

is now called`save_state`

, functionality is the same`save_pvd_adjoint`

is now called`save_adjoint`

, functionality is the same`save_pvd_gradient`

is now called`save_gradient`

, functionality is the same

Section LineSearch

The parameters

`initial_stepsize`

,`epsilon_armijo`

,`beta_armijo`

, and`safeguard_stepsize`

are moved from the OptimizationRoutine section to the LineSearch section. Their behavior is unaltered.

New configuration file parameters

Section AlgoLBFGS

`bfgs_periodic_restart`

is an integer parameter. If this is 0 (the default), no restarting is done. If this is >0, then the BFGS method is restarted after as many iterations, as given in the parameter`damped`

is a boolean flag which indicates, whether damping should be used for the BFGS method. The default is`damped = False`

.

Section LineSearch is a completely new section where the line searches can be configured.

`method`

is a string parameter, which can take the values`method = armijo`

(which is the default previous line search) and`method = polynomial`

(which are the new models)`polynomial_model`

is a string parameter which can be either`polynomial_model = quadratic`

or`polynomial_model = cubic`

. In case this is`polynomial_model = quadratic`

, three values (current function value, directional derivative, and trial function value) are used to generate a quadratic model of the one-dimensional cost functional. If this is`polynmomial_model = cubic`

, a cubic model is generated based on the last two guesses for the stepsize. These models are exactly minimized to get a new trial stepsize and a safeguarding is applied so that the steps remain feasible.`factor_high`

is one parameter for the safeguarding, the upper bound for the search interval for the stepsize (this is multiplied with the previous stepsize)`factor_low`

is the other parameter for the safeguarding, the lower bound for the search interval for the stepsize (this is multiplied with the previous stepsize)

Section Output

`precision`

is an integer which specifies the precision (number of significant digits) when printing to console or file. Default is, as before, 3 significant digits.

## 1.8.0 (July 6, 2022)#

cashocs now has a better memory efficiency

The printing and file output of cashocs has been modified to better readable and fit the default console window

The ksp keyword argument for solver routines in the

`_utils`

module has been removed. Now, KSP objects can be interfaced only directly via`ksp_options`

Rename the default branch from “master” to “main”

Implement the “guard against poor scaling” for the stepsize computation from Kelley, but only for the initial stepsize

New configuration file parameters

Section OptimizationRoutine

`safeguard_stepsize`

is a boolean parameter which dis-/enables the guard against poor scaling for the initial iteration

## 1.7.0 (April 20, 2022)#

MPI Support - cashocs now has full MPI support. All of its features, including remeshing, now work out of the box in parallel. Nearly any script using cashocs can be run in parallel by invoking it via

`mpirun -n p python script.py`

, where`p`

is the number of MPI processes. Note, that running in parallel may sometimes cause unexpected behavior as it is not tested as well as the serial usage. If you should encounter any bugs, please report them.

## 1.6.0 (April 4, 2022)#

Added the possibility to define additional constraints for the optimization problems as well as solvers which can be used to solve these new problems. This includes Augmented Lagrangian and Quadratic Penalty methods. This feature is documented at https://cashocs.readthedocs.io/en/stable/user/demos/optimal_control/demo_constraints.

Added the possibility for users to execute their own code before each solution of the state system or after each computation of the gradient with the help of

`inject_pre_callback`

and`inject_post_callback`

. This is documented at https://cashocs.readthedocs.io/en/stable/user/demos/optimal_control/demo_pre_post_callbacks.Added the possibility to define boundary conditions for control variables. This is documented at https://cashocs.readthedocs.io/en/stable/user/demos/optimal_control/demo_control_boundary_conditions.

Added new style cost functionals, namely

`cashocs.IntegralFunctional`

,`cashocs.ScalarTrackingFunctional`

and`cashocs.MinMaxFunctional`

. These allow for a clearer definition of cost functionals and will replace the keyword arguments`scalar_tracking_forms`

and`min_max_terms`

in the future. The new style cost functionals allow for greater flexibility and extensibility in the future.Added the possibility to choose between a direct and iterative solver for computing (shape) gradients.

Reworked the private interface of cashocs for better extensibility. The

`utils`

submodule is now private. Added a new`cashocs.io`

submodule for handling in- and output.Reworked the way configuration files are treated in cashocs. Now, they are validated and an exception is raised if a config is found to be invalid.

New configuration file parameters:

Section OptimizationRoutine

`gradient_method`

is either`gradient_method = direct`

or`gradient_method = iterative`

and specifies that the corresponding type of solver is used to compute the gradient.`gradient_tol`

specifies the tolerance which is used in case an iterative solver is used to compute the (shape) gradient.

## 1.5.0 (December 22, 2021)#

Major performance increase (particularly for large problems)

Added support for using the p-Laplacian to compute the shape gradient.

cashocs now also imports Gmsh Physical Group information when it is given by strings, which can be used in integration measures (e.g.,

`dx('part1')`

or`ds('inlet')`

, or for creating Dirichlet boundary conditions (e.g.`cashocs.create_dirichlet_bcs(V, Constant(0.0), boundaries, 'dirichlet_boundary')`

).The nonlinear solver (Newton’s method) got an additional

`inexact`

parameter, which allows users to use an inexact Newton’s method with iterative solvers. Additionally, users can specify their own Jacobians to be used in Newton’s method with the keyword argument`dF`

.Users can now specify the weight of the scalar tracking terms individually (this is now documented).

New configuration file parameters:

Section ShapeGradient

`use_p_laplacian`

is a boolean flag which enables the use of the p-Laplacian for the computation of the shape gradient`p_laplacian_power`

is an integer parameter specifying the power p used for the p-Laplacian`p_laplacian_stabilization`

is a float parameter, which acts as stabilization term for the p-Laplacian. This should be positive and small (e.g. 1e-3).`update_inhomogeneous`

is a boolean parameter, which allows to update the cell volume when using`inhomogeneous = True`

in the ShapeGradient section. This makes small elements have a higher stiffness and updates this over the course of the optimization. Default is`update_inhomogeneous = False`

## 1.4.0 (September 3, 2021)#

Added the possibility to compute the stiffness for the shape gradient based on the distance to the boundary using the eikonal equation

Cashocs now supports the tracking of scalar quantities, which are given as integrals of the states / controls / geometric properties. Input parameter is

`scalar_tracking_forms`

, which is a dictionary consisting of`'integrand'`

, which is the integrand of the scalar quantity, and`'tracking_goal'`

, which is the (scalar) value that shall be achieved. This feature is documented at https://cashocs.readthedocs.io/en/stable/user/demos/optimal_control/demo_scalar_control_tracking.Fixed a bug concerning cashocs’ memory management, which would occur if several OptimizationProblems were created one after the other

Changed the coding style to “black”

Switched printing to f-string syntax for better readability

Config files are now copied when they are passed to OptimizationProblems, so that manipulation of them is only possible before the instance is created

New configuration file parameters:

Section ShapeGradient

`use_distance_mu`

is a boolean flag which enables stiffness computation based on distances`dist_min`

and`dist_max`

describe the minimal and maximum distance to the boundary for which a certain stiffness is used (see below)`mu_min`

and`mu_max`

describe the stiffness values: If the boundary distance is smaller than`dist_min`

, then`mu = mu_min`

and if the distance is larger than`dist_max`

, we have`mu = mu_max`

`smooth_mu`

is a boolean flag, which determines how`mu`

is interpolated between`dist_min`

and`dist_max`

: If this is set to False, linear interpolation is used, otherwise, a cubic spline is used`boundaries_dist`

is a list of boundary indices to which the distance shall be computed

Small bugfixes and other improvements:

Switched to pseudo random numbers for the tests for the sake of reproduceability

fixed some tolerances for the tests

replaced

`os.system()`

calls by`subprocess.run()`

## 1.3.0 (June 11, 2021)#

Improved the remeshing workflow and fixed several smaller bugs concerning it

New configuration file parameters:

Section Output

`save_pvd_adjoint`

is a boolean flag which allows users to also save adjoint states in paraview format`save_pvd_gradient`

is a boolean flag which allows users to save the (shape) gradient(s) in paraview format`save_txt`

is a boolean flag, which allows users to capture the command line output as .txt file

## 1.2.0 (December 01, 2020)#

Users can now supply their own bilinear form (or scalar product) for the computation of the shape gradient, which is then used instead of the linear elasticity formulation. This is documented at https://cashocs.readthedocs.io/en/stable/user/demos/shape_optimization/demo_custom_scalar_product.

Added a curvature regularization term for shape optimization, which can be enabled via the config files, similarly to already implemented regularizations. This is documented at https://cashocs.readthedocs.io/en/stable/user/demos/shape_optimization/demo_regularization.

cashocs can now scale individual terms of the cost functional if this is desired. This allows for a more granular handling of problems with cost functionals consisting of multiple terms. This also extends to the regularizations for shape optimization, see https://cashocs.readthedocs.io/en/stable/user/demos/shape_optimization/demo_regularization. This feature is documented at https://cashocs.readthedocs.io/en/stable/user/demos/shape_optimization/demo_scaling.

cashocs now uses the logging module to issue messages for the user. The level of verbosity can be controlled via

`cashocs.set_log_level()`

.New configuration file parameters:

Section Regularization:

`factor_curvature`

can be used to specify the weight for the curvature regularization term.`use_relative_weights`

is a boolean which specifies, whether the weights should be used as scaling factor in front of the regularization terms (if this is False), or whether they should be used to scale the regularization terms so that they have the prescribed value on the initial iteration (if this is True).

## 1.1.0 (November 13, 2020)#

Added the functionality for cashocs to be used as a solver only, where users can specify their custom adjoint equations and (shape) derivatives for the optimization problems. This is documented at https://cashocs.readthedocs.io/en/stable/user/demos/cashocs_as_solver/index.

Using

`cashocs.create_config()`

is deprecated and replaced by`cashocs.load_config()`

, but the former will still be supported.Configuration files are now not strictly necessary, but still very strongly recommended.

New configuration file parameters:

Section Output:

`result_dir`

can be used to specify where cashocs’ output files should be placed.

## 1.0.0 (September 18, 2020)#

Initial release of cashocs.