API¶
-
class
resonance.system.
System
¶ This is the base system for any single or multi degree of freedom systems. It can be subclassed to make a custom system.
-
constants
¶ _ConstantsDict – 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
andconfig_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 = System() >>> sys.constants {} >>> sys.constants['mass'] = 5.0 >>> sys.constants {'mass': 5.0} >>> del sys.constants['mass'] >>> sys.constants {} >>> sys.constants['mass'] = 5.0 >>> sys.constants['length'] = 10.0 >>> sys.constants {'mass': 5.0, 'length': 10.0}
-
coordinates
A dictionary containing the system’s generalized coordinates. These values will be used as initial conditions in simulations.
Examples
>>> sys = System() >>> sys.coordinates['angle'] = 0.0 >>> sys.coordinates {'angle': 0.0}
-
free_response
(final_time, initial_time=0.0, sample_rate=100, **kwargs) 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, i.e. inclusive, 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.
-
plot_configuration
() Returns a matplotlib figure generated by the function assigned to the
config_plot_func
attribute. You may need to callmatplotlib.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.
Examples
>>> sys = System() >>> sys.speeds['angle_vel'] = 0.0 >>> sys.speeds {'angle_vel': 0.0}
-
states
¶ An ordered dictionary containing the system’s state variables and values. The coordinates are always ordered before the speeds and the individual order of the values depends on the order they were added to coordinates and speeds.
Examples
>>> sys = System() >>> sys.coordinates['angle'] = 0.2 >>> sys.speeds['angle_vel'] = 0.1 >>> sys.states {'angle': 0.2, 'angle_vel': 0.1} >>> list(sys.states.keys()) ['angle', 'angle_vel'] >>> list(sys.states.values()) [0.2, 0.1]
-
-
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.
MassSpringDamperSystem
¶ This system represents dynamics of a mass connected to a spring and damper (dashpot). The mass moves horizontally without friction and is acted on horizontally by the spring and damper in parallel. The system is described by:
-
constants
¶ - mass, M [kg]
- The system mass.
- damping, C [kg / s]
- The viscous linear damping coefficient which represents any energy dissipation from things like air resistance, slip, etc.
- stiffness, K [N / m]
- The linear elastic stiffness of the spring.
-
coordinates
¶ position, x [m]
-
speeds
¶ velocity, x_dot [m / s]
-
-
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.
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]
-
-
class
resonance.nonlinear_systems.
ClockPendulumSystem
¶ This system represents dynamics of a compound pendulum representing a clock pendulum. It is made up of a thin long cylindrical rod with a thin disc bob on the end. Gravity acts on the pendulum to bring it to an equilibrium state and there is option Coulomb friction in the joint. It is described by:
-
constants
¶ - bob_mass, m_b [kg]
- The mass of the bob (a thin disc) on the end of the pendulum.
- bob_radius, r [m]
- The radius of the bob (a thin disc) on the end of the pendulum.
- rod_mass, m_r [kg]
- The mass of the then cylindrical rod.
- rod_length, l [m]
- The length of the rod which connects the pivot joint to the center of the bob.
- coeff_of_friction, mu [unitless]
- The torsional Coulomb coefficient of friction at the pivot joint. The joint is clamped via a 1 Nm force.
- 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.
-
-
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