# ross.ModalResults¶

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

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

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)
>>> results2 = rs.ForcedResponseResults.load(file)
>>> abs(results2.forced_resp).all() == abs(results.forced_resp).all()
True

plot_mode_2d(mode=None, fig=None, 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.

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.

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

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