Axisymmetric¶

Initialize the axisymmetric FEM problem, which carries no thickness.

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

Parameters:

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

  Load scale factors starting at 0, typically [0, 1]. They may rise and fall, so a load cycle is expressed as a sequence like [0, 1, 0]. 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.

• method (Literal['direct', 'cg', 'bicgstab'] | None, default: None ) –

  Linear solver method, chosen by size and tangent symmetry when omitted.

• preconditioner (Literal['amg', 'jacobi', 'none'] | None, default: None ) –

  Preconditioner for an iterative method, chosen by device and available backends when omitted.

• 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.

• alpha (float, default: 0.0 ) –

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

• hessian_modulus (Tensor | float | None, default: None ) –

  Modulus k of the regularization energy ½ k ∇∇u ⋮ ∇∇u, a float or with shape [n_elem].

• 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. A tensor that requires grad and enters the residual must be listed.

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 mesh with matplotlib, 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 (Tensor | dict[str, Tensor] | None, default: None ) –

  Scalar nodal field with shape [n_nod] rendered as interpolated contours, optionally keyed by its colorbar label.

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

  Element field rendered as flat colors (shape [n_elem]) or as vector arrows (shape [n_elem, 2]), keyed like node_property.

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

  Element-wise material angles in radians, measured counter-clockwise, rendered as line markers.

• node_labels (bool, default: False ) –

  If True, annotates nodes with their indices.

• node_markers (bool, default: False ) –

  If True, draws markers at nodal positions.

• axes (bool, default: False ) –

  If True, shows the coordinate axes.

• bcs (bool, default: True ) –

  If True, indicates applied forces as arrows scaled relative to each other and constrained DOFs as markers. In the undeformed configuration, prescribed non-zero displacements are drawn to scale as arrows with a dot at the tip instead of a marker. In the deformed configuration, only the dot is drawn, marking the position the node was pulled to. A heat flux is drawn as a plus or a minus, a convecting edge as tildes on its nodes, and a prescribed temperature keeps its marker.

• color (str, default: 'lightblue' ) –

  Element fill color. Edges, markers and labels follow the foreground of the style.

• alpha (float, default: 1.0 ) –

  Opacity of nodal contour plots.

• cmap (str | Colormap, default: 'viridis' ) –

  Matplotlib colormap or its name.

• linewidth (float, default: 1.0 ) –

  Element edge line width. Set to 0.0 to hide edges.

• figsize (tuple[float, float], default: (8.0, 6.0) ) –

  Figure size when a new figure is created.

• colorbar (bool, default: False ) –

  If True, adds a colorbar.

• vmin (float | None, default: None ) –

  Lower color limit.

• vmax (float | None, default: None ) –

  Upper color limit.

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

  Plot title.

• ax (Axes | None, default: None ) –

  Existing matplotlib axes to plot into.

• **kwargs –

  Forwarded to the PolyCollection of the elements, e.g. edgecolor to override the foreground or hatch to fill them with a pattern.

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). The gradients hold for distinct eigenvalues only, not repeated ones.

Initialize the axisymmetric FEM problem, which carries no thickness.

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

Parameters:

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

  Load scale factors starting at 0, typically [0, 1]. They may rise and fall, so a load cycle is expressed as a sequence like [0, 1, 0]. 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.

• method (Literal['direct', 'cg', 'bicgstab'] | None, default: None ) –

  Linear solver method, chosen by size and tangent symmetry when omitted.

• preconditioner (Literal['amg', 'jacobi', 'none'] | None, default: None ) –

  Preconditioner for an iterative method, chosen by device and available backends when omitted.

• 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.

• alpha (float, default: 0.0 ) –

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

• hessian_modulus (Tensor | float | None, default: None ) –

  Modulus k of the regularization energy ½ k ∇∇u ⋮ ∇∇u, a float or with shape [n_elem].

• 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. A tensor that requires grad and enters the residual must be listed.

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.