Feature Request: Native Support for Unbalance Forces in run_time_response()

[ArthurIasbeck]

Summary

run_time_response() presently obliges users to build the complete external‐force matrix (F) or to supply a custom callback via add_to_RHS whenever unbalance effects are required. This leads to redundant, error-prone code, as each user must recreate the same harmonic loading scheme. Introducing first-class, declarative unbalance parameters—similar to the existing run_unbalance_response() in the frequency domain—would streamline time-domain simulations.

---

Current Limitation

• Users must manually construct the unbalance force terms (or embed them in a callback).
• There is no built-in mechanism to combine a user-supplied force matrix with standard unbalance loading in a transparent manner.

---

Proposed Enhancement

Add native unbalance handling to run_time_response(), enabling the caller to specify any number of unbalances via the following parameters:

Parameter	Type	Description
node	int or list[int]	Node index where the unbalance is located.
mass (mε)	float or Quantity	Unbalance magnitude (kg·m).
phase	float (rad)	Initial phase angle.
(optional) speed	float or np.ndarray	Rotor speed; defaults to the speed argument already passed to the method.

For each unbalance the method would form

$$ F_x(t) = mε\,Ω(t)^2 \cos\!\bigl[Ω(t)\,t + \varphi\bigr],\qquad F_y(t) = mε\,Ω(t)^2 \sin\!\bigl[Ω(t)\,t + \varphi\bigr] $$

and inject these components at the relevant global DoFs.

If a user also supplies an explicit force matrix, the internally generated unbalance forces must be superimposed (i.e., F_total = F_user + F_unbalance).

---

Implementation Suggestions

1. API Extension

   def run_time_response(
       self,
       speed,
       force=None,
       time_range=None,
       …,
       unbalance_nodes=None,
       unbalance_masses=None,
       unbalance_phases=None,
   ):
       …
   

   Behaviour

   • If all unbalance_* arguments are None, keep current behaviour.
   • If any unbalance_* argument is provided:
     1. Build F_unbalance internally.
     2. If force is also provided, compute F = force + F_unbalance; otherwise set F = F_unbalance.

2. Code Reuse

   • Leverage the existing node-to-DoF mapping and vectorised operations from run_unbalance_response() to assemble F_unbalance.
   • Support both scalar-speed (steady) and array-speed (transient spin-up/down) cases.

3. Multiple Unbalances & Vectorisation

   • Accept sequences for nodes, masses, and phases to handle multiple unbalances in one call.
   • Employ numpy broadcasting to avoid explicit Python loops over time steps.

4. Documentation & Examples

   • Add a subsection “Time Response with Native Unbalance” detailing constant- and variable-speed scenarios.
   • Provide comparative plots demonstrating equivalence between the new interface and the manual force-matrix approach.

5. Unit Tests

   • Validate that results obtained with the new parameters match legacy manual constructions.
   • Include tests combining user-supplied force matrices with unbalance parameters to ensure correct superposition.

---

Expected Benefits

• Usability – Removes routine boilerplate and reduces user error in force-matrix assembly.
• Flexibility – Allows simultaneous use of bespoke external forces and standard unbalance loads through simple superposition.
• Consistency – Brings the time-domain API in line with the well-established frequency-domain workflow.
• Extensibility – Provides a foundation for future enhancements such as automated parametric studies or stochastic unbalance modelling.

---

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

[jguarato]

Hi, @ArthurIasbeck!

I'll use this comment to also address your other issue, #1197.

Your requests have been addressed. The ROSS code approach is to keep the Rotor class methods as generic as possible, avoiding excessive conditions and arguments. With that in mind, as part of PR #1202, a new gravitational_force method was added. Additionally, the previously implemented unbalance_force_over_time method is now available to users.

---

The tutorial has also been updated to include an example demonstrating these features:

1.3.1.3 Considering coded force methods

In this example, we consider two forces of excitation:

• Unbalance Force ($F_{unb}$): The method .unbalance_force_over_time() calculates this time-varying force and returns a force array of shape (ndof, len(t)).

• Weight ($W$): The method .gravitational_force() returns a static force array of shape (ndof,), which must be expanded to match the time dimension.

• Force Combination: $F(t) = F_{unb}(t) + W$

dt = 1e-3
t = np.arange(0, 16, dt)
speed = 600.0
node = 29

# Unbalance force
Funb, _, _, _ = rotor3.unbalance_force_over_time(
    node=[node], magnitude=[0.003], phase=[0], omega=speed, t=t
)

# Weight
W = rotor3.gravitational_force(direction="y")

# Force combination
F = (Funb + W[:, np.newaxis]).T  # F argument has shape (len(t), ndof)

response3_2 = rotor3.run_time_response(speed, F, t)

---

If you have any questions or concerns, feel free to reach out!