ross.ThrustPad

ross.ThrustPad#

class ross.ThrustPad(n, pad_inner_radius, pad_outer_radius, pad_pivot_radius, pad_arc_length, angular_pivot_position, oil_supply_temperature, lubricant, n_pad, n_theta, n_radial, frequency, equilibrium_position_mode, radial_inclination_angle, circumferential_inclination_angle, initial_film_thickness, tolerance_force_moment=0.1, residual_force_moment=50, model_type='thermo_hydro_dynamic', axial_load=None, **kwargs)#

Thermo-Hydro-Dynamic (THD) Tilting Pad Thrust Bearing.

This class provides a comprehensive numerical model for tilting pad thrust bearings using thermo-hydro-dynamic (THD) analysis. Each pad is analyzed with its own pressure and temperature fields, pivot mechanics, and load distribution.

Theoretical Approach:

The model solves the complete THD problem for each pad using:

Reynolds Equation (for pressure field): - 2D finite volume method on a structured grid (n_radial × n_theta) - Accounts for pad rotation and surface velocities - Enforces atmospheric pressure at pad edges (cavitation boundary) - Viscosity varies spatially due to temperature field
Energy Equation (for temperature field): - 2D finite volume with upwind scheme - Includes viscous dissipation and heat conduction - Models turbulent effects using Reynolds number-dependent viscosity - Oil supply temperature as boundary condition
Equilibrium Calculation: - Iterative optimization to find pad equilibrium position - Two modes: calculate film thickness or use imposed thickness - Minimizes residual forces and moments using Nelder-Mead optimization (fmin) - Determines radial and circumferential inclination angles
Dynamic Coefficients (stiffness and damping): - Uses virtual perturbations of displacements and speeds to determine the coefficients - Applies small perturbations to axial position and velocity - Solves complete THD problem for each perturbation state - Extracts coefficients from force differences

For reference check [], [] and [Nicoletti, 1999].

Parameters:

nint: Node number for the bearing element.
pad_inner_radiusfloat: Inner radius of the pad. Default unit is meter.
pad_outer_radiusfloat: Outer radius of the pad. Default unit is meter.
pad_pivot_radiusfloat: Radius of the pivot point. Default unit is meter.
pad_arc_lengthfloat: Arc length of each pad. Default unit is degrees.
angular_pivot_positionfloat: Angular position of the pivot point. Default unit is degrees.
oil_supply_temperaturefloat: Oil supply temperature. Default unit is °C.
lubricantstr or dict: Lubricant type. Can be: - ‘ISOVG32’ - ‘ISOVG46’ - ‘ISOVG68’ Or a dictionary with lubricant properties.
n_padint: Number of pads in the bearing.
n_thetaint: Number of mesh elements in circumferential direction.
n_radialint: Number of mesh elements in radial direction.
frequencyarray_like: Rotor rotating frequency(ies). Default unit is rad/s.
equilibrium_position_modestr: Equilibrium position calculation mode: - ‘calculate’: Calculate film thickness and inclination angles - ‘imposed’: Use imposed film thickness, calculate inclination angles
model_typestr, optional: Type of model to be used. Options: - ‘thermo_hydro_dynamic’: Thermo-Hydro-Dynamic model
radial_inclination_anglefloat, optional: Initial radial inclination angle. Default unit is radians.
circumferential_inclination_anglefloat, optional: Initial circumferential inclination angle. Default unit is radians.
initial_film_thicknessfloat, optional: Initial film thickness at pivot point. Default unit is meters.
tolerance_force_momentfloat, optional: Convergence tolerance for residual forces and moments in N. The optimization stops when residual_force_moment < tolerance_force_moment. Default is 0.1.
residual_force_momentfloat, optional: Initial value for residual forces and moments in N. Used as starting point for the iterative equilibrium calculation. Default is 50.
axial_loadfloat, optional: Axial load applied to the bearing. Default unit is Newton.
**kwargsdict, optional: Additional keyword arguments.

Attributes:

kzzndarray: Axial stiffness coefficient in N/m.
czzndarray: Axial damping coefficient in N·s/m.
pressure_field_dimensionalndarray: Dimensional pressure field in Pa. Shape: (n_radial+2, n_theta+2)
temperature_fieldndarray: Temperature field in °C. Shape: (n_radial+2, n_theta+2)
pivot_film_thicknessfloat: Oil film thickness at the pivot point in m.
max_thicknessfloat: Maximum oil film thickness in m.
min_thicknessfloat: Minimum oil film thickness in m.
viscosity_fieldndarray: Viscosity field in Pa·s. Shape: (n_radial, n_theta)
film_thickness_center_arrayndarray: Film thickness at cell centers in m. Shape: (n_radial, n_theta)

Returns:

None: The class instance contains all calculated results as attributes.

References

[Nic99]

R Nicoletti. Efeitos térmicos em mancais segmentados híbridos—teoria e experimento. Thermal Effects in Hybrid Tilting-Pad Bearings—Theory and Experiment), M. Sc. dissertation, Universidade Estadual de Campinas, Campinas, http://libdigi. unicamp. br/document, 1999.

Examples

>>> from ross.bearings.thrust_pad import ThrustPad
>>> from ross.units import Q_
>>> bearing = ThrustPad(
...     n=1,
...     pad_inner_radius=Q_(1150, "mm"),
...     pad_outer_radius=Q_(1725, "mm"),
...     pad_pivot_radius=Q_(1442.5, "mm"),
...     pad_arc_length=Q_(26, "deg"),
...     angular_pivot_position=Q_(15, "deg"),
...     oil_supply_temperature=Q_(40, "degC"),
...     lubricant="ISOVG68",
...     n_pad=12,
...     n_theta=10,
...     n_radial=10,
...     frequency=Q_([90], "RPM"),
...     equilibrium_position_mode="calculate",
...     axial_load=13.320e6,
...     radial_inclination_angle=Q_(-2.75e-04, "rad"),
...     circumferential_inclination_angle=Q_(-1.70e-05, "rad"),
...     initial_film_thickness=Q_(0.2, "mm")
... )

Methods

C(frequency)#

Damping matrix for an instance of a bearing element.

This method returns the damping matrix for an instance of a bearing element.

Parameters:

frequencyfloat: The excitation frequency (rad/s).

Returns:

Cnp.ndarray: A 3x3 matrix of floats containing the cxx, cxy, cyx, cyy, and czz values (N*s/m).

Examples

>>> bearing = bearing_example()
>>> bearing.C(0)
array([[200.,   0.,   0.],
       [  0., 150.,   0.],
       [  0.,   0.,  50.]])

G()#

Gyroscopic matrix for an instance of a bearing element.

This method returns the mass matrix for an instance of a bearing element.

Returns:

Gnp.ndarray: A 3x3 matrix of floats.

Examples

>>> bearing = bearing_example()
>>> bearing.G()
array([[0., 0., 0.],
       [0., 0., 0.],
       [0., 0., 0.]])

K(frequency)#

Stiffness matrix for an instance of a bearing element.

This method returns the stiffness matrix for an instance of a bearing element.

Parameters:

frequencyfloat: The excitation frequency (rad/s).

Returns:

Knp.ndarray: A 3x3 matrix of floats containing the kxx, kxy, kyx, kyy and kzz values (N/m).

Examples

>>> bearing = bearing_example()
>>> bearing.K(0)
array([[1000000.,       0.,       0.],
       [      0.,  800000.,       0.],
       [      0.,       0.,  100000.]])

M(frequency)#

Mass matrix for an instance of a bearing element.

This method returns the mass matrix for an instance of a bearing element.

Parameters:

frequencyfloat: The excitation frequency (rad/s).

Returns:

Mnp.ndarray: Mass matrix (kg).

Examples

>>> bearing = bearing_example()
>>> bearing.M(0)
array([[0., 0., 0.],
       [0., 0., 0.],
       [0., 0., 0.]])

__init__(n, pad_inner_radius, pad_outer_radius, pad_pivot_radius, pad_arc_length, angular_pivot_position, oil_supply_temperature, lubricant, n_pad, n_theta, n_radial, frequency, equilibrium_position_mode, radial_inclination_angle, circumferential_inclination_angle, initial_film_thickness, tolerance_force_moment=0.1, residual_force_moment=50, model_type='thermo_hydro_dynamic', axial_load=None, **kwargs)#

coefficients()#

dof_local_index()#

Get the local index for a element specific degree of freedom.

Returns:

local_index: namedtupple: A named tuple containing the local index.

Examples

>>> # Example using BearingElement
>>> from ross.bearing_seal_element import bearing_example
>>> bearing = bearing_example()
>>> bearing.dof_local_index()
LocalIndex(x_0=0, y_0=1, z_0=2)

dof_mapping()#

Degrees of freedom mapping.

Returns a dictionary with a mapping between degree of freedom and its index.

Returns:

dof_mappingdict: A dictionary containing the degrees of freedom and their indexes.

Examples

The numbering of the degrees of freedom for each node.

Being the following their ordering for a node:

x_0 - horizontal translation y_0 - vertical translation z_0 - axial translation

>>> bearing = bearing_example()
>>> bearing.dof_mapping()
{'x_0': 0, 'y_0': 1, 'z_0': 2}

format_table(frequency=None, coefficients=None, frequency_units='rad/s', stiffness_units='N/m', damping_units='N*s/m', mass_units='kg')#

Return frequency vs coefficients in table format.

Parameters:

frequencyarray, pint.Quantity, optional: Array with frequencies (rad/s). Default is 5 values from min to max frequency.
coefficientslist, str, optional: List or str with the coefficients to include. Defaults is a list of stiffness and damping coefficients.
frequency_unitsstr, optional: Frequency units. Default is rad/s.
stiffness_unitsstr, optional: Stiffness units. Default is N/m.
damping_unitsstr, optional: Damping units. Default is N*s/m.
mass_unitsstr, optional: Mass units. Default is kg.

Returns:

tablePrettyTable object: Table object with bearing coefficients to be printed.

classmethod from_table(n, file, sheet_name=0, tag=None, n_link=None, scale_factor=1, color='#355d7a')#

Instantiate a bearing using inputs from an Excel table.

A header with the names of the columns is required. These names should match the names expected by the routine (usually the names of the parameters, but also similar ones). The program will read every row bellow the header until they end or it reaches a NaN.

Parameters:

nint: The node in which the bearing will be located in the rotor.
filestr: Path to the file containing the bearing parameters.
sheet_nameint or str, optional: Position of the sheet in the file (starting from 0) or its name. If none is passed, it is assumed to be the first sheet in the file.
tagstr, optional: A tag to name the element. Default is None.
n_linkint, optional: Node to which the bearing will connect. If None the bearing is connected to ground. Default is None.
scale_factorfloat, optional: The scale factor is used to scale the bearing drawing. Default is 1.
colorstr, optional: A color to be used when the element is represented. Default is ‘#355d7a’ (Cardinal).

Returns:

bearingrs.BearingElement: A bearing object.

Examples

>>> import os
>>> file_path = os.path.dirname(os.path.realpath(__file__)) + '/tests/data/bearing_seal_si.xls'
>>> BearingElement.from_table(0, file_path, n_link=1)
BearingElement(n=0, n_link=1,
 kxx=[1.379...

get_class_name_prefix(index=None)#

Extract prefix of the class name preceding ‘Element’, insert spaces before uppercase letters, and append an index number at the end.

Parameters:

indexint, optional: The index number to append at the end of the resulting string. Default is None.

Returns:

prefixstr: The processed class name prefix.

Examples

>>> # Example using BearingElement
>>> from ross.bearing_seal_element import bearing_example
>>> bearing = bearing_example()
>>> bearing.get_class_name_prefix()
'Bearing'

classmethod get_subclasses()#

classmethod load(file)#

plot(coefficients=None, frequency_units='rad/s', stiffness_units='N/m', damping_units='N*s/m', mass_units='kg', fig=None, **kwargs)#

Plot coefficient vs frequency.

Parameters:

coefficientslist, str: List or str with the coefficients to plot.
frequency_unitsstr, optional: Frequency units. Default is rad/s.
stiffness_unitsstr, optional: Stiffness units. Default is N/m.
damping_unitsstr, optional: Damping units. Default is N*s/m.
mass_unitsstr, optional: Mass units. Default is kg.
**kwargsoptional: Additional key word arguments can be passed to change the plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

Returns:

figPlotly graph_objects.Figure(): The figure object with the plot.

plot_results(show_plots=False, freq_index=0)#

Plot pressure and temperature field results for thrust bearing analysis.

This method generates comprehensive visualization plots for the calculated pressure and temperature fields at a specific frequency. It creates both 3D surface plots and 2D contour plots for visualization of the field properties distributions across the bearing pad.

Parameters:

show_plotsbool, optional: Whether to automatically display the plots. If True, attempts to show all plots using the default display method. If False, returns figure objects for manual display. Default is False.
freq_indexint, optional: Index of the frequency to plot results for. Must be within the range of calculated frequencies. Default is 0 (first frequency).

Returns:

dict: Dictionary containing four Plotly figure objects: - ‘pressure_3D’: 3D surface plot of pressure field - ‘temperature_3D’: 3D surface plot of temperature field - ‘pressure_2D’: 2D contour plot of pressure field - ‘temperature_2D’: 2D contour plot of temperature field

Notes

The method interpolates the field data using cubic interpolation for smoother contour plots. Coordinate transformation from polar to Cartesian coordinates is performed for visualization purposes.

classmethod read_toml_data(data)#

Read and parse data stored in a .toml or .json file.

Overrides the base Element method to pass extra saved keys (e.g. pre-computed coefficients) as kwargs to the constructor. This allows subclasses to skip expensive computation when coefficients are already available from a saved file.

Parameters:

datadict: Dictionary obtained from toml.load() or json.load().

Returns:

The element object.

record_optimization_residual(residual_value: float, iteration: int | None = None) → None#

Store the residual value for the current frequency.

If ‘iteration’ is provided, the value is placed at that index.
If ‘iteration’ is None, the value is appended.

Notes

Requires ‘self._current_freq_index’ to be set (done in the frequency loop).

run_thermo_hydro_dynamic()#

Execute the complete thermo-hydrodynamic analysis for the tilting pad thrust bearing.

This method performs the main computational sequence for analyzing a tilting pad thrust bearing, including pressure and temperature field calculations, equilibrium position determination, and dynamic coefficient computation for each operating frequency.

The analysis includes: - Initialization of field arrays (pressure, temperature, film thickness) - Iterative solution of Reynolds and energy equations - Calculation of hydrodynamic forces and moments - Computation of stiffness and damping coefficients - Optional display of results

Parameters:

None: This method uses the bearing parameters defined during initialization.

Attributes:

pressure_field_dimensionalndarray: Dimensional pressure field [Pa]. Shape: (n_radial+2, n_theta+2).
temperature_fieldndarray: Temperature field [°C]. Shape: (n_radial+2, n_theta+2).
pivot_film_thicknessfloat: Oil film thickness at pivot point [m].
max_thicknessfloat: Maximum oil film thickness [m].
min_thicknessfloat: Minimum oil film thickness [m].
kzzndarray: Axial stiffness coefficient [N/m]. Shape: (n_frequencies,).
czzndarray: Axial damping coefficient [N*s/m]. Shape: (n_frequencies,).
viscosity_fieldndarray: Viscosity field [Pa*s]. Shape: (n_radial, n_theta).

Returns:

None: Results are stored as instance attributes and optionally displayed.

Notes

The method processes each frequency in the frequency array sequentially. For each frequency, it: 1. Solves the pressure field using Reynolds equation with finite volume method 2. Solves the temperature field using energy equation considering viscous heating 3. Calculates dynamic coefficients using perturbation method 4. Stores results in instance attributes

The solution includes viscosity variation with temperature using exponential interpolation: μ = a * exp(b * T), where a and b are temperature-dependent coefficients calculated from lubricant properties.

Examples

>>> from ross.bearings.thrust_pad import thrust_pad_example
>>> bearing = thrust_pad_example()

save(file)#

Save the element in a .toml or .json file.

This function will save the element to a .toml or .json file. The file will have all the argument’s names and values that are needed to reinstantiate the element.

Parameters:

filestr, pathlib.Path: The name of the file the element will be saved in. The format is determined by the file extension (.toml or .json).

Examples

>>> # Example using DiskElement
>>> from tempfile import tempdir
>>> from pathlib import Path
>>> from ross.disk_element import disk_example
>>> # create path for a temporary file
>>> file = Path(tempdir) / 'disk.toml'
>>> disk = disk_example()
>>> disk.save(file)

show_coefficients_comparison()#

Display dynamic coefficients comparison table.

This method creates and displays a formatted table comparing dynamic coefficients (stiffness and damping) across different frequencies.

Parameters:

None: This method uses the frequency array and coefficients stored as instance attributes.

Returns:

None: Results are printed to the console in a formatted table.

show_execution_time()#

Display the simulation execution time.

This method calculates and displays the total time spent during the complete bearing analysis execution, including all frequency calculations.

Parameters:

None: This method uses the initial_time and final_time attributes stored during the simulation execution.

Returns:

float: Total simulation time in seconds. Returns None if simulation hasn’t been executed yet.

show_optimization_convergence(by: str = 'index', show_plots: bool = False) → None#

Display the optimization residuals per iteration for each processed frequency.

Parameters:

bystr: ‘index’ -> show frequencies by their index (default) ‘value’ -> show frequencies by their value (as stored in self.frequency)
show_plotsbool: Whether to show the convergence plot. Default is False.

Notes

Requires ‘self.optimization_history’ to be populated during the solve.

show_results()#

Display thrust bearing calculation results in a formatted table.

This method prints the main results from the thrust bearing analysis using PrettyTable, including operating conditions, field results, load information, and dynamic coefficients for each frequency.

Parameters:

None: This method uses the bearing parameters and results stored as instance attributes.

Returns:

None: Results are printed to the console in a formatted table.

solve_fields()#

Solve pressure and temperature fields iteratively until convergence.

This method performs the main iterative solution loop for thrust pad bearing analysis, solving the coupled pressure-temperature-viscosity problem. The method iterates between equilibrium position optimization and field equations until convergence criteria are met.

The solution process consists of two nested loops:

1. Outer Loop (Force-Moment Convergence): - Minimizes residual forces and moments to find equilibrium position - Updates pad inclination angles and film thickness - Uses scipy.optimize.fmin with Nelder-Mead method - Mode-dependent optimization:

‘imposed’: Film thickness is fixed, only angles are optimized

‘calculate’: Film thickness, radial and circumferential angles are optimized

2. Inner Loop (Viscosity Convergence): - Solves temperature field using energy equation - Updates viscosity field based on temperature-dependent viscosity model - Iterates until viscosity variation is below tolerance - Uses finite volume method with upwind convection scheme

For each iteration, the method:

Calculates pressure field using Reynolds equation with boundary conditions
Computes pressure gradients (dp/dr and dp/dtheta) at all control volumes
Solves energy equation for temperature field considering viscous heating
Updates viscosity using exponential model: μ = a * exp(b * T)
Computes hydrodynamic forces, moments, and residuals
Checks convergence of both force/moment balance and viscosity variation

The method modifies instance attributes including pressure_field_dimensional, temperature_field, viscosity_field, pivot_film_thickness, and film thickness arrays. Final results are stored for coefficient calculation and visualization.

Convergence Criteria:

Force-moment residual < tolerance_force_moment (default: 50 N or N*m)
Viscosity variation < viscosity_convergence_tolerance (default: 1e-5)

Optimization Parameters:

‘imposed’ mode: xtol=1, ftol=1, maxiter=100000
‘calculate’ mode: xtol=0.1, ftol=0.1, maxiter=100

ross.ThrustPad

Contents

ross.ThrustPad#