Linear Systems API

class resonance.linear_systems.BookOnCupSystem

This system represents dynamics of a typical engineering textbook set atop a cylinder (a coffee cup) such that the book can vibrate without slip on the curvature of the cup. It is described by:

constants

thickness, t [meters]

the thickness of the book

length, l [meters]

the length of the edge of the book which is tagent to the cup’s surface

mass, m [kilograms]

the mass of the book

radius, r [meters]

the outer radius of the cup

coordinates

book_angle, theta [radians]

the angle of the book with respect to the gravity vector

speeds

book_angle_vel, theta [radians]

the angular rate of the book with repsect to the gravity vector

class resonance.linear_systems.ClockPendulumSystem

This system represents dynamics of a simple compound pendulum in which a rigid body is attached via a revolute joint to a fixed point. Gravity acts on the pendulum to bring it to an equilibrium state and there is no friction in the joint. It is described by:

constants

pendulum_mass, m [kg]

The mass of the compound pendulum.

inertia_about_joint, i [kg m**2]

The moment of inertia of the compound pendulum about the revolute joint.

joint_to_mass_center, l [m]

The distance from the revolute joint to the mass center of the compound pendulum.

acc_due_to_gravity, g [m/s**2]

The acceleration due to gravity.

coordinates

angle, theta [rad]

The angle of the pendulum relative to the direction of gravity. When theta is zero the pendulum is hanging down in it’s equilibrium state.

speeds

angle_vel, theta_dot [rad / s]

The angular velocity of the pendulum about the revolute joint axis.

class resonance.linear_systems.CompoundPendulumSystem

This system represents dynamics of a simple compound pendulum in which a rigid body is attached via a revolute joint to a fixed point. Gravity acts on the pendulum to bring it to an equilibrium state and there is no friction in the joint. It is described by:

constants

pendulum_mass, m [kg]

The mass of the compound pendulum.

inertia_about_joint, i [kg m**2]

The moment of inertia of the compound pendulum about the revolute joint.

joint_to_mass_center, l [m]

The distance from the revolute joint to the mass center of the compound pendulum.

acc_due_to_gravity, g [m/s**2]

The acceleration due to gravity.

coordinates

angle, theta [rad]

The angle of the pendulum relative to the direction of gravity. When theta is zero the pendulum is hanging down in it’s equilibrium state.

speeds

angle_vel, theta_dot [rad / s]

The angular velocity of the pendulum about the revolute joint axis.

class resonance.linear_systems.SimplePendulumSystem

This system represents dynamics of a simple pendulum in which a point mass is fixed on a massless pendulum arm of some length to a revolute joint. Gravity acts on the pendulum to bring it to an equilibrium state and there is no friction in the joint. It is described by:

constants

pendulum_mass, m [kg]

The mass of the compound pendulum.

pendulum_length, l [m]

The distance from the revolute joint to the point mass location.

acc_due_to_gravity, g [m/s**2]

The acceleration due to gravity.

coordinates

angle, theta [rad]

The angle of the pendulum relative to the direction of gravity. When theta is zero the pendulum is hanging down in it’s equilibrium state.

speeds

angle_vel, theta_dot [rad / s]

The angular velocity of the pendulum about the revolute joint axis.

class resonance.linear_systems.SingleDoFLinearSystem

This is the base system for any linear single degree of freedom system. It can be subclassed to make a custom system or instantiated and the attributes and methods added dynamically.

constants

_ParametersDict – A custom dictionary that contains parameters that do not vary with time.

coordinates

_CoordinatesDict – A custom dictionary that contains the generalized coordinate which varies with time.

speeds

_CoordinatesDict – A custom dictionary that contains the generalized speed which varies with time.

measurements

_MeasurementsDict – A custom dictionary that contains parameters that are functions of the constants, coordinates, and other measurements.

config_plot_func

function – A function that generates a matplotlib plot that uses the instantaneous values of the constants, coordinates, and measurements.

config_plot_update_func

function – A function that updates the configuration plot that uses the time series values of the constants, coordinates, and measurements. Defines a matplotlib animation frame.

add_measurement()

Used to dynamically add functions to compute measurement values.

free_response()

Simulates the system and returns a time series of the coordinates and measurments.

plot_configuration()

Generates the plot defined by config_plot_func.

animate_configutation()

Generates the animation defined by config_plot_func and config_plot_update_func.

period()

Returns the damped natural period of the system.

add_measurement(name, func)

Creates a new measurement entry in the measurements attribute that uses the provided function to compute the measurement.

Parameters:

• name (string) – This must be a valid Python variable name and it should not clash with any names in the constants or coordinates dictionary.
• func (function) – This function must only have existing parameter, coordinate, or measurement names in the function signature. These can be a subset of the available choices and any order is permitted. The function must be able to operate on arrys, i.e. use NumPy vectorized functions inside. It should return a single variable, scalar or array, that gives the values of the measurement.

Examples

>>> import numpy as np
>>> def f(par2, meas4, par1, coord5):
          return par2 + meas4 + par1 + np.abs(coord5)
>>> f(1.0, 2.0, 3.0, -4.0):
10.0
>>> f(1.0, 2.0, 3.0, np.array([1.0, 2.0, -4.0]))
array([  7.,   8.,  10.])
>>> sys.add_measurement('meas5', f)
>>> sys.measurements['meas5']
10.0

animate_configuration(**kwargs)

Returns a matplotlib animation function based on the configuration plot and the configuration plot update function.

config_plot_func

The configuration plot function arguments should be any of the system’s constants, coordinates, measurements, or ‘time’. No other arguments are valid. The function has to return the matplotlib figure as the first item but can be followed by any number of mutable matplotlib objects that you may want to change during an animation. Refer to the matplotlib documentation for tips on creating figures.

Examples

>>> sys = SingleDoFLinearSystem()
>>> sys.constants['radius'] = 5.0
>>> sys.constants['center_y'] = 10.0
>>> sys.coordinates['center_x'] = 0.0
>>> def plot(radius, center_x, center_y, time):
...     fig, ax = plt.subplots(1, 1)
...     circle = Circle((center_x, center_y), radius=radius)
...     ax.add_patch(circle)
...     ax.set_title(time)
...     return fig, circle, ax
...
>>> sys.config_plot_function = plot
>>> sys.plot_configuration()

config_plot_update_func

The configuration plot update function arguments should be any of the system’s constants, coordinates, measurements, or ‘time’ in any order with the returned values from the config_plot_func as the last arguments in the exact order as in the configuration plot return statement. No other arguments are valid. Nothing need be returned from the function. See the matplotlib animation documentation for tips on creating these update functions.

Examples

>>> sys = SingleDoFLinearSystem()
>>> sys.constants['radius'] = 5.0
>>> sys.constants['center_y'] = 10.0
>>> sys.coordinates['center_x'] = 0.0
>>> def plot(radius, center_x, center_y, time):
...     fig, ax = plt.subplots(1, 1)
...     circle = Circle((center_x, center_y), radius=radius)
...     ax.add_patch(circle)
...     ax.set_title(time)
...     return fig, circle, ax
...
>>> sys.config_plot_function = plot
>>> def update(center_y, center_x, time, circle, ax):
...     # NOTE : that circle and ax have to be the last arguments and be
...     # in the same order as returned from plot()
...     circle.set_xy((center_x, center_y))
...     ax.set_title(time)
...     fig.canvas.draw()
...
>>> sys.config_plot_update_func = update
>>> sys.animate_configuration()

constants

A dictionary containing the all of the system’s constants.

Examples

>>> sys = SingleDoFLinearSystem()
>>> sys.constants
{}
>>> sys.constants['mass'] = 5.0
>>> sys.constants
{'mass': 5.0}
>>> del sys.constants['mass']
>>> sys.constants
{}
>>> sys.constants['length'] = 10.0
>>> sys.constants
{'length': 10.0}

coordinates

A dictionary containing the system’s generalized coordinate.

free_response(final_time, initial_time=0.0, sample_rate=100)

Returns a Pandas data frame with monotonic time values as the index and columns for each coordinate and measurement at the time value for that row. Note that this data frame is stored on the system as the vairable result until this method is called again, which will overwrite it.

Parameters:

• final_time (float) – A value of time in seconds corresponding to the end of the simulation.
• initial_time (float, optional) – A value of time in seconds corresponding to the start of the simulation.
• sample_rate (integer, optional) – The sample rate of the simulation in Hertz (samples per second). The time values will be reported at the initial time and final time, along with times space equally based on the sample rate.

Returns:

df – A data frame indexed by time with all of the coordinates and measurements as columns.

Return type:

pandas.DataFrame

measurements

A dictionary containing the all of the system’s measurements.

period()

Returns the (damped) period of oscillation of the coordinate in seconds.

plot_configuration()

Returns a matplotlib figure generated by the function assigned to the config_plot_func attribute. You may need to call matplotlib.pyplot.show() to display the figure.

Returns:

• fig (matplotlib.figure.Figure) – The first returned object is always a figure.
• *args (matplotlib objects) – Any matplotlib objects can be returned after the figure.

speeds

A dictionary containing the system’s generalized speed.

class resonance.linear_systems.TorsionalPendulumSystem

This system represents dynamics of a simple torsional pendulum in which the torsionally elastic member’s axis is aligned with gravity and the axis of the torsion member passes through the mass center of an object attached to it’s lower end. The top of the torsion rod is rigidly attached to the “ceiling”. It is described by:

constants

rotational_inertia, I [kg m**2]

The moment of inertia of the object attached to the pendulum.

torsional_damping, C [N s / m]

The viscous linear damping coefficient which represents any energy disipation from things like air resistance, slip, etc.

torsional_stiffness, K [N / m]

The linear elastic stiffness coefficient of the torsion member, typically a round slender rod.

coordinates

torsional_angle, theta [rad]

speeds

torsional_angle_vel, theta_dot [rad / s]

resonance.functions.estimate_period(time, signal)

Computes the period of oscillation based on the given periodic signal.

Parameters:

• time (array_like, shape(n,)) – An array of monotonically increasing time values.
• signal (array_like, shape(n,)) – An array of values for the periodic signal at each time in t.

Returns:

period – An estimate of the period of oscillation.

Return type:

float