modal damping

[Raimundovpn]

Introduction: Modal Damping Theory

In structural dynamics and vibration analysis, modal damping is a widely used approach to model energy dissipation in linear systems. Rather than specifying damping directly in physical coordinates (which can be complex and non-intuitive), modal damping assumes that damping is diagonal in the modal coordinate system—i.e., each mode damps independently of the others.

This approach relies on the assumption that the system is classically damped, meaning the damping matrix C satisfies the orthogonality condition with respect to the mass (M) and stiffness (K) matrices:

Φᵀ C Φ = diagonal

where Φ is the matrix of mode shapes (eigenvectors). Under this assumption, the equations of motion can be decoupled into independent single-degree-of-freedom systems in modal space, greatly simplifying time- and frequency-domain analyses.

Modal damping is typically specified by assigning a damping ratio ζᵢ to each mode i, representing the fraction of critical damping for that mode. This is especially convenient in engineering practice, as modal damping ratios can often be estimated from experimental data or code-specified values.

This PR introduces support for modal damping in, enabling users to define damping properties per mode and improving the physical realism and flexibility of dynamic simulations.

Case Study:

In this case, a study was conducted in which the FRF was evaluated for two modes:
In the 1st case study, zeta = [0, 0] was considered,

In the 2nd case study, zeta = [0.05, 0] was considered,

In the 3rd case study, zeta = [0.01, 0.02] was considered.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 45.83333% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.88%. Comparing base (fa3ab3e) to head (cc0100b).
⚠️ Report is 117 commits behind head on main.

Files with missing lines	Patch %	Lines
ross/rotor_assembly.py	40.90%	13 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1231      +/-   ##
==========================================
- Coverage   83.27%   82.88%   -0.39%     
==========================================
  Files          42       42              
  Lines       11894    12208     +314     
==========================================
+ Hits         9905    10119     +214     
- Misses       1989     2089     +100     

Files with missing lines	Coverage Δ
ross/shaft_element.py	95.72% <100.00%> (+0.03%)	⬆️
ross/rotor_assembly.py	92.22% <40.90%> (-0.96%)	⬇️

... and 5 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6dba5d1...cc0100b. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[raphaeltimbo]

Thank you for this detailed explanation of modal damping theory and the case studies! The theoretical background is very helpful.

To help reviewers better understand the implementation and potential use cases, could you provide some additional details?

API and Usage

1. How do users specify modal damping in their code? Could you provide a minimal code example showing how to:

   • Define a rotor with modal damping
   • Specify the damping ratios for different modes
   • Run an analysis using this feature

2. Which classes/methods were added or modified? A brief overview of the main API changes would help reviewers focus their attention.

Use Cases and Scope

3. What are the primary use cases where modal damping is preferred over other damping models? When should users choose this approach vs. proportional damping or other methods already available in ROSS?

4. Are there any limitations or assumptions users should be aware of? For example:

   • Does this only work with certain analysis types?
   • Are there restrictions on the number of modes?
   • Any performance considerations for large models?

Testing

5. What test coverage was added? It would be helpful to know what scenarios are covered by the tests to understand the validation scope.

Breaking Changes

6. Are there any breaking changes to existing APIs? Or is this purely additive functionality?

Thanks again for this contribution! The case study results look very promising for improving damping modeling in ROSS.