Mass–spring–damper

A two-state finite-dimensional port-Hamiltonian model

Let \(q\) be the displacement of a point mass, \(p=m\dot q\) its momentum, \(m>0\) the mass, \(k>0\) the stiffness and \(c\geq0\) the viscous damping coefficient. The applied force is \(f(t)\). Then

\[\dot q = \frac{p}{m},\qquad \dot p = -kq-\frac{c}{m}p+f(t).\]

Use the energy variables \(z=(q,p)^\top\) and Hamiltonian

\[H(z)=\frac12 kq^2+\frac{p^2}{2m}.\]

The co-energy variables are

\[e_q=\frac{\partial H}{\partial q}=kq,\qquad e_p=\frac{\partial H}{\partial p}=\frac{p}{m}.\]

The port-Hamiltonian representation is

\[\begin{split}\dot z = \underbrace{\begin{bmatrix}0&1\\-1&0\end{bmatrix}}_{J} \begin{bmatrix}e_q\\e_p\end{bmatrix} -\underbrace{\begin{bmatrix}0&0\\0&c\end{bmatrix}}_{R} \begin{bmatrix}e_q\\e_p\end{bmatrix} +\begin{bmatrix}0\\1\end{bmatrix}f(t),\qquad y=e_p.\end{split}\]

Since \(J=-J^\top\) and \(R\succeq0\), the continuous power balance is

\[\dot H=-c\,e_p^2+f(t)e_p.\]

Discretization and code

This is an ODE, not a spatial PDE. The new lumped port kind assigns one GetFEM DOF to each state and its co-state. The reference interval \((0,1)\) in the script is only used to assemble scalar GetFEM weak forms; it is not a physical spring mesh.

The implementation follows the standard SCRIMP workflow:

  1. Create a DPHS and its reference Domain.

  2. Add two State objects with kind=”lumped”, and their CoState objects.

  3. Call add_lumped_port for q and p (not add_FEM).

  4. Add mass, interconnection, damping, forcing and constitutive Brick objects.

  5. Initialize the states, integrate with implicit PETSc BDF2, then plot.

The factor /ell in each brick compensates for the integration over the reference interval length ell, so that the resulting scalar equations are exactly those above. The time-dependent forcing is assembled as a nonlinear/residual brick rather than as a fixed matrix term; this is needed in SCRIMP’s current GetFEM assembly path.

The complete runnable source is:

examples/mass_spring_damper.py
# SCRIMP - Simulation and ContRol of Interactions in Multi-Physics
#
# Copyright (C) 2015-2026 ISAE-SUPAERO -- GNU GPLv3
# 
# See the LICENSE file for license information.
#
# github: https://github.com/g-haine/scrimp

"""Mass--spring--damper: a finite-dimensional port-Hamiltonian example.

State x=(q,p), with displacement q and momentum p=m*q_dot.
    H(q,p) = k*q**2/2 + p**2/(2*m)
    e_q = dH/dq = k*q,  e_p = dH/dp = p/m
    q_dot = e_p
    p_dot = -e_q - c*e_p + f(t)

Power balance: H_dot = -c*e_p**2 + f*e_p.

Each lumped port has a **single** DOF. The interval used here is only
a normalization domain for GetFEM's weak-form assembly; it is NOT a
spatial discretization of the oscillator.
"""

import numpy as np
import scrimp as S


def mass_spring_damper(final_time=8.0, time_step=0.01, plot=False):
    """Simulate the forced, damped oscillator using lumped dynamic ports.

    Returns
    -------
    scrimp.DPHS
        Solved system with Hamiltonian terms and time histories.
    """
    mass = 1.5
    stiffness = 5.0
    damping = 0.25
    interval_length = 1.0

    sys = S.DPHS("real")
    sys.set_domain(S.Domain("Interval", {"L": interval_length, "h": 1.0}))

    q = S.State("q", "Displacement", "lumped")
    p = S.State("p", "Linear momentum", "lumped")
    for state in (q, p):
        sys.add_state(state)
    sys.add_costate(S.CoState("e_q", "Spring force", q))
    sys.add_costate(S.CoState("e_p", "Velocity", p))

    # Unlike FEM("q", ...), this registers a single scalar DOF.
    sys.add_lumped_port("q")
    sys.add_lumped_port("p")

    for key, val in {
        "ell": interval_length,
        "osc_mass": mass,
        "spring_k": stiffness,
        "damp_c": damping,
    }.items():
        sys.gf_model.add_macro(key, str(float(val)))
    sys.gf_model.add_macro("force", "0.2*sin(2*pi*t)")

    bricks = [
        S.Brick("M_q", "q*Test_q/ell", [1], dt=True, position="flow"),
        S.Brick("M_p", "p*Test_p/ell", [1], dt=True, position="flow"),
        # Canonical Dirac interconnection J = [[0,1],[-1,0]]
        S.Brick("J_qp", "e_p*Test_q/ell", [1], position="effort"),
        S.Brick("J_pq", "-e_q*Test_p/ell", [1], position="effort"),
        S.Brick("Damping", "-damp_c*e_p*Test_p/ell",
                [1], position="effort"),
        # A time-only source is classified non-linear so that it is
        # assembled on every residual evaluation.
        S.Brick("External_force", "force*Test_p/ell", [1],
                linear=False, position="effort"),
        S.Brick("Spring_law", "(spring_k*q-e_q)*Test_e_q/ell", [1]),
        S.Brick("Momentum_law", "(p/osc_mass-e_p)*Test_e_p/ell", [1]),
    ]
    for brick in bricks:
        sys.add_brick(brick)

    sys.set_initial_value("q", 0.4)
    sys.set_initial_value("p", 0.0)
    sys.set_time_scheme(
        ts_type="bdf", ts_bdf_order=2,
        ts_exact_final_time="matchstep",
        ts_adapt_type="none",
        ksp_type="gmres", pc_type="lu",
        pc_factor_mat_solver_type="superlu",
        t_0=0.0, t_f=float(final_time),
        dt=float(time_step), dt_save=float(time_step),
        init_step=True,
    )
    sys.solve()

    sys.hamiltonian.set_name("Mass--spring--damper energy")
    sys.hamiltonian.add_term(
        S.Term("Spring potential", "spring_k*q*q/(2*ell)", [1])
    )
    sys.hamiltonian.add_term(
        S.Term("Kinetic", "p*p/(2*osc_mass*ell)", [1])
    )

    if plot:
        import matplotlib.pyplot as plt

        times = np.asarray(sys.solution["t"], dtype=float)
        displacement = np.asarray(sys.get_solution("q"), dtype=float).ravel()
        momentum = np.asarray(sys.get_solution("p"), dtype=float).ravel()
        fig, ax = plt.subplots()
        ax.plot(times, displacement, label="q (displacement)")
        ax.plot(times, momentum/mass, label="q_dot (velocity)")
        ax.set(xlabel="Time", title="Mass--spring--damper")
        ax.grid(True)
        ax.legend()
        fig.tight_layout()
        sys.plot_Hamiltonian(with_powers=False)
        plt.show()
    return sys


if __name__ == "__main__":
    mass_spring_damper(plot=True)

Run from the repository root (in the SCRIMP Conda environment):

python examples/mass_spring_damper.py

Verification

The expected energy variation satisfies

\[H(t)-H(0)=\int_0^t\bigl[f(s)e_p(s)-c\,e_p(s)^2\bigr],\mathrm ds.\]

Compute the two integrals from the stored time histories to verify the numerical energy balance. BDF2 is not an exactly energy-preserving integrator: the measured defect should be examined under time-step refinement. A free undamped oscillator (f=0, c=0) is a useful additional regression case.

Note

This example has passed the automated numerical smoke tests and a full default standalone run in the SCRIMP GetFEM/PETSc environment. Quantitative power-balance refinement remains a separate check.