ross.PlainJournal

ross.PlainJournal#

class ross.PlainJournal(n, axial_length, journal_radius, radial_clearance, elements_circumferential, elements_axial, n_pad, pad_arc_length, preload, geometry, reference_temperature, frequency, fxs_load, fys_load, groove_factor, lubricant, sommerfeld_type=2, initial_guess=[0.1, -0.1], method='perturbation', model_type='thermo_hydro_dynamic', operating_type='flooded', oil_supply_pressure=None, oil_flow_v=None, **kwargs)#

Plain journal bearing - Advanced thermo-hydro-dynamic model.

This class provides a comprehensive numerical bearing model for detailed design and optimization. Solves full Reynolds equation with thermal effects on a discretized grid to calculate pressure, temperature fields, and bearing coefficients.

When to use this class: - Detailed bearing design and optimization - Thermo-hydro-dynamic (THD) analysis - Complex bearing geometries (circular, lobe, elliptical) - Multi-pad configurations with preload - High-speed applications requiring turbulence models - Oil starvation or flooded conditions - When accuracy is more important than computational speed

For quick calculations and preliminary design, consider using CylindricalBearing instead, which provides: - Fast analytical solutions - Simple geometry assumptions - Closed-form coefficients

The basic references for the code are found in Barbosa [2018], Daniel [2012] and Nicoletti [1999].

Parameters:

Bearing Geometry
^^^^^^^^^^^^^^^^
Describes the geometric characteristics.
nint: Node in which the bearing will be located.
axial_lengthfloat, pint.Quantity: Bearing length. Default unit is meter.
journal_radiusfloat: Rotor radius. The unit is meter.
radial_clearancefloat: Radial clearence between rotor and bearing. The unit is meter.
n_padinteger: Number of pads that compound the bearing surface.
pad_arc_lengthfloat: Arc length of each pad. The unit is degree.
preload: float: Preload of the pad. The preload is defined as m=1-Cb/Cp where Cb is the radail clearance and Cp is the pad ground-in clearance.Preload is dimensionless.
geometry: string: Refers to bearing geometry. The options are: ‘circular’, ‘lobe’ or ‘elliptical’.
initial_guessarray: Array with eccentricity ratio and attitude angle
methodstring: Choose the method to calculate the dynamics coefficients. Options are: - ‘lund’ - ‘perturbation’
model_typestr, optional: Type of model to be used. Options: - ‘thermo_hydro_dynamic’: Thermo-Hydro-Dynamic model
Operation conditions
^^^^^^^^^^^^^^^^^^^^
Describes the operation conditions of the bearing.
frequencylist, pint.Quantity: Array with the frequencies (rad/s).
fxs_loadfloat, pint.Quantity: Load in X direction. The unit is newton.
fys_loadfloat, pint.Quantity: Load in Y direction. The unit is newton.
operating_typestring: Choose the operating condition that bearing is operating. - ‘flooded’ - ‘starvation’
Fluid properties
^^^^^^^^^^^^^^^^^
Describes the fluid characteristics.
lubricantstr, dict: Lubricant type. Can be: - ‘ISOVG46’ (lubricants in ross.bearings.lubricants)
reference_temperaturefloat: Oil reference temperature. The unit is celsius.
groove_factorlist, numpy array, tuple or float: Ratio of oil in reservoir temperature that mixes with the circulating oil. Is required one factor per segment.
oil_flow_v: float, pint.Quantity: Suply oil flow to bearing. Only used when operating type ‘starvation’ is selected. Default unit is meter**3/second
oil_supply_pressure: float, Pint.Quantity: Suply oil pressure that bearing receives at groove regions. Only used when operating type ‘starvation’ is selected. Unit is Pascal (Pa).
Turbulence Model
^^^^^^^^^^^^^^^^
Turbulence model to improve analysis in higher speed.The model represents
the turbulence by eddy diffusivities. The basic reference is found in :cite:t:`suganami1979`
ReynArray: The Reynolds number is a dimensionless number used to calculate the fluid flow regime inside the bearing.
delta_turbfloat: Eddy viscosity scaling factor. Coefficient to assign weight to laminar, transitional and turbulent flows to calculate viscosity.
Mesh discretization
^^^^^^^^^^^^^^^^^^^
Describes the discretization of the bearing.
elements_circumferentialint: Number of volumes along the direction theta (direction of flow).
elements_axialint: Number of volumes along the Z direction (axial direction).

Attributes:

Pdimarray: Dimensional pressure field. The unit is pascal.
dPdzarray: Differential pressure field in z direction.
dPdyarray: Differential pressure field in theta direction.
Tdimarray: Dimensional temperature field. The unit is celsius.
Fhxfloat: Force in X direction. The unit is newton.
Fhyfloat: Force in Y direction. The unit is newton.
equilibrium_posarray: Array with excentricity ratio and attitude angle information. Its shape is: array([excentricity, angle])

Returns:

A PlainJournal object.

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.

[Dan12]

G Daniel. Desenvolvimento de um modelo termodinâmico para análise em mancais segmentados. Universidade Estadual de Campinas, 2012.

[LT78]

JW Lund and KK Thomsen. A calculation method and data for the dynamic coefficients of oil-lubricated journal bearings. Topics in fluid film bearing and rotor bearing system design and optimization, 1978.

[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.

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, axial_length, journal_radius, radial_clearance, elements_circumferential, elements_axial, n_pad, pad_arc_length, preload, geometry, reference_temperature, frequency, fxs_load, fys_load, groove_factor, lubricant, sommerfeld_type=2, initial_guess=[0.1, -0.1], method='perturbation', model_type='thermo_hydro_dynamic', operating_type='flooded', oil_supply_pressure=None, oil_flow_v=None, **kwargs)#

coefficients(speed)#

Calculates the dynamic coefficients of stiffness “k” and damping “c”. Basic reference is found at Lund and Thomsen [1978]

Parameters:

speedfloat, pint.Quantity: Rotational speed to evaluate coefficients. The unit is rad/s.

Returns:

coeffstuple: Bearing stiffness and damping coefficients. Its shape is: ((kxx, kxy, kyx, kyy), (cxx, cxy, cyx, cyy))

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.

[Dan12]

G Daniel. Desenvolvimento de um modelo termodinâmico para análise em mancais segmentados. Universidade Estadual de Campinas, 2012.

[LT78]

JW Lund and KK Thomsen. A calculation method and data for the dynamic coefficients of oil-lubricated journal bearings. Topics in fluid film bearing and rotor bearing system design and optimization, 1978.

[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.

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_bearing_representation(fig=None, rotation=90, **kwargs)#

Plot the bearing representation.

Parameters:

rotation: float: The default it is 90 degrees.
subplotsPlotly graph_objects.make_subplots(): The figure object with the plot.
kwargsoptional: Additional key word arguments can be passed to change the plot layout only (e.g. plot_bgcolor=”white”, …). *See Plotly Python make_subplot Reference for more information.

Returns:

The figure object with the plot.

plot_pressure_distribution(axial_element_index=None, fig=None, **kwargs)#

Plot pressure distribution.

Parameters:

axial_element_indexint, optional: Show pressure distribution on bearing for the respective axial element. Default is the element closest to the middle of the bearing.
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)#

Plot pressure and temperature fields for the plain journal analysis.

Returns a dict with: - ‘pressure_3d’: 3D surface (theta vs z) - ‘temperature_3d’: 3D surface (theta vs z) - ‘pressure_2d’: 2D contour (theta vs z) - ‘temperature_2d’: 2D contour (theta vs z)

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.

run_thermo_hydro_dynamic(speed)#: This method runs the optimization to find the equilibrium position of the rotor’s center.

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 for all speeds.

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 = 'value', show_plots: bool = False) → None#

Display the optimization residuals per iteration for each processed speed.

Parameters:

bystr: ‘index’ -> show speeds by their index in self.frequency ‘value’ -> show speeds by their numeric value (RPM)
show_plotsbool: Whether to show the convergence plot. Default is False.

show_results()#

Display plain journal bearing calculation results for all speeds.

Prints a formatted table for each speed in self.frequency.

sommerfeld(speed, force_x, force_y)#

Calculate the sommerfeld number. This dimensionless number is used to calculate the dynamic coeficients.

Parameters:

speedfloat: Rotor speed. The unit is rad/s.
force_xfloat: Force in x direction. The unit is newton.
force_yfloat: Force in y direction. The unit is newton.

Returns:

Ssfloat: Sommerfeld number.

summary()#

Present a summary for the element.

A pandas series with the element properties as variables.

Returns:

A pandas series.

Examples

>>> # Example using DiskElement
>>> from ross.disk_element import disk_example
>>> disk = disk_example()
>>> disk.summary()
n                             0
n_l                           0
n_r                           0...

classmethod table_to_toml(n, file)#

Convert bearing parameters to toml.

Convert a table with parameters of a bearing element to a dictionary ready to save to a toml file that can be later loaded by ross.

Parameters:

nint: The node in which the bearing will be located in the rotor.
filestr: Path to the file containing the bearing parameters.

Returns:

datadict: A dict that is ready to save to toml and readable by ross.

Examples

>>> import os
>>> file_path = os.path.dirname(os.path.realpath(__file__)) + '/tests/data/bearing_seal_si.xls'
>>> BearingElement.table_to_toml(0, file_path)
{'n': 0, 'kxx': array([...

ross.PlainJournal

Contents

ross.PlainJournal#