ross.ModalResults#

class ross.ModalResults(speed, evalues, evectors, wn, wd, damping_ratio, log_dec, ndof, nodes, nodes_pos, shaft_elements_length, number_dof)#

Class used to store results and provide plots for Modal Analysis.

Two options for plottting are available: plot_mode3D (mode shape 3D view) and plot_mode2D (mode shape 2D view). The user chooses between them using the respective methods.

Parameters:
speedfloat

Rotor speed.

evaluesarray

Eigenvalues array.

evectorsarray

Eigenvectors array.

wnarray

Undamped natural frequencies array.

wdarray

Damped natural frequencies array.

log_decarray

Logarithmic decrement for each mode.

damping_ratioarray

Damping ratio for each mode.

ndofint

Number of degrees of freedom.

nodeslist

List of nodes number.

nodes_poslist

List of nodes positions.

shaft_elements_lengthlist

List with Rotor shaft elements lengths.

Methods

__init__(speed, evalues, evectors, wn, wd, damping_ratio, log_dec, ndof, nodes, nodes_pos, shaft_elements_length, number_dof)#
data_mode(mode=None, length_units='m', frequency_units='rad/s', damping_parameter='log_dec')#

Return the mode shapes in DataFrame format.

Parameters:
modeint

The n’th vibration mode

length_unitsstr, optional

length units. Default is ‘m’.

damping_parameterstr, optional

Define which value to show for damping. We can use “log_dec” or “damping_ratio”. Default is “log_dec”.

Returns:
dfpd.DataFrame

DataFrame storing mode shapes data arrays.

kappa(node, w, wd=True)#

Calculate kappa for a given node and natural frequency.

frequency is the the index of the natural frequency of interest. The function calculates the orbit parameter \(\kappa\):

\[\kappa = \pm \sqrt{\lambda_2 / \lambda_1}\]

Where \(\sqrt{\lambda_1}\) is the length of the semiminor axes and \(\sqrt{\lambda_2}\) is the length of the semimajor axes.

If \(\kappa = \pm 1\), the orbit is circular.

If \(\kappa\) is positive we have a forward rotating orbit and if it is negative we have a backward rotating orbit.

Parameters:
node: int

Node for which kappa will be calculated.

w: int

Index corresponding to the natural frequency of interest.

wd: bool

If True, damping natural frequencies are used.

Default is true.

Returns:
kappa: dict

A dictionary with values for the natural frequency, major axis, minor axis and kappa.

kappa_mode(w)#

Evaluate kappa values.

This function evaluates kappa given the index of the natural frequency of interest. Values of kappa are evaluated for each node of the corresponding frequency mode.

Parameters:
w: int

Index corresponding to the natural frequency of interest.

Returns:
kappa_mode: list

A list with the value of kappa for each node related to the mode/natural frequency of interest.

classmethod load(file)#

Load results from a .toml file.

This function will load the simulation results from a .toml file. The file must have all the argument’s names and values that are needed to reinstantiate the class.

Parameters:
filestr, pathlib.Path

The name of the file the results will be loaded from.

Examples

>>> # Example running a stochastic unbalance response
>>> from tempfile import tempdir
>>> from pathlib import Path
>>> import ross as rs
>>> # Running an example
>>> rotor = rs.rotor_example()
>>> freq_range = np.linspace(0, 500, 31)
>>> n = 3
>>> m = 0.01
>>> p = 0.0
>>> results = rotor.run_unbalance_response(n, m, p, freq_range)
>>> # create path for a temporary file
>>> file = Path(tempdir) / 'unb_resp.toml'
>>> results.save(file)
>>> # Loading file
>>> results2 = rs.ForcedResponseResults.load(file)
>>> abs(results2.forced_resp).all() == abs(results.forced_resp).all()
True
plot_mode_2d(mode=None, fig=None, orientation='major', frequency_type='wd', title=None, length_units='m', frequency_units='rad/s', damping_parameter='log_dec', **kwargs)#

Plot (2D view) the mode shapes.

Parameters:
modeint

The n’th vibration mode

figPlotly graph_objects.Figure()

The figure object with the plot.

orientationstr, optional

Orientation can be ‘major’, ‘x’ or ‘y’. Default is ‘major’ to display the major axis.

frequency_typestr, optional

“wd” calculates the damped natural frequencies. “wn” calculates the undamped natural frequencies. Defaults is “wd”.

titlestr, optional

A brief title to the mode shape plot, it will be displayed above other relevant data in the plot area. It does not modify the figure layout from Plotly.

length_unitsstr, optional

length units. Default is ‘m’.

frequency_unitsstr, optional

Frequency units that will be used in the plot title. Default is rad/s.

damping_parameterstr, optional

Define which value to show for damping. We can use “log_dec” or “damping_ratio”. Default is “log_dec”.

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_mode_3d(mode=None, frequency_type='wd', title=None, length_units='m', phase_units='rad', frequency_units='rad/s', damping_parameter='log_dec', fig=None, **kwargs)#

Plot (3D view) the mode shapes.

Parameters:
modeint

The n’th vibration mode Default is None

frequency_typestr, optional

“wd” calculates de map for the damped natural frequencies. “wn” calculates de map for the undamped natural frequencies. Defaults is “wd”.

titlestr, optional

A brief title to the mode shape plot, it will be displayed above other relevant data in the plot area. It does not modify the figure layout from Plotly.

length_unitsstr, optional

length units. Default is ‘m’.

phase_unitsstr, optional

Phase units. Default is “rad”

frequency_unitsstr, optional

Frequency units that will be used in the plot title. Default is rad/s.

damping_parameterstr, optional

Define which value to show for damping. We can use “log_dec” or “damping_ratio”. Default is “log_dec”.

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_orbit(mode=None, nodes=None, fig=None, frequency_type='wd', title=None, frequency_units='rad/s', **kwargs)#

Plot (2D view) the mode shapes.

Parameters:
modeint

The n’th vibration mode Default is None

nodesint, list(ints)

Int or list of ints with the nodes selected to be plotted.

figPlotly graph_objects.Figure()

The figure object with the plot.

frequency_typestr, optional

“wd” calculates de map for the damped natural frequencies. “wn” calculates de map for the undamped natural frequencies. Defaults is “wd”.

titlestr, optional

A brief title to the mode shape plot, it will be displayed above other relevant data in the plot area. It does not modify the figure layout from Plotly.

frequency_unitsstr, optional

Frequency units that will be used in the plot title. Default is rad/s.

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

The data passed to this method needs to be according to the format saved in the .toml file by the .save() method.

Parameters:
datadict

Dictionary obtained from toml.load().

Returns:
The result object.
save(file)#

Save results in a .toml file.

This function will save the simulation results to a .toml file. The file will have all the argument’s names and values that are needed to reinstantiate the class.

Parameters:
filestr, pathlib.Path

The name of the file the results will be saved in.

Examples

>>> # Example running a unbalance response
>>> from tempfile import tempdir
>>> from pathlib import Path
>>> import ross as rs
>>> # Running an example
>>> rotor = rs.rotor_example()
>>> speed = np.linspace(0, 1000, 101)
>>> response = rotor.run_unbalance_response(node=3,
...                                         unbalance_magnitude=0.001,
...                                         unbalance_phase=0.0,
...                                         frequency=speed)
>>> # create path for a temporary file
>>> file = Path(tempdir) / 'unb_resp.toml'
>>> response.save(file)
static whirl(kappa_mode)#

Evaluate the whirl of a mode.

Parameters:
kappa_modelist

A list with the value of kappa for each node related to the mode/natural frequency of interest.

Returns:
whirldirstr

A string indicating the direction of precession related to the kappa_mode.

whirl_direction()#

Get the whirl direction for each frequency.

Returns:
whirl_warray

An array of strings indicating the direction of precession related to the kappa_mode. Backward, Mixed or Forward depending on values of kappa_mode.

whirl_values()#

Get the whirl value (0., 0.5, or 1.) for each frequency.

Returns:
whirl_to_cmap

0.0 - if the whirl is Forward 0.5 - if the whirl is Mixed 1.0 - if the whirl is Backward

Attributes

whirl_to_cmap