Skip to content

Truss

Bases: Mechanics

Truss model built from bar elements in 2D or 3D space.

The element type (Bar1, Bar2) is inferred from the number of nodes per element in the connectivity, and the spatial dimension from the nodes.

Attributes:

  • nodes –

    Nodal coordinates with shape [n_nod, n_dim].

  • elements –

    Element connectivity with shape [n_elem, nodes_per_element].

  • material (Material | None) –

    Vectorized 1D material model.

  • areas –

    Cross-sectional areas with shape [n_elem]. Defaults to ones.

  • forces (Tensor) –

    Applied nodal forces with shape [n_nod, n_dim].

  • displacements (Tensor) –

    Prescribed nodal displacements with shape [n_nod, n_dim].

  • constraints (Tensor) –

    Boolean mask of constrained DOFs with shape [n_nod, n_dim].

__init__(nodes, elements, material)

Initialize a truss FEM problem.

Parameters:

  • nodes (Tensor) –

    Nodal coordinates with shape [n_nod, n_dim].

  • elements (Tensor) –

    Connectivity with shape [n_elem, nodes_per_element].

  • material (Material) –

    1D material model, e.g. IsotropicElasticity1D.

solve(increments=None, max_iter=10, rtol=1e-08, atol=1e-06, stol=1e-10, cutback_factor=0.5, growth_factor=1.1, max_cutbacks=10, verbose=False, method=None, device=None, return_intermediate=False, aggregate_integration_points=True, use_cached_solve=False, nlgeom=False, alpha=0.0, differentiable_parameters=None)

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(u=0.0, **kwargs)

Plot the truss in 2D (matplotlib) or 3D (PyVista).

Dispatches to plot2d or plot3d based on the spatial dimension.

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

  • **kwargs –

    Forwarded to plot2d or plot3d, e.g. element_property (per-element values coloring the bars), show_thickness (line widths from cross-sectional areas), or node_labels (annotate node indices, 2D only).

solve_modes(n_modes)

Compute the natural frequencies and mode shapes.

Solves the generalized eigenvalue problem

\[\mathbf{K}\boldsymbol{\phi} = \omega^2 \mathbf{M}\boldsymbol{\phi}\]

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