Cashocs

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

* 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 :python:`_utils` module has been removed. Now, KSP objects can be interfaced only directly via :python:`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

* :ini:`safeguard_stepsize` is a boolean parameter which dis-/enables the guard against poor scaling for the initial iteration

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

* 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 :bash:`mpirun -n p python script.py`, where :bash:`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.

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

* 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 :py:meth:`inject_pre_callback <cashocs.optimization_problem.OptimizationProblem.inject_pre_callback>` and :py:meth:`inject_post_callback <cashocs.optimization_problem.OptimizationProblem.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 :py:class:`cashocs.IntegralFunctional`, :py:class:`cashocs.ScalarTrackingFunctional` and :py:class:`cashocs.MinMaxFunctional`. These allow for a clearer definition of cost functionals and will replace the keyword arguments :python:`scalar_tracking_forms` and :python:`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 :python:`utils` submodule is now private. Added a new :py:mod:`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

* :ini:`gradient_method` is either :ini:`gradient_method = direct` or :ini:`gradient_method = iterative` and specifies that the corresponding type of solver is used to compute the gradient.

* :ini:`gradient_tol` specifies the tolerance which is used in case an iterative solver is used to compute the (shape) gradient.

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

* 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., :python:`dx('part1')` or :python:`ds('inlet')`, or for creating Dirichlet boundary conditions (e.g. :python:`cashocs.create_dirichlet_bcs(V, Constant(0.0), boundaries, 'dirichlet_boundary')`).

* The nonlinear solver (Newton's method) got an additional :python:`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 :python:`dF`.

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

* New configuration file parameters:

* Section ShapeGradient

* :ini:`use_p_laplacian` is a boolean flag which enables the use of the p-Laplacian for the computation of the shape gradient

* :ini:`p_laplacian_power` is an integer parameter specifying the power p used for the p-Laplacian

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

* :ini:`update_inhomogeneous` is a boolean parameter, which allows to update the cell volume when using :ini:`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 :ini:`update_inhomogeneous = False`

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

* 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 :python:`scalar_tracking_forms`, which is a dictionary consisting of :python:`'integrand'`, which is the integrand of the scalar quantity, and :python:`'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

* :ini:`use_distance_mu` is a boolean flag which enables stiffness computation based on distances

* :ini:`dist_min` and :ini:`dist_max` describe the minimal and maximum distance to the boundary for which a certain stiffness is used (see below)

* :ini:`mu_min` and :ini:`mu_max` describe the stiffness values: If the boundary distance is smaller than :ini:`dist_min`, then :python:`mu = mu_min` and if the distance is larger than :ini:`dist_max`, we have :python:`mu = mu_max`

* :ini:`smooth_mu` is a boolean flag, which determines how :python:`mu` is interpolated between :ini:`dist_min` and :ini:`dist_max`: If this is set to `False`, linear interpolation is used, otherwise, a cubic spline is used

* :ini:`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 :python:`os.system()` calls by :python:`subprocess.run()`

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

* Improved the remeshing workflow and fixed several smaller bugs concerning it

* New configuration file parameters:

* Section Output

* :ini:`save_pvd_adjoint` is a boolean flag which allows users to also save adjoint states in paraview format

* :ini:`save_pvd_gradient` is a boolean flag which allows users to save the (shape) gradient(s) in paraview format

* :ini:`save_txt` is a boolean flag, which allows users to capture the command line output as .txt file