# Release notes

## v0.10.0

Since the 0.9.0 release, there has been 311 merged pull requests from 25 contributors. Below follows a summary of the biggest changes to the Python-API from these pull requests. In addition to the changes below, the ever-lasting quest of improving performance and squasing bugs continues.

### PETSc API

Authors: Jørgen S. Dokken, Francesco Ballarin, Jack Hale and Garth N. Wells

Mapping data between `PETSc.Vec<petsc4py.PETSc.Vec` and `dolfinx.fem.Function`s is now trivial for blocked problems by using `dolfinx.fem.petsc.assign()`.

Both solvers and assembly routines interfacing with PETSc has recieved a drastic make-over to improve useability and maintenance, both for developers and end-users

#### Improved non-linear (Newton) solver

The FEniCS project has for the last 15 years had its own implementation of a Netwon solver. We no longer see the need of providing this solver, as the `PETSc SNES` solver, and equivalent solver for C++ provides more features than our own implementation.

The previously shipped `dolfinx.nls.petsc.NewtonSolver` is deprecated, in favor of `dolfinx.fem.petsc.NonlinearProblem`, which now integrates directly with `petsc4py.PETSc.SNES`.

The non-linear problem object that was sent into `dolfinx.nls.petsc.NewtonSolver` has been renamed to `NewtonSolverNonlinearProblem` and is also deprecated.

The new `NonlinearProblem` has additional support for blocked systems, such as `NEST` by supplying `kind="nest"` to its intializer. See the documentation for further information.

#### Improved `dolfinx.fem.petsc.LinearProblem`

- The `dolfinx.fem.petsc.LinearProblem` now support blocked problems, either specified manually or by using `ufl.extract_blocks()`. By changing the input-argument `kind`, the user can now decide if they want to use the DOLFINx blocked PETSc implementation (`kind="mpi"`) or the `kind=``"nest"`.

- The default behavior for non-blocked systems remains the same as before.

- The users can now also specify a (blocked) form for preconditioning through the `P` keyword argument in the constructor.

#### Assembly routines

In earlier versions of DOLFINx, there were three assembly routines for `PETSc.Vec` and `PETSc.Mat`:

- `assemble_*`

- `assemble_*_block`

- `assemble_*_nest`

This caused alot of duplicate logic in codes. Therefore, we have unified all these assembly routines under `dolfinx.fem.petsc.assemble_vector()` and `dolfinx.fem.petsc.assemble_matrix()`. The input keyword argument `kind` selects the relevant assembler routine. See for instance the Stokes demo for a detailed introduction. Similar changes has been done to `dolfinx.fem.petsc.apply_lifting()`.

#### Linear algebra submodule

There is now a sub-module (`dolfinx.la.petsc`) containing PETSc LA operations.

#### Interpolation

The `dolfinx.fem.discrete_curl()` operator has been added to DOLFINx, to cater to Hypre Auxiliary-space Divergence Solver

- A `petsc4py.PETSc.Mat` equivalent can be found under `dolfinx.fem.petsc.discrete_curl()`.

### Simplified demos

#### Usage of `ufl.MixedFunctionSpace` and `ufl.extract_blocks()`

Authors: Jørgen S. Dokken and Joe Dean

Initially introduced as part of the v0.9.0-release, usage of these two UFL-abstractions hasve been propagated into the demos, to make it even easier for users to see examples of how to work with blocked problems.

TODO: Add profiling of blocked/mixed-element vs mixedfunction-space.

#### Usage of `ufl.ZeroBaseForm`

Author: Garth N. Wells For a long time, it has not been possible to specify the right hand side of a linear PDE as empty. This means that users often have had to resolve to adding `dolfinx.fem.Constant(mesh, 0.0)*v*ufl.dx` to ensure that one can use the dolfinx form compilation functions. With the introduction of `ufl.ZeroBaseForm` this is no longer required. The aforementioned workaround can now be reduced to `ufl.ZeroBaseForm((v, ))`, which avoid extra assembly calls within DOLFINx.

### Form compiler and integral types

Author: Susanne Claus, Paul T. Kühner, and Jørgen S. Dokken

- The tabulation kernels now have an extra input, a `void*`, to make it possible to pass custom data for custom kernels.

- New `dolfinx.fem.IntegralType` support

  - Vertex integrals: `ufl.dP`

  - Ridge integrals (codim=2); `uf.dr`

- One can now assemble the diagonal of a bilinear form into a vector by adding `form_compiler_options={"part":"diagonal"}` when calling `dolfinx.fem.form()`. Instead of calling `dolfinx.fem.petsc.assemble_matrix()` one should now call `dolfinx.fem.petsc.assemble_vector()`. This is useful for matrix-free solvers with Jacobi smoothing.

### Mesh

Authors: Paul T. Kühner, Joe Dean, Garth N. Wells, Jørgen S. Dokken and Chris Richardson

- Uniform mesh refinement of all `CellTypes` is available through `dolfinx.mesh.uniform_refine()`.

- Branching meshes (a mesh where a single facet is connected to more than two cells), such as T-joints (3 cells connected to a single facet) are now supported as input meshes to DOLFINx. To ensure proper partitioning in parallel, one should change the default option `max_facet_to_cell_links` to how many cells a facet can be attached to in `dolfinx.io.XDMFFile.read_mesh()`, `dolfinx.io.vtkhd.read_mesh()` and `dolfinx.mesh.create_mesh()`.

- One can no longer use `set_connectivity` or `set_index_map` to modify `dolfinx.mesh.Topology` objects. Any connectivity that is not `(tdim, 0)`, (`tdim`, `tdim`) or `(0, 0)` should be created with `dolfinx.mesh.Topology.create_connectivity()`. The aforementioned connections should be attached to the topology when calling `dolfinx.cpp.mesh.create_topology()`.

- Mixed-dimensional support has been vastly improved by creating `dolfinx.mesh.EntityMap`, which replaces the numpy arrays used as `entity_maps` in `dolfinx.fem.form()` in the previous release. This is a two-way map, meaning that the user no longer has to take care of creating the correct mapping. The two-way map from a sub-mesh to a parent mesh is returned as part of `dolfinx.mesh.create_submesh()`.

### Linear Algebra

Authors: Chris Richardson

The native `matrix-format` now has a sparse matrix-vector multiplication `dolfinx.la.MatrixCSR.mult()`. Note that the `dolfinx.la.Vector` that you multiply with should use the `dolfinx.la.MatrixCSR.index_map(1)` rather than the one stemming from the `dolfinx.fem.FunctionSpace.dofmap.index_map`.

### Collision detection

Author: Chris Richardson The collision detection algorithm `dolfinx.geometry.compute_distance_gjk()` now used multiprecision to ensure proper collision detection. The algorithm has also been improve to work on co-planar convex hulls.

### Documentation

Authors: Paul T. Kühner, Garth N. Wells, Mehdi Slimani and Jørgen S. Dokken

- Several classes that have only been exposed through the nanobind/C++interface have gotten proper Python classes and functions. This includes:

  - `dolfinx.graph.AdjacencyList`

  - `dolfinx.fem.FiniteElement`

  - `dolfinx.geometry.determine_point_ownership()`

- Tons of typos, formatting fixes and improvements have been made.

- Usage of intersphinx and sphinx-codeautolink to make the documentation more interactive. Most classes, functions and methods in any demo on the webpage can now redirect you to the relevant package API.

### Revised timer logic

Authors: Garth N. Wells and Paul T. Kühner

Instead of using the Boost timer library, we have opted for the standard timing library std::chrono. The switch is mainly due to some observed unaccuracies in timings with Boost. This removes the notion of wall, system and user time. See or `Timer` for examples of usage.

### IO

#### GMSH

Authors: Paul T. Kühner, Jørgen S. Dokken, Henrik N.T. Finsberg and Pierric Mora

The GMSH interface to DOLFINx has received a major upgrade.

- An API-breaking change is that the module `dolfinx.io.gmshio` has been renamed to `dolfinx.io.gmsh`.

- Another API-breaking change is the return type of `dolfinx.io.gmshio.model_to_mesh()` and `dolfinx.io.read_from_msh()`. Instead of returning the `dolfinx.mesh.Mesh`, cell and facet `dolfinx.mesh.MeshTags`, it now returns a `dolfinx.io.gmsh.MeshData` data-class, that can contain `dolfinx.mesh.MeshTags` of an sub-entity:

  - Cell (codim 0)

  - Facet (codim 1)

  - Ridge (codim 2)

  - Peak (codim 3)

- Additional checks and error handing for `Physical` tags from GMSH has been added to improve the user experience.

#### VTKHDF5

Authors: Chris Richardson and Jørgen S. Dokken

As Kitware has stated that VTKHDF is the future format they want to support, we have started the transistion to this format. Currently, the following features have been implemented:

- Reading meshes: `dolfinx.io.vtkhdf.read_mesh()`. Supports mixed topology.

- Writing meshes: `dolfinx.io.vtkhdf.write_mesh()`. Supports mixed topology.

- Writing point data `dolfinx.io.vtkhdf.write_point_data()`. The point data should have the same ordering as the geometry nodes of the mesh.

- Writing cell data `dolfinx.io.vtkhdf.write_cell_data()`.

#### VTXWriter

Authors: Mehdi Slimani and Jørgen S. Dokken

The writer does now support time-dependent DG-0 data, which can be written in the same file as a set of functions from another (unique) function space.

#### XDMF

Author: Massimilliano Leoni and Paul T. Kühner

- When using `dolfinx.io.XDMFFIle.read_meshtags()` one can now specify the attribute name, if the grid has multiple tags assigned to it.

- Flushing data to file is now possible with `dolfinx.io.XDMFFile.flush()`. This is useful when wanting to visualize long-running jobs in Paraview.

#### Remove Fides backend

As we unfortunately haven’t seen an expanding set of features for the Fides Reader in Paraview, we have decided to remove it from DOLFINx.

#### Pyvista

Pyvista no longer requires `pyvista.start_xvfb()` if one has installed `vtk` with OSMesa support.