This note provides an interactive simulation of a coupled spring-mass-damper system with a linear motor providing external force excitation. Multiple masses are connected in series, with a programmable linear motor on the right end that applies periodic forces to the system.

The simulation allows you to configure the number of masses, spring constants, damping coefficients, and initial conditions. The linear motor can be controlled with various waveforms (sine, square, triangle, sawtooth), adjustable amplitude, and frequency. You can observe the system's behavior through real-time animations and plots showing position, velocity, and acceleration over time. This teaches the engineering principles behind forced vibrations, resonance, and coupled systems.

NOTE : Refer to this note for the theory of this system

 

Math behind the Simulation

1. System Configuration

The simulation models an N-degree of freedom spring-mass-damper system with external force excitation:

• N Masses: The system consists of N masses (m₁, m₂, ..., m_N) connected in series.
• N+1 Springs: For N masses, there are N+1 springs. The first spring connects the left wall to the first mass, springs 2 through N connect adjacent masses, and the last spring connects the last mass to the linear motor.
• Linear Motor: A programmable actuator on the right side provides external force excitation by moving the attachment point of the last spring. The motor displacement follows: x_motor(t) = A · f(ωt), where A is amplitude, ω = 2πf is angular frequency, and f() is the waveform function (sine, square, triangle, or sawtooth).
• Damping: Each mass has a damping coefficient (c₁, c₂, ..., c_N) that creates a velocity-proportional damping force.

2. Equations of Motion

The system is governed by coupled ordinary differential equations derived from Newton's second law (F = ma):

• For each mass i: m_i · a_i = F_spring,i + F_damping,i + F_ext,i
• Spring Forces (Hooke's Law): F_spring = -k · Δx, where k is the spring constant and Δx is the displacement from equilibrium.
• Damping Force: F_damping = -c · v, where c is the damping coefficient and v is the velocity.
• External Force (from Linear Motor): The motor provides excitation through base displacement — it moves the attachment point of the last spring, creating a time-varying force:
  • F_ext(t) = k_N · (x_motor(t) - x_N-1) = k_N · (A · f(2πft) - δ_N-1)
  • where A is amplitude, f is frequency, and δ_N-1 is the last mass's displacement from equilibrium
  • This is a displacement excitation (base excitation) model, not a direct force input
• For the first mass (i=0): Connected to left wall via spring k₀ and to second mass via spring k₁:
  • m₀ · a₀ = -k₀·x₀ - k₁(x₀ - x₁) - c₀·v₀
• For middle masses (i=1 to N-2): Connected to adjacent masses:
  • m_i · a_i = -k_i(x_i - x_i-1) - k_i+1(x_i - x_i+1) - c_i·v_i
• For the last mass (i=N-1) with External Force:
  • m_N-1 · a_N-1 = -k_N-1(x_N-1 - x_N-2) + k_N·(x_motor(t) - x_N-1) - c_N-1·v_N-1
  • The pink term is the external force from the linear motor
  • x_motor(t) = x_base + A · f(2πft), where f() is the waveform function
• State-Space Representation: The system can be written as:
  • dx_i/dt = v_i (velocity)
  • dv_i/dt = F_i/m_i (acceleration)

2.1. Linear Motor Waveforms

The linear motor provides displacement excitation using various waveform functions f(θ) where θ = 2πft:

• Sine: f(θ) = sin(θ) — Smooth, continuous excitation producing pure harmonic motion
• Square: f(θ) = sign(sin(θ)) — Alternating between +A and -A, creates step-like excitation
• Triangle: f(θ) = Linear ramp up then down — Creates constant velocity motion segments
• Sawtooth: f(θ) = Linear ramp from -A to +A — Creates periodic "reset" motions

3. Numerical Integration (Runge-Kutta 4th Order)

The coupled ODEs are solved numerically using the Runge-Kutta 4th order method (RK4):

• Time Step (dt): The simulation advances in discrete time steps. Smaller dt values provide higher accuracy but require more computation.
• RK4 Algorithm: For each time step, RK4 calculates four intermediate derivatives (k₁, k₂, k₃, k₄) and combines them:
  • k₁ = f(t, y)
  • k₂ = f(t + dt/2, y + dt·k₁/2)
  • k₃ = f(t + dt/2, y + dt·k₂/2)
  • k₄ = f(t + dt, y + dt·k₃)
  • y(t + dt) = y(t) + (dt/6)(k₁ + 2k₂ + 2k₃ + k₄)
• Accuracy: RK4 is a 4th-order method, meaning the local truncation error is O(dt⁵), providing excellent accuracy for smooth systems.

4. Equilibrium Positions

The equilibrium positions are calculated based on the boundary conditions:

• Fixed right wall: Masses are evenly spaced between the two walls: x_eq,i = x_{wall_left} + (i+1) · L/(N+1), where L is the distance between walls.
• Open-ended: Masses are evenly spaced from the left wall: x_eq,i = x_{wall_left} + (i+1) · L/(N+1) (same formula, but the last spring is not attached to a wall).
• Displacement: The plots show displacement from equilibrium: δ_i = x_i - x_eq,i, which is more physically meaningful than absolute position.

5. Boundary Constraints (Collision Handling)

The simulation enforces physical boundary constraints to prevent impossible mass positions:

• Wall Collisions: Masses cannot pass through the left wall. When a mass reaches the wall:
  • Position is clamped to the wall boundary plus a minimum gap (half mass width)
  • Velocity is reversed with a restitution coefficient of 0.8 (partially elastic collision)
  • This prevents "tunneling" through walls while preserving most of the energy
• Mass-to-Mass Collisions: Adjacent masses cannot overlap:
  • Minimum separation is enforced (one mass width)
  • When masses get too close, they are pushed apart equally
  • Velocities are averaged with restitution to simulate collision
• Velocity Limiting: Maximum velocity is capped at 50 m/s to prevent numerical instability in extreme resonance conditions.

 

Usage Example

Follow these steps to explore the Spring-Mass-Damper system with Linear Motor simulation:

1. Quick Start with Presets: Use the Preset dropdown to instantly load a preconfigured scenario. For example:
   • Select "🎯 Resonance" to see maximum amplitude response when the motor frequency matches the natural frequency
   • Select "🌊 Beating" to observe amplitude modulation when frequencies are close but not equal
   • The preset name stays visible in the dropdown so you know which configuration is active
2. Or Configure Manually: Use the "Number of Masses" input to set how many masses you want (1-5). Click "Apply Config" to update the system. The default is 2 masses with 3 springs.
3. Set Initial Conditions: You can adjust initial positions in two ways:
   • Mouse Drag: Click and drag any mass in the physical animation to set its initial position. The mass will snap to your mouse position as you drag.
   • Random Button: Click "Random" to randomly initialize all mass positions within the walls, ensuring minimum separation between masses.
4. Adjust Parameters: Use the sliders to modify system parameters:
   • Time Step (dt): Controls the numerical integration step size (0.001 to 0.05). Smaller values are more accurate but slower. Default: 0.01.
   • Damping: Controls the damping coefficient for all masses (0.0 to 2.0). Higher values create more energy dissipation. Default: 0.1.
   • Spring k: Controls the spring constant for all springs (1.0 to 50.0). Higher values create stiffer springs and faster oscillations. Default: 10.0.
5. Configure the Linear Motor: Use the motor panel (highlighted in pink) to set up external excitation:
   • Motor ON/OFF: Enable the motor to apply external force to the system.
   • Waveform: Choose sine, square, triangle, or sawtooth waveform.
   • Amplitude: Set how far the motor moves (0.0 to 3.0 m).
   • Frequency: Set the motor oscillation speed (0.1 to 5.0 Hz). Try adjusting this to find resonance!
6. Start the Simulation: Click "Start" to begin the simulation. The physical animation and all plots will update in real-time. Click "Start" again (now showing "Pause") to pause/resume.
7. Observe the Physical Animation:
   • Watch the masses oscillate between the walls (or extend beyond if open-ended).
   • Notice how the springs stretch and compress as masses move.
   • Each mass is colored to match its corresponding plot line (blue, green, orange, red, purple).
   • The current simulation time is displayed in the top-left corner.
8. Analyze Time Series Plots: Three plots show how the system evolves over time:
   • Displacement vs Time: Shows how each mass's displacement from equilibrium changes over time. Notice the oscillatory behavior and how different masses may have different phases.
   • Velocity vs Time: Shows the velocity of each mass. Velocity is maximum when displacement is zero (passing through equilibrium).
   • Acceleration vs Time: Shows the acceleration of each mass. Acceleration is maximum when displacement is maximum (at the turning points).
9. Explore State Space Plots: Three plots show relationships between state variables:
   • Displacement vs Velocity: Creates phase portraits showing the trajectory in state space. Closed loops indicate periodic motion.
   • Displacement vs Acceleration: Shows the relationship between position and acceleration. For simple harmonic motion, this should be a straight line (F = -kx).
   • Velocity vs Acceleration: Shows how velocity and acceleration are related. The shape depends on the system's dynamics.
10. Reset and Experiment: Click "Reset" to return to initial conditions, or modify parameters while the simulation is running to see real-time effects.
11. Use Step Controls for Detailed Analysis: For careful examination:
    • Click "Step ▶" to advance one time step at a time
    • Click "◀ Step" to go backward and review what happened
    • The status bar shows how many history states are saved (up to 500)
    • This is especially useful for understanding collision events or resonance buildup

Tips:

•   Finding Resonance: Start with 1 mass and low damping. Slowly increase the motor frequency until you see maximum amplitude response — this is resonance! The natural frequency is approximately ω_n = √(k/m). With default k=10 and m=1, natural frequency ≈ 0.5 Hz.
•   Beating Phenomenon: Set the motor frequency close to (but not exactly at) the natural frequency. You'll see the amplitude oscillate slowly — this is "beating".
•   Damping Effect: Increase the damping slider and observe how oscillations decay faster. At resonance, higher damping reduces the peak amplitude.
•   Different Waveforms: Try square and triangle waveforms to see how the system responds to non-sinusoidal excitation. Square waves contain many harmonics, exciting multiple frequencies simultaneously.
•   Normal Modes: Try setting initial conditions where all masses start at the same displacement. You'll see synchronized motion (first normal mode). For 2 masses, try displacing them in opposite directions to see the second normal mode.
•   Spring Stiffness: Increase the spring constant to see faster oscillations (higher natural frequency). Decrease it to see slower, more gentle motion.
•   Multiple Masses: Try 3 or 4 masses to see more complex coupled oscillations. Notice how energy transfers between masses through the connecting springs.
•   Time Step Accuracy: If you see numerical instability (wild oscillations or divergence), reduce the time step. For smooth, accurate results, use dt ≤ 0.01.
•   Plot Scrolling: The time series plots show a rolling window of the last 10 seconds. New data appears on the right, and old data scrolls off the left, making it easy to observe long-term behavior. The motor displacement is shown as a dashed pink line on the displacement plot.
•   Using Presets: The preset dropdown is the fastest way to explore different phenomena. Start with "🎯 Resonance" to understand forced vibrations, then try "🌊 Beating" to see frequency interference. Compare "🛑 Heavy Damping" vs "♾️ No Damping" to understand energy dissipation.
•   Step-by-Step Analysis: When studying collisions or transient behavior, use the Step buttons. Click "Step ▶" repeatedly to advance frame-by-frame, then use "◀ Step" to rewind and see exactly when and how events occur.
•   Boundary Collisions: The simulation now handles wall collisions with a restitution of 0.8 (mostly elastic). Watch how the mass bounces off the left wall during high-amplitude resonance. The collision response prevents unrealistic "tunneling" while preserving physical behavior.

 

Visualizations

The simulation provides multiple synchronized real-time visualizations that update as the simulation runs:

• 1. Physical System Animation: Shows a top-down view of the spring-mass-damper system with:
  • Fixed Wall: Dark gray rectangle on the left.
  • Springs: Green zig-zag lines connecting masses to walls and to each other. Springs stretch and compress as masses move.
  • Masses: Colored rectangles representing each mass. Colors match the corresponding plot lines: Mass 1 = Blue, Mass 2 = Green, Mass 3 = Orange, Mass 4 = Red, Mass 5 = Purple.
  • Linear Motor: Gray/pink housing on the right with a moving piston shaft. The motor provides periodic displacement excitation to the last spring. A pink indicator light shows the motor is active. The motor label and info (waveform, amplitude, frequency) are displayed in the animation.
  • Time Display: Current simulation time shown in the top-left corner.
  The animation updates in real-time, showing the dynamic behavior of the coupled system. You can drag masses to adjust their initial positions before starting the simulation.
• 2. Time Series Plots: Three plots showing how state variables evolve over time:
  • Displacement vs Time: Shows the displacement of each mass from its equilibrium position over time. The motor displacement is shown as a dashed pink line for reference. The plot uses a rolling window of the last 10 seconds, with new data appearing on the right. This reveals oscillatory behavior, phase relationships, and damping effects.
  • Velocity vs Time: Shows the velocity of each mass over time. Velocity is the time derivative of displacement. Notice how velocity is maximum when displacement is zero (passing through equilibrium).
  • Acceleration vs Time: Shows the acceleration of each mass over time. Acceleration is the time derivative of velocity. For harmonic motion, acceleration is maximum when displacement is maximum (at turning points).
  All time series plots use the same color scheme as the masses and share the same time axis (last 10 seconds). Each plot has a center-aligned title and shows grid lines for easy reading. The legend shows mass labels and motor indicator.
• 3. State Space Plots: Three plots showing relationships between different state variables:
  • Displacement vs Velocity: Creates phase portraits showing the trajectory in state space. For periodic motion, this creates closed loops (limit cycles). The shape and size of the loops reveal information about the system's energy and damping.
  • Displacement vs Acceleration: Shows the relationship between position and acceleration. For simple harmonic motion with a single spring, this should be a straight line (F = -kx, so a = -kx/m). For coupled systems, the relationship is more complex.
  • Velocity vs Acceleration: Shows how velocity and acceleration are related. This plot helps visualize the system's dynamics and energy flow.
  State space plots also use a rolling window and share the same color scheme. They help visualize the system's behavior in a different coordinate system, revealing patterns that may not be obvious in time series.

Controls

• Preset Dropdown: Quick-select preconfigured scenarios to explore different physical phenomena. The selected preset remains visible in the dropdown. Available presets:
  • 🎯 Resonance (ω = ω_n): 1 mass, motor at natural frequency (0.5 Hz) — observe maximum amplitude response
  • 🌊 Beating (ω ≈ ω_n): 1 mass, motor slightly off natural frequency (0.55 Hz) — see amplitude modulation
  • 🐌 Low Frequency: 2 masses, very slow motor (0.1 Hz) — quasi-static response, masses follow motor
  • ⚡ High Frequency: 2 masses, fast motor (3.0 Hz) — attenuated response, system cannot follow
  • 🛑 Heavy Damping: 1 mass, high damping (c=1.5) — see rapid decay of oscillations
  • ♾️ No Damping: 1 mass, zero damping — perpetual oscillation, energy conservation
  • ▢ Square Wave: 2 masses, square waveform — step excitation, rich harmonic content
  • △ Triangle Wave: 2 masses, triangle waveform — constant velocity segments
  • 🔗 3-Mass Chain: 3 coupled masses — observe mode shapes and energy transfer
  • 🧸 Soft Springs: Low spring constant (k=3) — slow, gentle oscillations
  • 🔩 Stiff Springs: High spring constant (k=40) — fast, tight oscillations
• Number of Masses: Input field to set the number of masses (1-5). The default is 2. Click "Apply Config" to reconfigure the system with the new number of masses. When you change the number of masses, the system is reset with default parameters (evenly spaced masses, default spring constants and damping).
• Apply Config Button: Applies the new number of masses configuration. The system is reinitialized with default parameters, and all masses are positioned evenly between the walls.
• Random Button: Randomly initializes the position of each mass within the walls, ensuring minimum separation between masses. This is useful for exploring different initial conditions and observing how the system evolves from non-equilibrium states.
• Reset Button: Resets the simulation to the initial conditions (current positions and zero velocities). The simulation time is reset to zero, and all plot histories are cleared.
• Time Step (dt) Slider: Controls the numerical integration step size from 0.001 to 0.05 seconds. Smaller values provide higher accuracy but require more computation. Default: 0.01. The current value is displayed next to the slider.
• Damping Slider: Controls the damping coefficient for all masses from 0.0 to 2.0. Higher values create more energy dissipation, causing oscillations to decay faster. Default: 0.1. The current value is displayed next to the slider.
• Spring k Slider: Controls the spring constant for all springs from 1.0 to 50.0. Higher values create stiffer springs, resulting in faster oscillations (higher natural frequency). Default: 10.0. The current value is displayed next to the slider.
• Start/Pause Button: Starts or pauses the simulation. When running, the button shows "Pause"; when stopped, it shows "Start". Clicking while running pauses the simulation, and clicking while paused resumes from the current state.
• ◀ Step (Step Backward): Steps the simulation backward by one time step. Uses saved state history (up to 500 states). The button is disabled when:
  • No history is available (at t=0)
  • The simulation is currently running
  This allows you to carefully examine what happened before a particular moment.
• Step ▶ (Step Forward): Advances the simulation by exactly one time step (dt). Useful for:
  • Carefully examining system behavior frame-by-frame
  • Understanding the exact sequence of events
  • Educational purposes to see how RK4 integration works
  Each step saves the previous state to history, allowing you to step backward afterward.
• Status Display: Shows the current simulation state, time, motor configuration, and history count (e.g., "Running - t = 5.23s | Motor: sine 0.5Hz | History: 500").
• Mouse Drag (Physical Animation): Click and drag any mass in the physical animation to adjust its initial position. This allows you to set custom initial conditions before starting the simulation. The mass will follow your mouse cursor as you drag. When you release the mouse, the position is set and velocities are reset to zero.

Linear Motor Controls

The linear motor panel (highlighted in pink) provides controls for the external force excitation:

• Motor ON/OFF Toggle: Enables or disables the linear motor. When OFF, the system reverts to a fixed right wall boundary condition. When ON, the motor provides periodic displacement excitation.
• Waveform Select: Choose the motor excitation waveform:
  • Sine: Smooth sinusoidal motion — ideal for studying harmonic forced vibrations and resonance.
  • Square: Step-like motion alternating between +A and -A — useful for studying transient response to sudden changes.
  • Triangle: Linear ramp up and down — creates constant-velocity motion segments.
  • Sawtooth: Linear ramp with periodic reset — useful for studying asymmetric excitations.
• Amplitude Slider: Controls the motor displacement amplitude from 0.0 to 3.0 meters. Higher values create larger external excitation. Default: 1.0 m.
• Frequency Slider: Controls the motor oscillation frequency from 0.1 to 5.0 Hz. Adjusting this allows you to explore:
  • Low frequency: System follows motor closely (quasi-static response)
  • Resonance: When motor frequency matches system natural frequency, maximum amplitude response
  • High frequency: System cannot follow fast excitation, response attenuates
  Default: 1.0 Hz.

System Parameters

The simulation uses the following default parameters, which can be adjusted via the control panel:

• Number of Masses (N): 1 to 5 (default: 2). Determines the number of degrees of freedom in the system.
• Number of Springs: N+1 (one more than the number of masses). The first spring connects the left wall to the first mass, springs 2 through N connect adjacent masses, and the last spring connects the last mass to the linear motor.
• Mass Values: All masses default to 1.0 kg. Currently, all masses have the same value, but the system architecture supports different masses per mass.
• Spring Constants: All springs default to 10.0 N/m. The slider adjusts all springs simultaneously. The system architecture supports different spring constants per spring.
• Damping Coefficients: All masses default to 0.1 N·s/m. The slider adjusts all damping coefficients simultaneously. The system architecture supports different damping per mass.
• Wall Position: Left wall at x = 0.0 m. Motor base position at x = 10.0 m.
• Initial Conditions: By default, masses are positioned at their equilibrium positions with zero initial velocity. You can modify initial positions by dragging masses or using the Random button.
• Time Step (dt): Default 0.01 seconds. This is the step size used in the Runge-Kutta 4th order numerical integration.

Linear Motor Parameters

The linear motor provides external force excitation with the following parameters:

• Enabled: Default: ON. When enabled, the motor provides periodic displacement to the right boundary.
• Waveform: Default: Sine. Available options: Sine, Square, Triangle, Sawtooth.
• Amplitude (A): Default: 1.0 m. Range: 0.0 to 3.0 m. The maximum displacement of the motor from its base position.
• Frequency (f): Default: 1.0 Hz. Range: 0.1 to 5.0 Hz. The number of complete oscillation cycles per second.
• Motor Position: x_motor(t) = x_base + A · f(2πft), where f() is the waveform function.