Cashocs

----------------------

* Add the possibility to re-compute the gradient deformation in shape optimization. To do so, the gradient deformation is first computed as before but then only the surface deformation (or the one in normal direction) is used as boundary condition for the elasticty equation to compute a new deformation. This can help to avoid numerical artifacts in the interior of the domain not related to the actual shape changes.

* Update the way :py:func:`cashocs.ts_pseudo_solve` handles convergence / divergence. A new divergence tolerance is introduced. If the residual increases by a factor of 1e4, the solver automatically diverges and raises a corresponding exception. Moreover, if the solver reaches the maximum number of iterations, no exception is raised anymore. Instead, a warning is issued that the solver did not reach the specified tolerances, but converges anyway. This is in line with the convergence of the PETSc TS.

* Add support for Python 3.13.

* Functions with Crouzeix-Raviart elements are now interpolated into discontinuous Galerkin FEM spaces before being saved as .xdmf file so that they can be worked with.

* New configuration file parameters:

* Section ShapeGradient

* :ini:`reextend_from_boundary` is a boolean flag which indicates whether the gradient deformation should be re-computed as described above

* :ini:`reextension_mode` can have the values :ini:`reextension_mode = surface` or :ini:`reextension_mode = normal`. In the first case, the boundary values of the gradient deformation are used as they are for the re-extension, in the second case only the normal deformation is used.

------------------------

* Add support for named Gmsh meshes, so that the names can not only be used with :py:func:`cashocs.create_dirichlet_bcs`, but also with the :py:class:`cashocs.NamedMeasure` objects created with :py:func:`cashocs.import_mesh`.

* Add a pseudo time stepping solver for nonlinear equations. This uses PETSc's TS and is implemented in :py:func:`cashocs.ts_pseudo_solve`. The pseudo time stepping is also available for optimization problems and documented at `<https://cashocs.readthedocs.io/en/stable/user/demos/shape_optimization/demo_pseudo_time_stepping/>`_.

* Add a Poisson approach for computing the distance to the wall. This should be more robust than the previous approach of solving the Eikonal equation but less robust. The method can be changed in the configuration (see "New configuration file parameters" below).

* New configuration file parameters:

* Section ShapeGradient

* :ini:`distance_method` specifies which method should be used to compute the distance to the boundary. The default is :ini:`distance_method = eikonal`, but the new Poisson approach can be used with :ini:`distance_method = poisson`.

-------------------------

* The handling of the terminal output (and some other outputs) has changed significantly and now uses the python logging library. This allows for a greater flexibility and automatically times operations. The downside of this is, that the configuration has to change. Particularly, the :ini:`verbose` and :ini:`save_txt` parameters are now deprecated and will be removed in the future. These are kept for backwards compatibility reasons, but their default value is set to `False` to use the new logging-based approach. Moreover, almost any place where a flag such as a keyword argument :python:`verbose` or :python:`quiet` is used, is deprecated and will be removed in the future. Here, too, the logging-based approach is used by default now. If your applications are too verbose for you now, you can call :python:`cashocs.log.set_log_level(cashocs.log.WARNING)` to increase the log level. A brief documentation of the logging capabilities can be found at `<https://cashocs.readthedocs.io/en/stable/user/demos/misc/demo_logging/>`_.

* Properly handle the output for nested problems in the context of space mapping and additional constraints. The output config is applied to all problems and the sub- and main problems all write their history to files and console.

* Topology optimization problems now work as expected in parallel, with the exception that there is no support for angle-weighted interpolation of the topological derivative. Now, a corresponding exception is raised by cashocs.

* Add additional documentation for the configuration parameters for topology optimization which can be found at `<https://cashocs.readthedocs.io/en/stable/user/demos/topology_optimization/doc_config/>`_.

-----------------------

* Add a wrapper for PETSc's SNES solver for nonlinear equations. This is used internally in cashocs whenever possible. For the solution of the state system, our own Newton solver is the default for backwards compatibility. Users can use the new SNES backend by specifying :ini:`backend = petsc` in the Section StateSystem of the configuration.

* Allows nesting of PETSc Fieldsplit PCs with the command line option "pc_fieldsplit_%d_fields <a,b,...>, as explained at `<https://petsc.org/main/manualpages/PC/PCFieldSplitSetFields/>`_

* Increase the precision of the Gmsh output from cashocs

* New configuration file parameters:

* Section StateSystem

* :ini:`backend` specifies which backend is used for solving nonlinear equations. The default is :ini:`backend = cashocs`, which is the "old" behavior, and :ini:`backend = petsc` uses the new PETSc SNES interface.

* Section ShapeGradient

* :ini:`test_for_intersections` is used to disable the (post mesh movement) check for intersections of the mesh, which ensures physically reasonable designs. This should not be set to `False`.

------------------------

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

* Add the keyword arguments :python:`pre_callback` and :python:`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 :py:func:`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 :bash:`cashocs-extract_mesh` which can be used to invoke :py:func:`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 :ini:`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 :py:func:`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 :py:func:`cashocs.io.import_function`.

* :py:func:`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 :py:func:`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

* :ini:`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

* :ini:`inhomogeneous_exponent` is a float, which specifies an exponent for the inhomogeneous mesh stiffness

* Section MeshQuality

* :ini:`remesh_iter` is used to perform a remeshing after a certain amount of iterations.

--------------------

* cashocs has a new docstyle. It now uses the `pydata-sphinx-theme <https://pydata-sphinx-theme.readthedocs.io/en/latest/>`_.

* 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 :bash:`cashocs-convert`, so that this can be used from inside python too. Simply call :py:func:`cashocs.convert`.

* :bash:`cashocs-convert` now has a default output argument (which is the same name as the input file). This can be invoked with the :bash:`-o` or :bash:`--outfile flag`.

* :bash:`cashocs-convert` now has an additional quiet flag, which can be invoked with :bash:`-q` or :bash:`--quiet`. Analogously, :py:func:`cashocs.convert` also has a keyword argument :python:`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 (:python:`pre_hook` and :python:`post_hook`) are renamed to "callback", see, e.g., :py:meth:`inject_pre_callback <cashocs.optimization_problem.OptimizationProblem.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 <https://cashocs.readthedocs.io/en/stable/user/demos/misc/demo_xdmf_io/>`_.

* Deprecated functions have been removed. In particular, the functions :py:func:`create_bcs_list`, :py:func:`create_config`, :py:func:`damped_newton_solve` are removed. They are replaced by :py:func:`create_dirichlet_bcs <cashocs.create_dirichlet_bcs>`, :py:func:`load_config <cashocs.load_config>`, and :py:func:`newton_solve <cashocs.newton_solve>`.

* The usage of the keyword arguments :python:`scalar_tracking_forms` and :python:`min_max_terms` in :py:class:`ShapeOptimizationProblem <cashocs.ShapeOptimizationProblem>` and :py:class:`OptimalControlProblem <cashocs.OptimalControlProblem>` has been removed. Instead, every cost functional is now passed via the :python:`cost_functional_list` parameter. Scalar tracking forms are now realized via :py:class:`ScalarTrackingFunctional <cashocs.ScalarTrackingFunctional>` and min-max terms via :py:class:`MinMaxFunctional <cashocs.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 :bash:`-ksp_view`) have a value of :python:`None` in the dictionary (so :python:`'ksp_view': None` can be used inside the dictionary to supply the aforementioned option).

* cashocs now includes a :py:func:`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 :python:`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 :py:func:`cashocs.convert`, which are :python:`"physical"`, :python:`"geometrical"`, and :python:`"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

* :ini:`maximum_iterations` is now called :ini:`max_iter`

* Section Output

* :ini:`save_pvd` is now called :ini:`save_state`, functionality is the same

* :ini:`save_pvd_adjoint` is now called :ini:`save_adjoint`, functionality is the same

* :ini:`save_pvd_gradient` is now called :ini:`save_gradient`, functionality is the same

* Section LineSearch

* The parameters :ini:`initial_stepsize`, :ini:`epsilon_armijo`, :ini:`beta_armijo`, and :ini:`safeguard_stepsize` are moved from the OptimizationRoutine section to the LineSearch section. Their behavior is unaltered.

* New configuration file parameters

* Section AlgoLBFGS

* :ini:`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

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

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

* :ini:`method` is a string parameter, which can take the values :ini:`method = armijo` (which is the default previous line search) and :ini:`method = polynomial` (which are the new models)

* :ini:`polynomial_model` is a string parameter which can be either :ini:`polynomial_model = quadratic` or :ini:`polynomial_model = cubic`. In case this is :ini:`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 :ini:`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.

* :ini:`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)

* :ini:`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

* :ini:`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.