fedoo.weakform.ArtificialDamping

class ArtificialDamping(c_stab=0.0002, energy_fraction=True, variables=None, mat_lumping=True, name='', space=None)

Weak formulation for artificial viscous stabilization.

This class provides artificial damping to stabilize unstable increments in both static and dynamic problems. It introduces a velocity-dependent damping force that regularizes the system when the stiffness matrix is singular or non-positive definite (e.g., during buckling, snap-through, or material softening).

The damping force is defined as:

\[F_{stab} = c_{stab} \cdot M^* \cdot v\]

where \(M^*\) is an artificial mass matrix (unit-density volume integrator) and \(v\) is the velocity computed from displacement: \(\Delta u / \Delta t\).

Parameters:

  • c_stab (float, default=2e-4) – The stabilization coefficient. If energy_fraction is True, this is interpreted as the target ratio of dissipated stabilization energy to external work.

  • energy_fraction (bool, default=True) – If True, the coefficient c_stab is automatically adapted at each increment to maintain a target energy ratio, ensuring the stabilization remains “invisible” to the physical results.

  • variables (str | list[str], optional) – The variables or vectors (e.g., ‘Disp’, ‘Rot’) to which damping is applied. By default, all displacement and rotational variables in the modeling space are included.

  • mat_lumping (bool, default=True) – If True, the stabilization matrix is lumped (diagonalized). This is highly recommended as it ensures that stabilization forces are localized and independent for each degree of freedom, improving numerical robustness.

  • name (str, optional) – Name of the WeakForm instance.

  • space (ModelingSpace, optional) – Modeling space for the weakform.

Notes

When using energy_fraction=True, the reference energy is the work of the external loads (forces, torques, etc.) during the last converged iteration. It is approximated by \(\Delta u \cdot F_t\), where \(F_t\) is the external force vector at the end of the iteration.

Limitations and Best Practices: * Initial Step: The simulation should ideally be stable enough to

converge its first increment with minimal damping. If the very first step diverges, consider setting energy_fraction=False.

  • Load Discontinuities: If the external load changes abruptly between increments, damping based on the previous iteration’s work may become unreliable or unadapted.

Examples

wf = fd.weakform.StressEquilibrium(material)
# Add 5% energy-based artificial damping
wf += fd.weakform.ArtificialDamping(c_stab=0.05, energy_fraction=True)
__init__(c_stab=0.0002, energy_fraction=True, variables=None, mat_lumping=True, name='', space=None)

Methods

ArtificialDamping.get_all()

Return the list of all weak forms.

ArtificialDamping.get_weak_equation(assembly, pb)

ArtificialDamping.initialize(assembly, pb)

ArtificialDamping.nvar(self)

Return the number of variables used in the modeling space associated to the WeakForm.

ArtificialDamping.reset()

ArtificialDamping.set_start(assembly, pb)

Update historical variables and adapt c_stab based on energy ratio.

ArtificialDamping.sum(wf1, wf2)

ArtificialDamping.to_start(assembly, pb)

ArtificialDamping.update(assembly, pb)

ArtificialDamping.update_2(assembly, pb)

ArtificialDamping.name

Return the name of the WeakForm.

ArtificialDamping.space

Return the ModelingSpace associated to the WeakForm if defined.