ross.SensitivityResults

ross.SensitivityResults#

class ross.SensitivityResults(sensitivity_data, sensitivity_compute_dofs, number_dof, t)#

Results from the sensitivity analysis for the rotor AMBs.

This class holds the results of a sensitivity analysis performed to evaluate the impact of disturbances on a rotor system with Active Magnetic Bearings (AMBs). It stores frequency-domain sensitivity functions and time-domain simulation results obtained by applying log chirp disturbances at each AMB.

The attributes store the computed sensitivities, maximum sensitivity values, frequencies at which sensitivities are evaluated, and time-domain signals from the sensitivity analysis. This class provides methods to plot and analyze these results.

Parameters:

sensitivity_datadict: A nested dictionary containing the results of the time-domain simulation. The structure is {amb_tag: {axis: {‘excitation_signal’: array, ‘disturbed_signal’: array, ‘sensor_signal’: array}}}. ‘amb_tag’ is the identifier of the active magnetic bearing (AMB), and ‘axis’ can be either ‘x’ or ‘y’. The arrays are time-domain signals from the chirp disturbance simulation.
sensitivity_compute_dofsdict: Mapping of AMB tags to their corresponding degrees of freedom (DOFs). The keys are the AMB tags, and the values are dictionaries with axes (‘x’, ‘y’) mapping to the DOF index.
number_dofint: Number of degrees of freedom of the rotor system.

Attributes:

max_abs_sensitivitiesdict: Maximum absolute sensitivity for each AMB and axis (x, y).
sensitivitiesdict: Complex sensitivity Frequency Response Function (FRF) for each AMB and axis.
sensitivities_absdict: Absolute value of sensitivity FRF for each AMB and axis.
sensitivities_phasedict: Phase of sensitivity FRF for each AMB and axis.
sensitivity_compute_dofsdict: Mapping of AMB tags to their corresponding DOFs.
sensitivities_frequenciesnumpy.ndarray: Frequencies (in Hz) at which the sensitivity FRF is computed.
number_dofint: Number of degrees of freedom of the rotor system.
sensitivity_run_time_resultsdict: Time-domain simulation results.
Available plotting methods:: .plot() .plot_run_time_results()

Methods

__init__(sensitivity_data, sensitivity_compute_dofs, number_dof, t)#

Initialize the SensitivityResults instance.

This constructor processes the time-domain data from sensitivity analysis simulations to calculate the frequency-domain sensitivity functions and stores the results from both domains.

Parameters:

sensitivity_datadict: A nested dictionary containing the time-domain simulation results. The structure is {amb_tag: {axis: {‘excitation_signal’: array, ‘disturbed_signal’: array, ‘sensor_signal’: array}}}. ‘amb_tag’ is the identifier for the active magnetic bearing (AMB), and ‘axis’ can be ‘x’ or ‘y’. The arrays are the time-domain signals from the impulse disturbance simulation.
sensitivity_compute_dofsdict: Mapping of AMB tags to their corresponding degrees of freedom (DOFs). Keys are AMB tags, and values are dictionaries with axes (‘x’, ‘y’) mapping to the DOF index.
number_dofint: Number of degrees of freedom of the rotor system.
tarray_like: Time vector associated with the simulation signals. It is used to compute the frequency response function (FRF) from the time-domain data.

build_plot_time_results(data, fig, amb_tag, axis, color_index, dof_list, y_label, row, showlegend, x_lim_dt=None)#

Build and add a trace for time-domain results to a Plotly figure.

This is a helper function to create and add a scatter plot trace to a Plotly figure object. It is specifically designed for plotting time-domain results from sensitivity analysis, such as sensor signals, excitation signals, and disturbed signals.

The function takes time-series data, along with metadata like AMB tag, axis, and degree of freedom information, to generate a formatted trace that is then added to the specified row of the provided Plotly figure.

Parameters:

datanumpy.ndarray: Time-series data to be plotted. This should be a 1D NumPy array representing the signal values over time.
figplotly.graph_objects.Figure: Plotly figure object to which the trace will be added.
amb_tagstr: Tag of the Active Magnetic Bearing (AMB) associated with the data. This tag is used in the trace name for identification.
axisstr: Axis (‘x’ or ‘y’) of the AMB to which the data corresponds. Used in the trace name.
color_indexint: Index to select a color from the tableau_colors color palette for the trace line. Ensures consistent coloring across plots.
dof_listlist of str: List of degree of freedom names (e.g., [‘x’, ‘y’, ‘z’, ‘α’, ‘β’, ‘θ’]). Used to determine the degree of freedom name based on the DOF index.
y_labelstr: Label for the y-axis of the plot, describing the type of signal being plotted (e.g., “Sensor signal”, “Excitation signal”). Used in the y-axis title and hover template.
rowint: Row number in the Plotly subplot grid where the trace should be added.
showlegendbool: Boolean indicating whether to display the legend for this trace. Typically True for the first trace of a kind and False for subsequent ones in the same group.
x_lim_dtfloat, optional: Define the time limit for the x-axis, that will be equal to x_lim_dt * dt. If not provided, the upper limit in x axis will be equals to the max value of t.

Returns:

None: This function modifies the fig object in place by adding a trace. It does not return any value.

Examples

This is a helper function and is intended to be used internally by the plot_run_time_results method of a sensitivity results object. Refer to the documentation of plot_run_time_results for usage examples.

get_plot_data(amb_tag, axis, frequency_range, magnitude_scale, phase_unit, xaxis_type)#

Prepare sensitivity data for plotting based on user preferences.

This method processes the sensitivity data to be in the correct format for plotting, taking into account user-specified preferences for magnitude scale, phase unit, and x-axis type. It calculates the magnitude sensitivity (in linear or decibel scale) and phase sensitivity (in radians or degrees) based on the provided parameters. It also determines the appropriate x-axis range based on the chosen axis type (logarithmic or linear).

This method is intended for internal use by plotting functions and is not typically called directly by the user.

Parameters:

amb_tagstr: Tag of the Active Magnetic Bearing (AMB) for which to retrieve plot data.
axisstr: Axis (‘x’ or ‘y’) of the AMB for which to retrieve plot data.
frequency_rangearray_like: Array of frequencies for the x-axis.
magnitude_scalestr: Scale for the magnitude plot. Must be either ‘decibel’ or ‘linear’.
phase_unitstr: Unit for the phase plot. Must be either ‘rad’ or ‘deg’.
xaxis_typestr: Type of x-axis scaling. Must be either ‘log’ or ‘linear’.

Returns:

tuple

A tuple containing the following elements: - mag_sensitivity : numpy.ndarray

Magnitude sensitivity data, scaled according to magnitude_scale.

phase_sensitivity : numpy.ndarray Phase sensitivity data, converted to phase_unit.
scale_string : str String indicating the magnitude scale used (e.g., “(dB)” for decibel).
xaxis_range : list List of two floats defining the x-axis range based on xaxis_type.

Raises:

ValueError: If magnitude_scale is not ‘decibel’ or ‘linear’.
AttributeError: If xaxis_type is not ‘log’ or ‘linear’.

Examples

This is a helper function and is not intended to be called directly. Refer to the documentation of the plot method for examples of how plotting is performed using this method indirectly.

classmethod load(file: Path)#

Load a SensitivityResults object from a TOML file.

This method reconstructs a SensitivityResults instance from data stored in a TOML file, restoring all relevant attributes such as sensitivities, maximum absolute sensitivities, frequency arrays, and time-domain results.

Parameters:

filePath: Path to the TOML file containing the serialized SensitivityResults data.

Returns:

SensitivityResults: An instance of SensitivityResults with all data loaded from the file.

plot(frequency_units='rad/s', magnitude_scale='decibel', xaxis_type='log', phase_unit='rad', fig=None, fig_kwargs=None)#

Plots sensitivity analysis results.

This method generates a plot of the sensitivity analysis results, showing the magnitude and phase of the sensitivity associated with each Active Magnetic Bearing (AMB) and axis (x and y).

Parameters:

frequency_unitsstr, optional: Units for the frequency axis. Options are “rad/s”, “Hz”, “RPM”. Default is “rad/s”.
magnitude_scalestr, optional: Scale for the magnitude plot. Options are “decibel” or “linear”. Default is “decibel”.
xaxis_typestr, optional: Type of x-axis scaling. Options are “log” or “linear”. Default is “log”.
phase_unitstr, optional: Units for the phase plot. Options are “rad” or “deg”. Default is “rad”.
figplotly.graph_objects.Figure, optional: Plotly figure object to add the plot to. If None, a new figure is created. Default is None.
fig_kwargsdict, optional: Dictionary of keyword arguments to customize the plotly figure. See plotly.graph_objects.Figure documentation for more details. Default is None.

Returns:

figplotly.graph_objects.Figure: Plotly figure object containing the sensitivity plots.

Examples

>>> import ross as rs
>>> rotor = rs.rotor_amb_example()
>>> sensitivity_results = rotor.run_amb_sensitivity(
...     speed=0,
...     t_max=5e-4,
...     dt=1e-4,
...     disturbance_amplitude=10e-6,
...     disturbance_min_frequency=0.001,
...     disturbance_max_frequency=150,
...     amb_tags=["Magnetic Bearing 0"])
Running direct method...

>>> # Generate the sensitivity plot
>>> fig_sensitivity = sensitivity_results.plot()

>>> # Customize the plot appearance
>>> fig_custom = sensitivity_results.plot(
...     frequency_units="Hz",
...     magnitude_scale="linear",
...     xaxis_type="linear",
...     phase_unit="deg",
...     fig_kwargs={"title": "Custom Sensitivity Plot"}
... )

plot_time_results(fig=None, fig_kwargs=None)#

Plot time-domain results from sensitivity analysis.

This method generates a plot of the time-domain signals obtained during the sensitivity analysis. It displays the sensor signal, excitation signal, and disturbed signal for each Active Magnetic Bearing (AMB) and axis (x and y) where sensitivity analysis was performed.

The signals are plotted in subplots within a single figure, allowing for a visual inspection of the system’s response in the time domain to impulse disturbances at the AMBs.

Parameters:

figplotly.graph_objects.Figure, optional: plotly figure object to add the plot to. If None, a new figure is created. Default is None.
fig_kwargsdict, optional: Dictionary of keyword arguments to customize the plotly figure. This can include parameters like ‘title’, ‘width’, ‘height’, etc. See plotly.graph_objects.Figure documentation for more details. Default is None.

Returns:

figplotly.graph_objects.Figure: Plotly figure object containing the time-domain signal plots (sensor signal, excitation signal, and disturbed signal) for each AMB and axis.

Examples

>>> import ross as rs
>>> rotor = rs.rotor_amb_example()
>>> sensitivity_results = rotor.run_amb_sensitivity(
...     speed=0,
...     t_max=5e-4,
...     dt=1e-4,
...     disturbance_amplitude=10e-6,
...     disturbance_min_frequency=0.001,
...     disturbance_max_frequency=150,
...     amb_tags=["Magnetic Bearing 0"])
Running direct method...

>>> # Generate the time-domain results plot
>>> fig_sensitivity = sensitivity_results.plot_time_results()

>>> # Customize the plot appearance
>>> fig_custom = sensitivity_results.plot_time_results(
...     fig_kwargs={"title": "Time-Domain Signals from Sensitivity Analysis",
...                 "height": 800}
... )

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: Path)#

Save the sensitivity analysis results to a TOML file.

This method serializes all relevant attributes of the SensitivityResults object, including the number of degrees of freedom, sensitivity computation DOFs, maximum absolute sensitivities, frequency response data (complex, magnitude, and phase), and time-domain results. The data is converted to standard Python types and written to the specified file in TOML format, creating parent directories if needed.

Parameters:

filePath: The path to the TOML file where the results will be saved.

Returns:

None: The method does not return anything. The results are written to disk.

ross.SensitivityResults

Contents

ross.SensitivityResults#