--------------------
* 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.