Felupe

Added
- Add `SolidBody.assemble.mass(density=1.0)` and `SolidBodyNearlyIncompressible.assemble.mass(density=1.0)` to assemble the mass matrix.
- Add `SolidBody.evaluate.stress(field)` to evaluate the (first Piola-Kirchhoff) stress tensor (engineering stress in linear elasticity).
- Add a free-vibration modal analysis Step/Job `FreeVibration(items, boundaries)` with methods to evaluate `FreeVibration.evaluate()` and to extract `field, frequency = FreeVibration.extract(n)` its n-th result.
- Add `Boundary.plot()` to plot the points and prescribed directions of a boundary.
- Add `BoundaryDict` as a subclassed dict with methods to `plot()`, `screenshot()` and `imshow()`.
- Add a new argument to apply a callable on the assembled vector/matrix of a solid body, `SolidBody(..., apply=None)`. This may be used to sum the list of sub-blocks instead of stacking them together, `SolidBody(..., block=False, apply=None)`. This is useful for mixed formulations where both the deformation gradient and the displacement values are required.
- Add support for non-symmetric bilinear mixed forms in `IntegralForm`.
- Add `element.Element` to the top-level package namespace.
- Raise a TypeError if a mesh container is used as the `mesh`-argument in a region. The error message explains that the container is not supported. A mesh must be used instead.
- Add the `Vertex` element formulation.
- Add a vertex-region `RegionVertex`.
- Add `MeshContainer.as_vertex_mesh()` to create a merged vertex mesh from the meshes of the mesh container.
- Add `Field.from_mesh_container(container)` to create a top-level field on a vertex mesh.
- Add `GaussLobatto` quadrature. The order-argument is equal to the 1d-sample points minus two. This ensures identical minimum order-arguments for Gauss-Legendre and Gauss-Lobatto schemes.

Changed
- The first Piola-Kirchhoff stress tensor is evaluated if `ViewSolid(stress_type=None)`.
- Autodetect the stress-type in `SolidBody.plot(name)` from `name`.
- Enhance the `hello_world(axisymmetric=False, planestrain=False, curve=False, xdmf=False, container=False)` function with new arguments to customize the generated template script.
- Enhance `Boundary` with added support for multiaxial prescribed values.
- Enhance `math.linsteps(..., values=0)` with default values except for the column `axis` if `axis` is not None.
- Link all field-values to the values of the first field if no other field is given in `FieldContainer.link()`.
- Change the default arguments from `block=True` to `block=None` in `SolidBody.assemble.vector(block=None)` and `SolidBody.assemble.matrix(block=None)` and define `block` on creation, `SolidBody(..., block=True)` instead.
- Integrate and assemble `None`-items in the `fun`-argument of `IntegralForm`. On integration, `None` is returned. `None` will be assembled to an emtpy sparse matrix.
- Enhance `mesh.interpolate_line(mesh, xi, axis=None, ...)` which by default uses a curve-progress variable when `axis=None`. The curve progress evaluation points `xi` must be within `0 <= xi <= 1`.

Fixed
- Fix `Boundary(..., mode="and")` by ignoring any undefined axis.
- Fix `tools.hello_world(planestrain=True)` with the correct region `RegionQuad` for the plane-strain template.
- Fix the cells-array in `RegionQuadraticQuadBoundary` for midpoints of edges.
- Fix `FieldContainer.plot()` for regions without the shape-function gradients available.

Removed
- Remove the unused `shape`-argument in `element.Element(shape)`. Adopt the arbitrary-lagrange element to use its own `dim`-argument. This simplifies the creation of custom finite element formulations.

Added
- Add the hessian of the element shape functions for a quadratic quad element `QuadraticQuad.hessian()`.
- Add the `order`-argument to `FieldContainer.extract(order="C")` as well as for `Field`, `FieldAxisymmetric`, `FieldPlaneStrain` to return C-contiguous arrays by default.
- Add an optional multiplier to `Laplace(multiplier=1.0)`.
- Add optional keyword-arguments to `math.transpose(**kwargs)` to support optional `out` and `order`-keywords.
- Add the attribute `RegionBoundary.tangents`, which contains a list of tangent unit vectors. For `quad` cell-types the length of this list is one and for `hexahedron` cell-types it is of length two.
- Add `math.inplane(A, vectors)` to return the in-plane components of a symmetric tensor `A`, where the plane is defined by its standard unit vectors.
- Add `constitution.jax.Hyperelastic` as a feature-equivalent alternative to `Hyperelastic` with `jax` as backend.
- Add `constitution.jax.Material(..., jacobian=None)` with JAX as backend. A custom jacobian-callable may be passed to switch between forward- and backward-mode automatic differentiation.
- Add material models for JAX-based materials. Hyperelastic models available at `constitution.jax.models.hyperelastic`: `extended_tube()`, `miehe_goektepe_lulei()`, `mooney_rivlin()`, `neo_hooke()`, `yeoh()`, `third_order_deformation()`, `van_der_waals()`. Lagrange (stress-based) models available at `constitution.jax.models.lagrange`: `morph()`, `morph_representative_directions()`.
- Add `constitution.jax.total_lagrange()`, `constitution.jax.updated_lagrange()` and `constitution.jax.isochoric_volumetric_split()` function decorators for the JAX hyperelastic material class.
- Add an optional keyword-argument `Region.astype(copy=True)` to modify the data types of the arrays of the region in-place if `copy=False`.
- Add `FieldContainer.evaluate.right_cauchy_green_deformation()` and `math.right_cauchy_green_deformation(field)` to evaluate the right Cauchy-Green deformation tensor.
- Add `math.strain(field, C=None, ..., **kwargs)` to use a given right Cauchy-Green deformation tensor for the evaluation of the strain tensor.
- Add the hyperelastic foam models `storakers()` and `blatz_ko()` for both AD-backends.
- Add the `saint_venant_kirchhoff_orthotropic()` hyperelastic model (tensortrax).

Changed
- Change default `np.einsum(..., order="K")` to `np.einsum(..., order="C")` in the methods of `Field`, `FieldAxisymmetric`, `FieldPlaneStrain` and `FieldContainer`.
- Change supported Python versions to 3.9 - 3.12.
- Change the `dtype`-argument in `Region.astype(dtype)` from an optional to a required argument.
- Make `tensortrax` an optional dependency (again). Now FElupe does only depend on NumPy and SciPy, all other extras are optional.

Fixed
- Fix the number of points for non-disconnected dual meshes. This reduces the assembled (sparse) vector- and matrix-shapes, which are defined on mixed-fields.
- Fix wrong results of `ConstitutiveMaterial.plot()` if any stretch is non-physical, i.e. lower or equal zero. This raises an error now.

Removed
- Remove the unused, deprecated aliases `UserMaterial`, `UserMaterialStrain` and `UserMaterialHyperelastic`.

Added
- Add `Region.astype(dtype=None)` to copy and cast the region arrays to a specified type.
- Add `Field(..., dtype=None)` to cast the array with field values to a specified type.
- Add `Field.extract(dtype=None)` to cast the extracted field gradient/interpolated values to a specified type.
- Add `hello_world()` to print the lines of a minimal-working-example to the console.
- Add `mesh.interpolate_line(mesh, xi, axis)` to interpolate a line mesh. The attribute `points_derivative` holds the derivatives of the independent variable w.r.t. the dependent variable(s). The column of the independent variable is filled with zeros.
- Add optional keyword-argument `SolidBody.assemble.matrix(block=True)`, also for `SolidBody.assemble.vector(block=True)` and the assemble-methods of `SolidBodyNearlyIncompressible`. If `block=False`, these methods will assemble a list of the upper-triangle sub block-vectors/-matrices instead of the combined block-vector/-matrix.
- Add `SolidBodyForce` as a replacement for `SolidBodyGravity` with more general keyword arguments (`"values"` instead of `"gravity"`, `"scale"` instead of `"density"`).
- Add `Laplace` to be used as user-material in a solid body. Works with scalar- and vector-valued fields.
- Add an optional `mechanics.Assemble(..., multiplier=None)` argument which is used in external items like `SolidBodyForce`, `SolidBodyGravity` and `PointLoad` and is applied in `newtonrhapson(items, ...)`.
- Add a new submodule `view` which contains the `View...` classes like `ViewSolid` or `ViewField`, previously located at `tools._plot`.
- Add the `grad`- and `hess`-arguments to the `reload()`- and `copy()`-methods of a `Region`, i.e. `Region.reload(grad=None, hess=None)`.
- Add `LinearElasticOrthotropic`.
- Add `SolidBodyCauchyStress` in addition to `SolidBodyPressure`.
- Add `mesh.cell_types()` which returns an object-array with cell-type mappings for FElupe and PyVista.
- Add `MeshContainer.from_unstructured_grid(grid, dim=None, **kwargs)` to create a mesh-container from an unstructured grid (PyVista).

Changed
- Change the internal initialization of `field = Field(region, values=1, dtype=None)` values from `field.values = np.ones(shape) * values` to `field = np.full(shape, fill_value=values, dtype=dtype)`. This enforces `field = Field(region, values=1)` to return the gradient array with data-type `int` which was of type `float` before.
- Initialize empty matrices of `SolidBodyForce`, `SolidBodyGravity` and `PointLoad` with `dtype=float`.
- Don't multiply the assembled vectors of `SolidBodyForce`, `SolidBodyGravity` and `PointLoad` by `-1.0`. Instead, `mechanics.Assemble(multiplier=-1.0)` is used in the solid bodies.
- Change the visibility of the internal helpers `mechanics.Assemble`, `mechanics.Evaluate` and `mechanics.Results` from private to public.
- Import the `assembly` module to the global namespace.
- Isolate the submodules, i.e. a submodule only uses the public API of another submodule. If necessary, this will help to change one or more modules to a future extension package.
- Enforce contiguous arrays for the region shape-function and -gradient arrays `h` and `dhdX`. This recovers the integral-form assembly performance from v8.6.0.
- Make the private basis classes public (`assembly.expression.Basis`, `assembly.expression.BasisField` and `assembly.expression.BasisArray`) as especially their docstrings are useful to understand how a *Basis* is created on a field.
- Remove material parameter keyword-arguments in the `function()`-, `gradient()`- and `hessian()`-methods of the core constitutive material formulations. This removes the ability for temporary material parameters in `LinearElastic(E=None, nu=0.3).gradient(x, E=1.0)`, use `LinearElastic(E=1.0, nu=0.3).gradient(x)` instead. This affects the material formulations `LinearElastic`, `LinearElasticPlaneStrain`, `LinearElasticPlaneStress`, `LinearElasticLargeStrain`, `NeoHooke` and `NeoHookeCompressible`. `None` is still supported for the material parameters of `NeoHooke` and `NeoHookeCompressible`.
- Remove `LinearElasticPlaneStrain` from the top-level package namespace because this should only be used with `Field(region, dim=2)`. The preferred method is to use `FieldPlaneStrain(region, dim=2)` and the default `LinearElastic`. `LinearElasticPlaneStrain` remains available in `constitution.LinearElasticPlaneStrain`.
- Rename `Mesh.as_pyvista()` to `Mesh.as_unstructured_grid()` and add `Mesh.as_pyvista()` as alias.

Deprecated
- Deprecate `SolidBodyGravity`, `SolidBodyForce` should be used instead.

Added
- Add `Region(uniform=False)`, a flag to invoke a reduced evaluation of the element shape functions and their gradients. If True, only the first cell is evaluated. This drastically speeds up linear-elasticity on uniform grid meshes (e.g. voxel-like quads and hexahedrons).
- Add an update-method in `FormItem(..., ramp_item=0).update(value)`. This enables a `FormItem` to be used as a ramped-item in a `Step`.

Added
- Add `math.solve_nd(A, b, n=1)` as a generalized function of `math.solve_2d(A, b)` with supported broadcasting on the elementwise-operating trailing axes.

Changed
- Rebase `math.solve_2d(A, b)` on `math.solve_nd(A, b, n=2)` with a batched-rhs supported in NumPy 2.0.
- Change `ogden_roxburgh()` and `OgdenRoxburgh` to use the Gauss error function `erf` instead of `tanh` as internal sigmoid function.
- Flatten the returned `inverse` indices-array of `np.unique(..., return_inverse=True)` in `mesh.merge_duplicate_points()` to ensure compatibility with NumPy 2.0.

Fixes
- Reset state variables in `PlotMaterial.evaluate()` after each completed load case.

Added
- Add the isotropic-hyperelastic `alexander(C1, C2, C2, gamma, k)` material model formulation to be used in `Hyperelastic()`.
- Add the isotropic-hyperelastic Micro-Sphere `miehe_goektepe_lulei(mu, N, U, p, q)` material model formulation to be used in `Hyperelastic()`.
- Add the pseudo-elastic `ogden_roxburgh(r, m, beta, material, **kwargs)` material model formulation to be used in `Hyperelastic()`.
- Add an optional relative-residuals argument to `ConstitutiveMaterial.optimize(relative=False)`.
- Add a class-decorator `constitutive_material(Msterial, name=None)`.
- Add the Total-Lagrange MORPH material formulation implemented by the concept of representative directions `morph_representative_directions(p)` to be used in `MaterialAD()`.
- Add the Total-Lagrange (original) MORPH material formulation `morph(p)` to be used in `Hyperelastic()`.
- Add decorators `total_lagrange` and `updated_lagrange` for Total / Updated Lagrange material formulations to be used in `MaterialAD`.
- Add the isotropic-hyperelastic `anssari_benam_bucchi(mu, N)` material model formulation to be used in `Hyperelastic()`.
- Add the isotropic-hyperelastic `lopez_pamies(mu, alpha)` material model formulation to be used in `Hyperelastic()`.

Changed
- Recfactor the `constitution` module.

Fixed
- Fix plotting the keyword-arguments of a constitutive material `ConstitutiveMaterial.plot(show_kwargs=True)`. For list-based material parameters of length 1, the brackets aren't shown now. E.g., this affects optimized material parameters.
- Don't update the material parameters in-place in `ConstitutiveMaterial.optimize()`.
- Don't convert material parameter scalars to arrays in `ConstitutiveMaterial.optimize()`.