Shell¶

Initialize the shell FEM problem.

Parameters:

• material (Material | Laminate) –

  Either a single plane-stress Material (homogeneous shell) or a Laminate describing a layered stacking sequence. When a Laminate is passed, thickness and n_simpson are taken from the laminate and the corresponding arguments here are ignored.

• orientation (Tensor | None, default: None ) –

  Global reference direction from which material/ply angles are measured. It is projected onto each element's surface to define the element's local material 0°-axis. Accepts a single (3,) vector (shared by all elements) or a per-element (n_elem, 3) tensor. Defaults to the global x-direction.

Solve the quasi-static finite-element problem by load increments.

Parameters:

• increments (Tensor | None, default: None ) –

  Monotonic load scale factors, typically [0, 1]. Results are always returned at exactly these values. If a Newton solve does not converge, the increment is subdivided internally and retried, and the substep is grown again after each success.

• max_iter (int, default: 10 ) –

  Maximum Newton iterations before an increment is cut back.

• rtol (float, default: 1e-08 ) –

  Relative residual tolerance for Newton convergence.

• atol (float, default: 1e-06 ) –

  Absolute residual tolerance for Newton convergence.

• stol (float, default: 1e-10 ) –

  Tolerance used by iterative linear solvers.

• cutback_factor (float, default: 0.5 ) –

  Factor applied to the substep size after a Newton solve failed to converge.

• growth_factor (float, default: 1.1 ) –

  Factor applied to the substep size after a Newton solve converged, capped at the requested increment.

• max_cutbacks (int, default: 10 ) –

  Number of successive cutbacks accepted within an increment before the solve is given up.

• verbose (bool, default: False ) –

  If True, reports the solver configuration and a table of per-increment progress, updated in place inside notebooks.

• method (Literal['spsolve', 'minres', 'cg', 'pardiso'] | None, default: None ) –

  Linear solver backend name.

• device (str | None, default: None ) –

  Optional device hint for the linear solver backend.

• return_intermediate (bool, default: False ) –

  If True, returns values for all increments.

• aggregate_integration_points (bool, default: True ) –

  If True, averages flux, gradient, and state over integration points.

• use_cached_solve (bool, default: False ) –

  If True, reuses cached linear solver data.

• nlgeom (bool, default: False ) –

  If True, includes geometric nonlinearity.

• alpha (float, default: 0.0 ) –

  Damping factor for viscous stabilization. Dissipated energy is accumulated in self.stabilization_energy.

• differentiable_parameters (Tensor | Iterable[Tensor] | None, default: None ) –

  Explicit parameter(s) to differentiate through implicit Newton/sparse solves. Accepts either a single tensor or an iterable of tensors.

Returns:

• tuple[Tensor, Tensor, Tensor, Tensor, Tensor] –

  Tuple of displacement, internal force, flux, gradient, and material state. If return_intermediate is True, each tensor includes an increment dimension as the leading axis.

Plot the shell mesh with PyVista, optionally with results.

Parameters:

• u (float | Tensor, default: 0.0 ) –

  Nodal displacements added to the positions, e.g. to plot the deformed configuration. Defaults to 0.0 (undeformed).

• node_property (dict[str, Tensor] | None, default: None ) –

  Named nodal fields, e.g. {"u": u[:, :3]}.

• element_property (dict[str, Tensor] | None, default: None ) –

  Named element fields.

• orientations (Tensor | None, default: None ) –

  Per-element direction vectors with shape [n_elem, k, 3] with k <= 3, e.g. the local frames self.t, drawn on the unmirrored mesh as red, green, and blue arrows of the mean element size.

• thickness (bool, default: False ) –

  If True, extrudes elements by their thickness.

• mirror (tuple[bool, bool, bool], default: (False, False, False) ) –

  Mirrors the mesh about the (x, y, z) planes, e.g. to visualize symmetric halves. Warns if the nodes on a mirrored plane are not constrained to enforce that symmetry.

• show_undeformed (bool, default: False ) –

  If True, draws the undeformed mesh as a grey wireframe.

• bcs (bool, default: False ) –

  If True, renders boundary conditions on the unmirrored mesh: arrows for forces and prescribed displacements, spheres at displacement tips, and a cone per constrained DOF. Rotational DOFs use doubled heads, the usual convention for moments. Constraints enforcing the symmetry of a mirrored plane are skipped, since the mirrored copy shows that symmetry already.

• plotter (Plotter | None, default: None ) –

  PyVista plotter. Defaults to None.

• **kwargs –

  Forwarded to pyvista.Plotter.add_mesh.

Compute the natural frequencies and mode shapes.

Solves the generalized eigenvalue problem

Parameters:

• n_modes (int) –

  Number of eigenpairs to compute.

Returns:

• tuple[Tensor, Tensor] –

  Tuple (omega_sq, modes) where omega_sq has shape [n_modes] (squared angular frequencies, differentiable) and modes has shape [n_modes, n_nod, n_dof_per_node] (detached).