Feature Request: Native Support for Gravity Loading in run_time_response()

[ArthurIasbeck]

Summary

run_time_response() currently requires users to manually add the weight of shafts, disks and other components to the external‐force matrix F. The method signature only accepts speed, F, t, method and arbitrary **kwargs—there is no built-in flag for gravity inclusion.

Conversely, the static analysis routine already computes and stores the shaft and disk weights (shaft_weight, disk_forces_nodal, etc.) for vertical deflection calculations.

This feature request proposes adding first-class, opt-in gravity loading to time-domain simulations so users can obtain realistic transient responses without constructing a custom force matrix.

---

Motivation

• Accuracy: Rotating machinery installed horizontally is always subject to its own weight; omitting this constant load can underestimate peak shaft deflections and bearing loads in transient studies.
• Usability: Preparing an ndof-sized gravity vector and broadcasting it over all time steps is error-prone—especially for large multirotor models. A simple flag would streamline workflows and align the API with other ROSS analyses that already handle weight internally (run_static).
• Consistency: Providing a unified way to activate gravity across analyses reduces cognitive load and improves documentation coherence.

---

Proposed API Change

# illustrative only
response = rotor.run_time_response(
    speed,
    F,          # user–defined dynamic forces
    t,
    include_gravity=True,   # new boolean flag (default False for backward-compatibility)
    g=9.80665,             # optional override of gravitational acceleration (m/s²)
    gravity_axis='y',      # 'y' (default) or 'z' to match modelling conventions
    method="newmark",
)

• When include_gravity=True, the solver should internally build a constant force vector Fg with the same shape as one time slice of F and add it to the right-hand side at every time step.
• Fg can reuse the per-node weight evaluation already implemented in run_static(). A helper such as _gravity_force_vector() could:
  1. Loop over shaft, disk and point-mass elements.
  2. Map each element’s translational DOF (typically the vertical y direction) to its nodal index.
  3. Compute w_i = m_i * g and insert w_i in the chosen gravity axis.
• For array-like speed (Newmark integration) or scalar speed (state-space), gravity remains constant—no additional modifications are required.

---

Implementation Notes

1. Backward Compatibility – Defaulting the flag to False ensures existing scripts reproduce identical results.
2. Extensibility – The same flag could later be honoured by run_forced_response() and other dynamic solvers for full consistency.
3. Testing – Unit tests should verify that enabling the flag reproduces the static equilibrium displacement at speed=0 when no other forces are applied.
4. Documentation – Update the User Guide and docstring examples illustrating both manual and automatic gravity loading.
5. Performance – Because the gravity vector is constant, it can be pre-computed once and broadcast with NumPy’s np.tile or via direct addition inside the integrator loop with negligible overhead.

---

Additional Context

• The requested functionality mirrors finite-element packages where gravity can be toggled globally for transient analysis.
• Implementation will leverage existing mass properties already computed for modal and static analyses, avoiding redundant calculations.

---

Thank you for considering this enhancement. Native gravity support in run_time_response() will improve the fidelity and ergonomics of time-domain simulations within ROSS.