ross.ForcedResponseResults

class ross.ForcedResponseResults(rotor, forced_resp, velc_resp, accl_resp, speed_range, unbalance=None)

Class used to store results and provide plots for Forced Response analysis.

Parameters
rotorross.Rotor object

The Rotor object

force_resparray

Array with the forced response (displacement) for each node for each frequency.

velc_resparray

Array with the forced response (velocity) for each node for each frequency.

accl_resparray

Array with the forced response (acceleration) for each node for each frequency.

speed_rangearray

Array with the frequencies.

unbalancearray, optional

Array with the unbalance data (node, magnitude and phase) to be plotted with deflected shape. This argument is set only if running an unbalance response analysis. Default is None.

Returns
subplotsPlotly graph_objects.make_subplots()

Plotly figure with Amplitude vs Frequency and Phase vs Frequency plots.

Methods

__init__(rotor, forced_resp, velc_resp, accl_resp, speed_range, unbalance=None)
data_magnitude(probe, probe_units='rad', frequency_units='rad/s', amplitude_units='m')

Return the forced response (magnitude) in DataFrame format.

Parameters
probelist

List with tuples (node, orientation angle, tag).

node : int -> Indicate the node where the probe is located.

orientation : float -> Probe orientation angle about the shaft. The 0 refers to +X direction. The strings ‘major’ and ‘minor’ can also be used to reference the major and minor axis.

tag : str, optional -> Probe tag to be add a DataFrame column title.

probe_unitsstr, option

Units for probe orientation. Default is “rad”.

frequency_unitsstr, optional

Units for the frequency range. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

Returns
dfpd.DataFrame

DataFrame storing magnitude data arrays. The columns are set based on the probe’s tag.

data_phase(probe, probe_units='rad', frequency_units='rad/s', amplitude_units='m', phase_units='rad')

Return the forced response (phase) in DataFrame format.

Parameters
probelist

List with tuples (node, orientation angle, tag).

node : int -> Indicate the node where the probe is located.

orientation : float -> Probe orientation angle about the shaft. The 0 refers to +X direction. The strings ‘major’ and ‘minor’ can also be used to reference the major and minor axis.

tag : str, optional -> Probe tag to be add a DataFrame column title.

probe_unitsstr, option

Units for probe orientation. Default is “rad”.

frequency_unitsstr, optional

Units for the x axis. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

phase_unitsstr, optional

Units for the x axis. Default is “rad”

Returns
dfpd.DataFrame

DataFrame storing phase data arrays. They columns are set based on the probe’s tag.

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(probe, probe_units='rad', frequency_units='rad/s', amplitude_units='m', phase_units='rad', mag_kwargs=None, phase_kwargs=None, polar_kwargs=None, subplot_kwargs=None)

Plot forced response.

This method returns a subplot with:
  • Frequency vs Amplitude;

  • Frequency vs Phase Angle;

  • Polar plot Amplitude vs Phase Angle;

Parameters
probelist

List with tuples (node, orientation angle, tag).

node : int -> Indicate the node where the probe is located.

orientation : float -> Probe orientation angle about the shaft. The 0 refers to +X direction. The strings ‘major’ and ‘minor’ can also be used to reference the major and minor axis.

tag : str, optional -> Probe tag to be add a DataFrame column title.

probe_unitsstr, option

Units for probe orientation. Default is “rad”.

frequency_unitsstr, optional

Frequency units. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

phase_unitsstr, optional

Phase units. Default is “rad”

mag_kwargsoptional

Additional key word arguments can be passed to change the magnitude plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

phase_kwargsoptional

Additional key word arguments can be passed to change the phase plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

polar_kwargsoptional

Additional key word arguments can be passed to change the polar plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

subplot_kwargsoptional

Additional key word arguments can be passed to change the plot layout only (e.g. width=1000, height=800, …). This kwargs override “mag_kwargs” and “phase_kwargs” dictionaries. *See Plotly Python Figure Reference for more information.

Returns
subplotsPlotly graph_objects.make_subplots()

Plotly figure with Amplitude vs Frequency and Phase vs Frequency and polar Amplitude vs Phase plots.

plot_bending_moment(speed, frequency_units='rad/s', moment_units='N*m', rotor_length_units='m', fig=None, **kwargs)

Plot the bending moment diagram.

Parameters
speedfloat

The rotor rotation speed. Must be an element from the speed_range argument passed to the class (rad/s).

frequency_unitsstr, optional

Frequency units. Default is “rad/s”

moment_unitsstr, optional

Moment units. Default is ‘N*m’.

rotor_length_unitsstr

Rotor Length units. Default is m.

figPlotly graph_objects.Figure()

The figure object with the plot.

kwargsoptional

Additional key word arguments can be passed to change the deflected shape 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_deflected_shape(speed, samples=101, frequency_units='rad/s', amplitude_units='m', rotor_length_units='m', moment_units='N*m', shape2d_kwargs=None, shape3d_kwargs=None, bm_kwargs=None, subplot_kwargs=None)

Plot deflected shape diagrams.

This method returns a subplot with:
  • 3D view deflected shape;

  • 2D view deflected shape - Major Axis;

  • Bending Moment Diagram;

Parameters
speedfloat

The rotor rotation speed. Must be an element from the speed_range argument passed to the class (rad/s).

samplesint, optional

Number of samples to generate the orbit for each node. Default is 101.

frequency_unitsstr, optional

Frequency units. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m/N” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m/N pkpk’)

rotor_length_unitsstr, optional

Rotor length units. Default is ‘m’.

moment_unitsstr

Moment units. Default is ‘N*m’

shape2d_kwargsoptional

Additional key word arguments can be passed to change the 2D deflected shape plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

shape3d_kwargsoptional

Additional key word arguments can be passed to change the 3D deflected shape plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

bm_kwargsoptional

Additional key word arguments can be passed to change the bending moment diagram plot layout only (e.g. width=1000, height=800, …). *See Plotly Python Figure Reference for more information.

subplot_kwargsoptional

Additional key word arguments can be passed to change the plot layout only (e.g. width=1000, height=800, …). This kwargs override “mag_kwargs” and “phase_kwargs” dictionaries. *See Plotly Python Figure Reference for more information.

Returns
subplotsPlotly graph_objects.make_subplots()

Plotly figure with Amplitude vs Frequency and Phase vs Frequency and polar Amplitude vs Phase plots.

plot_deflected_shape_2d(speed, amplitude_units='m', phase_units='rad', rotor_length_units='m', fig=None, **kwargs)

Plot the 2D deflected shape diagram.

Parameters
speedfloat, pint.Quantity

The rotor rotation speed. Must be an element from the speed_range argument passed to the class. Default unit is rad/s.

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

phase_unitsstr, optional

Phase units. Default is “rad”

rotor_length_unitsstr, optional

Displacement units. Default is ‘m’.

figPlotly graph_objects.Figure()

The figure object with the plot.

kwargsoptional

Additional key word arguments can be passed to change the deflected shape 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_deflected_shape_3d(speed, amplitude_units='m', phase_units='rad', rotor_length_units='m', fig=None, **kwargs)

Plot the 3D deflected shape diagram.

Parameters
speedfloat

The rotor rotation speed. Must be an element from the speed_range argument passed to the class (rad/s).

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

phase_unitsstr, optional

Phase units. Default is “rad”

rotor_length_unitsstr, optional

Rotor Length units. Default is ‘m’.

figPlotly graph_objects.Figure()

The figure object with the plot.

kwargsoptional

Additional key word arguments can be passed to change the deflected shape 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_magnitude(probe, probe_units='rad', frequency_units='rad/s', amplitude_units='m', fig=None, **kwargs)

Plot forced response (magnitude) using Plotly.

Parameters
probelist

List with tuples (node, orientation angle, tag).

node : int -> Indicate the node where the probe is located.

orientation : float -> Probe orientation angle about the shaft. The 0 refers to +X direction. The strings ‘major’ and ‘minor’ can also be used to reference the major and minor axis.

tag : str, optional -> Probe tag to be add a DataFrame column title.

probe_unitsstr, option

Units for probe orientation. Default is “rad”.

frequency_unitsstr, optional

Units for the x axis. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

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_phase(probe, probe_units='rad', frequency_units='rad/s', amplitude_units='m', phase_units='rad', fig=None, **kwargs)

Plot forced response (phase) using Plotly.

Parameters
probelist

List with tuples (node, orientation angle, tag).

node : int -> Indicate the node where the probe is located.

orientation : float -> Probe orientation angle about the shaft. The 0 refers to +X direction. The strings ‘major’ and ‘minor’ can also be used to reference the major and minor axis.

tag : str, optional -> Probe tag to be add a DataFrame column title.

probe_unitsstr, option

Units for probe orientation. Default is “rad”.

frequency_unitsstr, optional

Units for the x axis. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

phase_unitsstr, optional

Units for the x axis. Default is “rad”

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_polar_bode(probe, probe_units='rad', frequency_units='rad/s', amplitude_units='m', phase_units='rad', fig=None, **kwargs)

Plot polar forced response using Plotly.

Parameters
probelist

List with tuples (node, orientation angle, tag).

node : int -> Indicate the node where the probe is located.

orientation : float -> Probe orientation angle about the shaft. The 0 refers to +X direction. The strings ‘major’ and ‘minor’ can also be used to reference the major and minor axis.

tag : str, optional -> Probe tag to be add a DataFrame column title.

probe_unitsstr, option

Units for probe orientation. Default is “rad”.

frequency_unitsstr, optional

Units for the x axis. Default is “rad/s”

amplitude_unitsstr, optional

Units for the response magnitude. Acceptable units dimensionality are:

‘[length]’ - Displays the displacement;

‘[speed]’ - Displays the velocity;

‘[acceleration]’ - Displays the acceleration.

Default is “m” 0 to peak. To use peak to peak use ‘<unit> pkpk’ (e.g. ‘m pkpk’)

phase_unitsstr, optional

Units for the x axis. Default is “rad”

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