ROSS (Rotordynamic Open-Source Software)

The ROSS Graphical Interface provides a visual workflow for rotor dynamics:

• Modeling: Interactive editing of materials, shaft elements, disks, gears, bearings, seals, couplings, and point masses.
• Visualization: Real-time 3D visualization of the rotor model.
• Analysis: Dashboards for Campbell Diagrams, Unbalanced Critical Speed (UCS), Frequency Response, Time Response, Vibration Modes (2D/3D), Unbalance Response, and Static Analysis.
• Export: Automatically generate Python scripts using native ROSS syntax from your visual model.
• Persistence: Save and load configurations via JSON files.
• Theming: Supports Light and Dark themes (follows system settings by default).

ROSS (Rotordynamic Open Source Software) is a Python package (ross-rotordynamics) used for building complex rotor models and performing various rotordynamic analyses.

Core Modeling Capabilities:

• Shaft elements, disks, bearings, seals, and materials.

Analysis Capabilities:

• Modal & Frequency: Modal analysis, Campbell diagrams, critical speeds, and Frequency Response Functions (FRF).
• Response Analysis: Unbalance response, time response, and static analysis.
• Stability & Clearance: Undamped critical speed (UCS) maps, API 617 Level 1 stability, and clearance analysis.
• Fault Analysis: Rubbing, cracks, and misalignment.
• Advanced Components: Gas seals with speed- and whirl-frequency-dependent coefficients.

ROSS uses SI units internally:

• Speed: rad/s
• Stiffness: N/m
• Damping: N·s/m
• Unbalance: kg·m

You can perform conversions using the rs.Q_(value, "unit") helper. For example, to convert 4000 RPM to rad/s and then to a meter-based unit, use the .to() method.

# Example conversion from RPM to rad/s
val = rs.Q_(4000, "RPM").to("rad/s").m

When analyzing the results of fault simulations, look for these characteristic frequency signatures using .plot_dfft() and .plot_2d(node=n):

To compare how a fault affects different parts of the rotor, use response.plot_2d(node=n) at various nodes.

When analyzing ModalResults, keep the following physical interpretations in mind:

• Mode Pairs: Modes appear in pairs representing forward whirl (precession in the same direction as rotation) and backward whirl (precession opposite to rotation).
• Stability:
  • log_dec > 0: The mode is stable.
  • log_dec < 0: The mode is unstable.
• Gyroscopic Splitting: At speed=0, forward and backward whirl pairs only coincide if the supports are isotropic (kxx == kyy). Anisotropic bearings will cause the pairs to split even at zero speed.

ROSS is designed to be extensible. Developers can add new components like specialized bearings or seals by inheriting from existing base classes.

Adding a Bearing

To add a new type of bearing (e.g., a tapered roller bearing), inherit from the BearingElement class. An example of this pattern is seen in the existing BallBearingElement implementation.

Adding a Custom Element

For elements requiring more fundamental customization, inherit directly from the Element class. When doing this, you must implement the required methods to return the following matrices for the element:

• Mass matrix
• Stiffness matrix
• Damping matrix
• Gyroscopic matrix

ROSS maintains visual consistency across its documentation, figures, and graphical interface by using a shared set of design tokens. These tokens are named values for typography, color, spacing, radius, elevation, and motion.

Instead of using hardcoded hex values, all surfaces (CSS, Python Plotly templates, and the Frontend) consume these tokens. This allows for seamless theme switching (light/dark) because stylesheets are written using semantic aliases (e.g., --surface-page) rather than specific colors. When the data-theme attribute on the <html> element changes, these aliases re-point to different values, updating the entire UI automatically.

When analyzing unbalance response plots, look for these indicators:

• Critical Speeds: Identified by peaks in the magnitude plot.
• Resonance: Characterized by a phase change of approximately 180° through the resonance point.
• Whirl Direction: Can be identified by using multiple probes placed at different angles.
• Compliance: Results can be compared against API 617 acceptance criteria where applicable.

ROSS uses 0-based indexing for both nodes and Degrees of Freedom (DOF).

Node Numbering

• Nodes are numbered from 0 to N.
• If you have n shaft elements, you will have n+1 nodes.
• Node 0 is always the leftmost end of the rotor.
• Disks and bearings are attached to specific nodes.

DOF Indexing

Every node has 6 DOFs in the order: [x, y, z, alpha, beta, theta].

• 0: x (horizontal)
• 1: y (vertical)
• 2: z (axial)
• 3: alpha (rotation about x)
• 4: beta (rotation about y)
• 5: theta (torsion about z)

To calculate the global index for a specific DOF: DOF index = rotor.number_dof * node + direction

When analyzing a Campbell diagram, look for the following indicators:

• Critical Speeds: Indicated by crossing points where a natural frequency curve intersects an $N_x$ synchronous line.
• Synchronous Lines:
  • 1x (harmonic=1): Excitation frequency equals rotation speed (typical for unbalance).
  • 0.5x or 2x: Sub-synchronous or super-synchronous excitations.
• Gyroscopic Effect: Observed when forward and backward frequencies diverge as speed increases.
• Stability: Check the log_dec (logarithmic decrement) at crossing points. If log_dec is negative, the mode is unstable at that speed.