Add support for facet orientation in FacetBasis (#865)

* Add workaround for default file format change in meshio 5.3.0

* Add skfem.generic_utils.OrientedBoundary

* Add Mesh.facets_around for constructing OrientedBoundary

* Rename BoundaryFacetBasis to FacetBasis and alias vice versa

* Add example meshes with oriented interfaces

* Support giving lambda AND index sets in with_boundaries

* Fix the broken subdomain assembly with tags

* Fix interpolation with multiple components

* Allow specifying normal in Mesh.facets_satisfying

* Support loading OrientedBoundary in Mesh.load from Gmsh format

README.md

@@ -216,20 +216,44 @@ with respect to documented and/or tested features.
 ### Unreleased
 
 - Changed: `DiscreteField` is now a subclass of `ndarray` instead of
-  `NamedTuple`
+  `NamedTuple` and, consequently, the components of `DiscreteField` cannot no
+  more be indexed inside forms like `u[1]` (use `u.grad` instead)
 - Changed: Writing `w['u']` and `w.u` inside the form definition is now
   equivalent (previously `w.u == w['u'].value`)
-- Changed: `Mesh.draw` now uses `matplotlib` by default, call
-  `Mesh.draw("vedo")` to keep using `vedo`
+- Changed: `Mesh.draw` now uses `matplotlib` by default, calling
+  `Mesh.draw("vedo")` uses `vedo`
 - Changed: `skfem.visuals.matplotlib` now uses `jet` as the default colormap
+- Changed: `BoundaryFacetBasis` is now an alias of `FacetBasis` instead of
+  other way around
 - Deprecated: `DiscreteField.value` remains for backwards-compatibility but is
   now deprecated and can be dropped
 - Added: `Mesh.plot`, a wrapper to `skfem.visuals.*.plot`
 - Added: `Basis.plot`, a wrapper to `skfem.visuals.*.plot`
 - Added: `Basis.refinterp` now supports vectorial fields
-- Added: `skfem.visuals.matpltlib.plot` now has a basic quiver plot for vector
+- Added: `skfem.visuals.matplotlib.plot` now has a basic quiver plot for vector
   fields
-- Fixed: Improvements to backwards compatibility in `asm`/`assemble` kwargs
+- Added: `Mesh.facets_around` which constructs a set of facets around a
+  subdomain
+- Added: `Mesh.load` now tries loading the orientation of boundaries and
+  interfaces
+- Added: `OrientedBoundary` which is a subclass of `ndarray` for facet index
+  arrays with the orientation information (0 or 1 per facet) available as
+  `OrientedBoundary.ori`
+- Added: `FacetBasis` will use the facet orientations (if present) to calculate
+  traces and normal vectors
+- Added: `skfem.visuals.matplotlib.draw` will visualize the orientations if
+  `boundaries=True` is given
+- Added: `Mesh.facets_satisfying` allows specifying the keyword argument
+  `normal` for orienting the resulting interface
+- Added: `FacetBasis` constructor now has the keyword argument `side` which
+  allows changing the side of the facet used to calculate the basis function
+  values and gradients
+- Fixed: Improvements to backwards compatibility in `asm`/`assemble` keyword
+  arguments
+- Fixed: Save format issue with meshio 5.3.0+
+- Fixed: `CellBasis` did not properly support `elements` argument
+- Fixed: `Basis.interpolate` did not properly interpolate all components of
+  `ElementComposite`
 
 ### [5.2.0] - 2021-12-27
 

docs/advanced.rst

@@ -65,7 +65,7 @@ This can be written as
 
 In addition, forms can depend on the local mesh parameter ``w.h`` or other
 finite element functions (see :ref:`predefined`).  Moreover, boundary forms
-assembled using :class:`~skfem.assembly.BoundaryFacetBasis` can depend on the
+assembled using :class:`~skfem.assembly.FacetBasis` can depend on the
 outward normal vector ``w.n``.  One example is the form
 
 .. math::

docs/api.rst

@@ -90,12 +90,12 @@ Class: CellBasis
    :members: __init__, interpolate, project
 
 
-Class: BoundaryFacetBasis
-*************************
-
-.. autoclass:: skfem.assembly.FacetBasis
+Class: FacetBasis
+*****************
 
 .. autoclass:: skfem.assembly.BoundaryFacetBasis
+
+.. autoclass:: skfem.assembly.FacetBasis
    :members: __init__
 
 Class: InteriorFacetBasis