ross.TiltingPad

ross.TiltingPad#

class ross.TiltingPad(n, journal_diameter, pre_load, pad_thickness, pad_arc, offset, pad_axial_length, lubricant, oil_supply_temperature, radial_clearance, pivot_angle, frequency, nx=30, nz=30, n_link=None, xj=None, yj=None, equilibrium_type=None, eccentricity=0.3, attitude_angle=4.71238898038469, load=None, initial_pads_angles=None, model_type='thermo_hydro_dynamic', solver_options=None, **kwargs)#

Tilting-pad journal bearing - Thermo-Hydro-Dynamic (THD) model.

This class provides a comprehensive numerical model for tilting-pad journal bearings using thermo-hydro-dynamic (THD) analysis. Each pad is treated independently 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 difference method on a structured grid (nx × nz) - Accounts for pad rotation and journal motion - Enforces zero pressure at pad edges (cavitation boundary) - Viscosity varies spatially due to temperature field
Energy Equation (for temperature field): - 2D finite difference 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 journal equilibrium position - Two modes: match specified eccentricity or determine complete equilibrium - Minimizes pad moment imbalance using Nelder-Mead optimization (fmin) - Each pad rotates independently about its pivot point
Dynamic Coefficients (stiffness and damping): - Uses virtual perturbations of displacements and speeds to determine the coefficients - Applies small perturbations to journal position (0.5% of clearance) - Applies small perturbations to journal velocity (2.5% of operating speed) - Solves complete THD problem for each perturbation state - Extracts coefficients from force differences

For reference check [Barbosa, 2018], [Heinrichson et al., 2007] and [Nicoletti, 1999].

Parameters:

nint

Node in which the bearing will be located.

journal_diameterfloat

Journal diameter. Default unit is meter.

pre_loadarray_like

Pre-load factor for each pad. Dimensionless.

pad_thicknessfloat

Pad thickness. Default unit is meter.

pad_arcarray_like

Individual pad arc angle for each pad. Default unit is degrees.

offsetarray_like

Pivot offset for each pad. Dimensionless (0.5 = centered).

pad_axial_lengtharray_like

Pad axial length for each pad. Default unit is meter.

lubricantstr or dict

Lubricant type. Can be: - ‘ISOVG32’ - ‘ISOVG46’ - ‘ISOVG68’ Or a dictionary with lubricant properties.

oil_supply_temperaturefloat

Oil supply temperature. Default unit is °C.

radial_clearancefloat

Radial clearance. Default unit is meter.

pivot_anglearray_like

Pivot angle for each pad. Default unit is degrees.

frequencyarray_like

Operating frequencies. Default unit is RPM.

nxint, optional

Number of volumes along the circumferential direction. Default is 30.

nzint, optional

Number of volumes along the axial direction. Default is 30.

n_linkint, optional

Node to which the bearing will connect. If None the bearing is connected to ground.

xjfloat, optional

Journal position in X direction. Default unit is meter.

yjfloat, optional

Journal position in Y direction. Default unit is meter.

equilibrium_typestr, optional

Type of equilibrium calculation. Options: - ‘match_eccentricity’: Uses the provided eccentricity and attitude_angle and optimizes only the pad rotation angles. - ‘determine_eccentricity’: Optimizes eccentricity, attitude_angle, and pad rotation angles to balance the applied loads; requires load to be provided.

model_typestr, optional

Type of model to be used. Options: - ‘thermo_hydro_dynamic’: Thermo-Hydro-Dynamic model

eccentricityfloat, optional

Eccentricity ratio. Dimensionless.

attitude_anglefloat, optional

Attitude angle. Default unit is degrees.

loadarray_like, optional

External loads applied to the journal. Must be a list or array with two elements [fx, fy], where fx is the load in X direction and fy is the load in Y direction. Default unit is Newton. Required when equilibrium_type is ‘determine_eccentricity’.

initial_pads_anglesarray_like, optional

Initial pad angles. Default unit is radians.

solver_optionsdict, optional

Options for the Nelder-Mead optimization solver used in equilibrium calculation. Keys (SciPy fmin convention): - ‘xtol’ : float

Convergence tolerance for solution parameters (eccentricity, attitude angle, pad angles). Solver stops when parameter changes between iterations fall below this value. Default is 1e-3.

‘ftol’float
Convergence tolerance for the objective function (force and moment residuals). Solver stops when objective change falls below this value. Default is 1e-3.
‘maxiter’int
Maximum number of iterations allowed. Default is 1000.

If None, uses default values: {"xtol": 1e-3, "ftol": 1e-3, "maxiter": 1000}.

**kwargsdict, optional

Additional keyword arguments.

Attributes:

kxx, kyy, kxy, kyxfloat: Stiffness coefficients in N/m. Shape: (n_freq,).
cxx, cyy, cxy, cyxfloat: Damping coefficients in N·s/m. Shape: (n_freq,).
pressure_dimarray: Dimensional pressure field in Pa.
temperature_initarray: Temperature field in °C.
force_x_dim, force_y_dimarray: Dimensional forces in N.
moment_j_dimarray: Dimensional moments in N·m.
maxPfloat: Maximum pressure in Pa.
maxTfloat: Maximum temperature in °C.
h_pivotfloat: Oil film thickness at pivot point in m.
eccfloat: Eccentricity ratio.

Returns:

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

References

[Bar18]

Jefferson Silva Barbosa. Determinação da posição de equilíbrio em mancais hidrodinâmicos cilíndricos usando o algoritmo de evolução diferencial. REVISTA CEREUS, 2018.

[HSF07]

Niels Heinrichson, Ilmar Ferreira Santos, and Axel Fuerst. The influence of injection pockets on the performance of tilting-pad thrust bearings—part i: theory. Journal of Tribology, 129(4):895–903, 06 2007. URL: https://doi.org/10.1115/1.2768609, arXiv:https://asmedigitalcollection.asme.org/tribology/article-pdf/129/4/895/5824595/895_1.pdf, doi:10.1115/1.2768609.

[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.tilting_pad import TiltingPad
>>> from ross.units import Q_
>>> bearing = TiltingPad(
...     n=1,
...     frequency=Q_([3000], "RPM"),
...     equilibrium_type="match_eccentricity",
...     journal_diameter=101.6e-3,
...     radial_clearance=74.9e-6,
...     pad_thickness=12.7e-3,
...     pivot_angle=Q_([18, 90, 162, 234, 306], "deg"),
...     pad_arc=Q_([60]*5, "deg"),
...     pad_axial_length=Q_([50.8e-3]*5, "m"),
...     pre_load=[0.5]*5,
...     offset=[0.5]*5,
...     lubricant="ISOVG32",
...     oil_supply_temperature=Q_(40, "degC"),
...     eccentricity=0.35,
...     attitude_angle=Q_(287.5, "deg"),
...     load = [8.8405e+02, -2.6704e+03],
... )

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, journal_diameter, pre_load, pad_thickness, pad_arc, offset, pad_axial_length, lubricant, oil_supply_temperature, radial_clearance, pivot_angle, frequency, nx=30, nz=30, n_link=None, xj=None, yj=None, equilibrium_type=None, eccentricity=0.3, attitude_angle=4.71238898038469, load=None, initial_pads_angles=None, model_type='thermo_hydro_dynamic', solver_options=None, **kwargs)#

coefficients()#

Calculate dynamic stiffness and damping coefficients for the tilting pad bearing.

This method computes the dynamic coefficients (stiffness and damping) of the tilting pad bearing using a perturbation approach. The coefficients are determined by applying small perturbations to the journal position and velocity and calculating the resulting force changes.

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'

get_equilibrium_position(x)#

Calculate the equilibrium position for a single pad.

This method serves as the objective function for optimization algorithms to find the equilibrium position of a tilting pad. It performs a complete thermo-hydrodynamic analysis and returns the absolute moment value.

Parameters:

xfloat: Pad rotation angle [rad] to be evaluated.

Returns:

float: Absolute value of the dimensional moment [N·m] acting on the pad.

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_contourP(x_data, y_data, z_data, z_title)#

This method plots a contour(x,y,z) graph.

Parameters:

x_datafloat: X axis data.
y_datafloat: Y axis data.
z_datafloat: Z axis data.
z_titlestr: Name of the z axis

Returns:

figobject: Contour figure.

plot_contourT(x_data, y_data, z_data, z_title)#

This method plots a contour(x,y,z) graph.

Parameters:

x_datafloat: X axis data.
y_datafloat: Y axis data.
z_datafloat: Z axis data.
z_titlestr: Name of the z axis

Returns:

figobject: Contour figure.

plot_pad_results(fig=None, **kwargs)#

Plot pad results including forces and moments.

Parameters:

figPlotly graph_objects.Figure(): The figure object with the plot.
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_pressure_distribution(fig=None, **kwargs)#

Plot pressure distribution for the tilting pad bearing.

Parameters:

figPlotly graph_objects.Figure(): The figure object with the plot.
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 tilting pad bearing analysis.

This method generates comprehensive visualization plots for the calculated pressure and temperature fields at a specific frequency. It creates scatter plots and contour plots for pressure and temperature distributions across all pads.

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_scatter’: Scatter plot of pressure distribution - ‘temperature_scatter’: Scatter plot of temperature distribution - ‘pressure_2D’: 2D contour plot of pressure field - ‘temperature_2D’: 2D contour plot of temperature field

Notes

The method creates visualizations for all pads showing the pressure and temperature distributions in both scatter and contour formats for the selected frequency.

plot_scatter(x_data, y_data, pos, y_title)#

This method plots a scatter(x,y) graph.

Parameters:

x_datafloat: X axis data.
y_datafloat: Y axis data.
posfloat: Probe position.
y_titlestr: Name of the Y axis

Returns:

figobject: Scatter figure.

plot_temperature_distribution(fig=None, **kwargs)#

Plot temperature distribution for the tilting pad bearing.

Parameters:

figPlotly graph_objects.Figure(): The figure object with the plot.
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.

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.

Parameters:

residual_valuefloat: Residual value to be stored.
iterationint, optional: Iteration index. If None, the value is appended.

Returns:

None: The residual value is stored in the optimization history.

run_thermo_hydro_dynamic()#

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

This method performs the main computational sequence for analyzing a tilting pad journal 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 for each frequency - Calculation of hydrodynamic forces and moments - Computation of stiffness and damping coefficients

Parameters:

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

Attributes:

pressure_dimndarray: Dimensional pressure field for all pads [Pa]. Shape: (nz, nx, n_pad).
temperature_initndarray: Temperature field for all pads [°C]. Shape: (nz, nx, n_pad).
h_pivotndarray: Oil film thickness at pivot point for each pad [m]. Shape: (n_pad,).
kxx, kyy, kxy, kyxfloat: Stiffness coefficients [N/m].
cxx, cyy, cxy, cyxfloat: Damping coefficients [N·s/m].
force_x_dim, force_y_dimndarray: Dimensional forces in X and Y directions [N]. Shape: (n_pad,).
moment_j_dimndarray: Dimensional moments [N·m]. Shape: (n_pad,).

Returns:

None: Results are stored as instance attributes and plots are generated.

Notes

The method processes each frequency in the frequency array sequentially. For each frequency, it: 1. Initializes field arrays and dimensionless parameters 2. Solves the thermo-hydrodynamic equations to find equilibrium 3. Calculates dynamic coefficients using perturbation methods 4. Updates the parent BearingElement with computed coefficients 5. Generates visualization plots

The analysis assumes steady-state operation and uses finite difference methods for solving the governing equations.

Examples

>>> from ross.bearings.tilting_pad import tilting_pad_example
>>> bearing = tilting_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 tilting pad bearing calculation results in a formatted table.

This method prints the main results from the tilting pad 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 the thermo-hydrodynamic equations to determine equilibrium position and field distributions.

This method performs the complete thermo-hydrodynamic analysis for tilting pad bearings, including equilibrium position calculation and field solution for pressure and temperature.

The method supports two equilibrium calculation types: - ‘match_eccentricity’: Imposes eccentricity and optimizes only pad angles - ‘determine_eccentricity’: Determines complete equilibrium position including eccentricity

For each pad, the method solves: 1. Reynolds equation for pressure field using finite difference method 2. Energy equation for temperature field with turbulent viscosity modeling 3. Iterative convergence between pressure and temperature fields

Parameters:

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

Returns:

tuple

A tuple containing the following results: - max_p : float

Maximum pressure in Pa

med_pfloat
Mean pressure in Pa
max_tfloat
Maximum temperature in °C
med_tfloat
Mean temperature in °C
h_pivotfloat
Oil film thickness at pivot point in m
eccfloat
Eccentricity ratio (dimensionless)

ross.TiltingPad

Contents

ross.TiltingPad#