Felupe

Added
- Add methods to evaluate different strain measures of a field container, i.e. `FieldContainer.evaluate.strain(tensor=True, asvoigt=False, k=0)`, `FieldContainer.evaluate.log_strain(tensor=True, asvoigt=False)` or `FieldContainer.evaluate.green_lagrange_strain(tensor=True, asvoigt=False)`. These methods refer to `math.strain(k=0)` which uses `math.strain_stretch_1d(k=0)` by default with the strain exponent `k` of the Seth-Hill strain formulation.

Changed
- Change the return type of `math.eig()` which returns a namedtuple with attributes `eigenvalues` and `eigenvectors`. Now consistent with NumPy. This also affects `math.eigh()`.
- Change the shape of the array of eigenvectors returned by `math.eig()` from `(a, i, ...)` to `(i, a, ...)`. Now consistent with NumPy. This also affects `math.eigh()`.
- Switch from a hard-coded logarithmic strain evaluation to a more generalized Seth-Hill strain-stretch relation in `math.strain(fun=math.strain_stretch_1d, k=0)` with a default strain-exponent of `k=0` which returns the logarithmic strain.

Added
- Add an argument to disable the (default) expansion of the points-array of a mesh in `mesh.expand(expand_dim=True)` and `mesh.revolve(expand_dim=True)`. E.g., this allows the expansion and / or revolution of a quad-mesh with points in 3d-space.
- Add `MultiPointContact.plot(offset=0, **kwargs)` to plot the rigid contact plane(s) or line(s) at a given offset.
- Add `MultiPointConstraint.plot(**kwargs)` to plot the lines of a multi-point constraint.

Changed
- Don't raise an error if the total angle of revolution is greater than 360 degree in `mesh.revolve(phi=361)`.

Added
- Add axis of expansion in `mesh.expand(axis=-1)` (ignored for `n=1`).
- Add an optional mask-argument to select points for rotation in `mesh.rotate(mask=None)`.
- Add Lagrange quad/hex cell-types in `ViewMesh`.
- Add optional projection of stresses from quadrature-points to mesh.points in `SolidBody.plot(project=None)`, where `project` has to be a callable like `project(values, region)`.
- Add optional projection of internel cell-data (Displacement, Logarithmic Strain and Deformation Gradient) from quadrature-points to mesh-points in `FieldContainer.plot(project=None)`, where `project` has to be a callable like `project(values, region)`.

Changed
- The internal `BasisField.basis` is now a subclassed array `BasisArray` with a `grad`-attribute.
- `math.grad(x, **kwargs)` is enhanced to return gradients of fields (like before) and the gradient-attribute of basis-arrays (added).
- The `grad_v` and `grad_u` arguments are removed from the form-expression decorator `Form`. This changes the required function signature of the weakform-callable to `weakform(v, u, **kwargs)`. The tuple of optional arguments is also removed. Gradients of `v` and `u` are now obtained by `math.grad(v)` or `v.grad`.
- Enforce quadrature schemes with minimal order for projections in `project()` for `Triangle`, `Tetra` as well as their MINI- and Quadratic-variants.
- Fall-back to `extrapolate(mean=True)` in `project(mean=True)`.
- Don't ravel the results of `res = extrapolate(values, region)`, i.e. `values.shape = (3, 3, 4, 100)` will be returned as `res.shape = (121, 3, 3)` instead of `res.shape = (121, 9)`.
- Stack only a selection of meshes in `MeshContainer.stack([idx])`.
- Enable list-based indexing in `MeshContainer[idx]`.
- Add the `opacity=0.99` argument to `MeshContainer.plot()` and `MeshContainer.screenshot()`.
- Pass the dpi-argument to the matplotlib figure in `imshow(dpi=None)` for solids, field- and mesh-containers.
- Permute `GaussLegendre(order=2, dim=2)` according to the points of the `BiQuadraticQuad` element by default.
- Permute the 2- and 3-dimensional `GaussLegendre` quadrature schemes for order > 2 according to the VTK-Lagrange element formulations. That means for linear and quadratic quads and hexahedrons, the points of `GaussLegendre` are sorted according to the default VTK elements and for all higher-order elements according to the Lagrange-elements.
- Enable default point-permutations in `RegionLagrange(permute=True)` by default.
- Hide internal edges of higher-order cell-types in `ViewScene.plot()` by default.
- Simplify `tools.topoints(values, region, average=True, mean=False)`. Remove all other arguments. If values of single quadrature-point per cells is given, then the values are broadcasted to the number of points-per-cell. If values are provided on more quadrature points than the number of points-per-cell, then the values are trimmed. E.g., this is required for `QuadraticHexahedron` with 20 points and 27 quadrature-points.

Fixed
- Fix mesh-expansion with one layer `mesh.expand(n=1)`. This expands the dimension of the points-array.
- Fix VTK-compatible cells in `CubeArbitraryOrderHexahedron`.
- Fix Cauchy-stress evaluation of `SolidBody` and `SolidBodyNearlyIncompressible` on a 2d-Field (plane stress): Automatic fall-back to Kirchhoff-stress and print a warning.

Removed
- Remove the deprecated old-style argument `move` in `dof.biaxial()`.
- Remove the deprecated old-style arguments `move`, `axis_compression`, `axis_shear` and `compression` in `dof.shear()`.

Fixed
- Fix `tools.project()` for meshes where some points are not connected to cells.

Added
- Add `FieldDual(disconnect=True)` for a dual (secondary) field with an optionally disconnected mesh. This also enables `FieldsMixed(disconnect=True)` in mixed fields.
- Add a quadrature scheme for integrating the surface of a unit hemisphere `BazantOh(n=21)`.
- Add `NearlyIncompressible` as a simplified version of `ThreeFieldVariation`. A constitutive material formulation on the distortional part of a strain energy function in terms of the deformation gradient has to be provided, e.g. by `umat = NearlyIncompressible(NeoHooke(mu=1), bulk=5000)`.
- Add optional kwargs to a job-callback `Job(callback=lambda stepnumber, substepnumber, substep, **kwargs: None, **kwargs)` and `CharacteristicCurve(callback=lambda stepnumber, substepnumber, substep, **kwargs: None, **kwargs)`.
- Add `DiscreteGeometry` properties `x`, `y` and `z` to access the columns of the points-array.
- Add a new math-function `math.equivalent_von_mises(A)` for three-dimensional second-order tensors.
- Add the evaluation of the equivalent von Mises Cauchy stress as cell-data in `ViewSolid`, available as `Solid.plot("Equivalent of Cauchy Stress")`.
- Add `mesh.stack(meshes)` as method to `MeshContainer.stack()`. Note that this only supports mesh containers with meshes of same cell-types.
- Add `NeoHooke.gradient(out=None)` and `NeoHooke.hessian(out=None)` for a location to store the results. Also for `NeoHookeCompressible`.
- Add `out`-keyword to `gradient()` and `hessian` of `NearlyIncompressible` and `ThreeFieldVariation`.
- Add optional initial state variables in `ViewMaterial(statevars=None)` and `ViewMaterialIncompressible(statevars=None)`.
- Add the L2-projection as `tools.project(values, region, average=True, mean=False, dV=None, solver=scipy.sparse.linalg.spsolve)` to project given values at quadrature points to mesh-points. This replaces the old `tools.project(values, region, average=True, mean=False)` in a backward-compatible way. The new method is computationally more expensive but is also much more flexible.
- Add fifth-order quadrature schemes `quadrature.Triangle(order=5)` and `quadrature.Tetrahedron(order=5)`.
- Add `Region.copy(mesh=None, element=None, quadrature=None)` to copy a region and re-evaluate this copy if necessary.

Changed
- Rename `Mesh.save()` to `Mesh.write()` and add `Mesh.save()` as an alias to `Mesh.write()`.
- Enhance the performance of `NeoHooke`, `NeoHookeCompressible`, `SolidBody` and `SolidBodyNearlyIncompressible`.
- Enhance the performance of `math.inv(out=None)` and `math.det(out=None)`.
- Use only the offical API of `tensortrax`. A workaround is used to ensure compatibility with `tensortrax` <= v0.17.1.
- Pass optional keyword-arguments in the plot-methods `ViewMaterial.plot(**kwargs)` and `ViewMaterialIncompressible.plot(**kwargs)` to the matplotlib axes object `ax.plot(**kwargs)`.
- Only add `off_screen` and `notebook` keyword-arguments to `pyvista.Plotter(**kwargs)` if they are `True`. This is needed for not ignoring a global variable like `pyvista.OFF_SCREEN = True`.
- Enforce `verbose=0` if the environmental variable `"FELUPE_VERBOSE"` is `"false"`. This is useful for running the examples when building the documentation.
- Don't require a `bilinearform` in `FormItem(bilinearform=None)`. An empty `FormItem` is now a valid item in a `Step`. For empty vectors/matrices, the shape is inferred from `sum(FieldContainer.fieldsizes)` instead of `FieldContainer.fields[0].values.size`.
- Rename the old-project method to `tools.extrapolate(values, region, average=True, mean=False)` which extrapolates values at quadrature points to mesh-points.
- Change the sorting of quadrature points for triangles and tetrahedrons (due to internal code simplifications).
- The reload-method of a region does only re-evaluate it if at least one of the arguments are not None `Region.reload(mesh, element, quadrature)`.

Fixed
- Fix missing support for third-order- and second-order tensor combinations to `math.dot(A, B, mode=(2,3))` and `math.ddot(A, B, mode=(2,3))`.
- Fix error if `FieldDual` is in the fields of a `FieldContainer` for `IntegralForm`.
- Fix `math.inv(A)` for arrays with shape `A.shape = (1, 1, ...)`. Also raise an error if `shape[:2]` not in `[(3, 3), (2, 2), (1, 1)]`.
- Raise an error in `math.det(A)` if `A.shape[:2]` not in `[(3, 3), (2, 2), (1, 1)]`.
- Fix mutable keyword-arguments in `SolidBody._vector(kwargs={})` by `SolidBody._vector(kwargs=None)`. Also for `._matrix()` and for `SolidBodyNearlyIncompressible`.
- Fix wrong shape and the resulting error during assembly in `fem.assembly.expression.Form` for the integration of a linear form with different mesh- and field-dimensions.

Added
- Create a `FieldContainer` by the `&`-operator between fields and field containers, i.e. `field = displacement & pressure`, where `displacement = Field(region, dim=2)` and `pressure = Field(region)`. This also works for `field & pressure` as well as `pressure & field`.
- Add a method to create a field container from a field, i.e. `Field(region, dim=3).as_container()` is equal to `FieldContainer([Field(region, dim=3)])`.
- Add `ViewMaterial(umat)` to view force-stretch curves for uniaxial tension/compression, planar shear and equi-biaxial tension.
- Add `ViewMaterialIncompressible(umat)` to view force-stretch curves for incompressible uniaxial tension/compression, planar shear and equi-biaxial tension.
- Add a base class for constitutive materials with methods `ConstitutiveMaterial.view(incompressible=False)`, `ConstitutiveMaterial.plot(incompressible=False)` and `ConstitutiveMaterial.screenshot(incompressible=False)`.
- Add a dict-attribute with material parameters to all built-in materials, e.g. `NeoHooke.kwargs = {"mu": self.mu, "bulk": self.bulk}`.
- Add `umat = CompositeMaterial(material, other_material)`.
- Add `&`-operator to combine constitutive materials `umat = material & other_material`. Note that only the first material must contain state variables.

Changed
- Don't disconnect the dual mesh by default for regions `RegionQuadraticTriangle` and `RegionQuadraticTetra` in `FieldsMixed`.

Fixed
- Fix `Mesh.flip(mask=None)`: Take care of the mask (it wasn't applied to the cells-array of the mesh).