Note
Go to the end to download the full example code.
Using Parameter Sets¶
Parameter sets represent a set of constants associated with a multibody
dynamics model. These constants have a name and an associated floating point
value. This mapping from name to value is stored in a dictionary and then
passed to a ParameterSet on
creation. The docstring of the parameter set shows what values must be defined
in the dictionary. This example will make use of the parameters associated with
the model defined in [Meijaard2007].
from bicycleparameters import parameter_sets
from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
print(help(Meijaard2007ParameterSet))
Help on class Meijaard2007ParameterSet in module bicycleparameters.parameter_sets:
class Meijaard2007ParameterSet(ParameterSet)
| Meijaard2007ParameterSet(parameters, includes_rider)
|
| Represents the parameters of the benchmark bicycle presented in
| [Meijaard2007]_.
|
| The four bodies are:
|
| - B: rear frame + rigid rider
| - F: front wheel
| - H: front frame (fork & handlebars)
| - R: rear wheel
|
| Parameters
| ==========
| parameters : dictionary
| A dictionary mapping variable names to values that contains the
| following keys:
|
| - ``IBxx`` : x moment of inertia of the frame/rider [kg*m**2]
| - ``IBxz`` : xz product of inertia of the frame/rider [kg*m**2]
| - ``IBzz`` : z moment of inertia of the frame/rider [kg*m**2]
| - ``IFxx`` : x moment of inertia of the front wheel [kg*m**2]
| - ``IFyy`` : y moment of inertia of the front wheel [kg*m**2]
| - ``IHxx`` : x moment of inertia of the handlebar/fork [kg*m**2]
| - ``IHxz`` : xz product of inertia of the handlebar/fork [kg*m**2]
| - ``IHzz`` : z moment of inertia of the handlebar/fork [kg*m**2]
| - ``IRxx`` : x moment of inertia of the rear wheel [kg*m**2]
| - ``IRyy`` : y moment of inertia of the rear wheel [kg*m**2]
| - ``c`` : trail [m]
| - ``g`` : acceleration due to gravity [m/s**2]
| - ``lam`` : steer axis tilt [rad]
| - ``mB`` : frame/rider mass [kg]
| - ``mF`` : front wheel mass [kg]
| - ``mH`` : handlebar/fork assembly mass [kg]
| - ``mR`` : rear wheel mass [kg]
| - ``rF`` : front wheel radius [m]
| - ``rR`` : rear wheel radius [m]
| - ``w`` : wheelbase [m]
| - ``xB`` : x distance to the frame/rider center of mass [m]
| - ``xH`` : x distance to the frame/rider center of mass [m]
| - ``zB`` : z distance to the frame/rider center of mass [m]
| - ``zH`` : z distance to the frame/rider center of mass [m]
|
| includes_rider : boolean
| True if body B is the combined rear frame and rider in terms of
| mass and inertia values.
|
| Attributes
| ==========
| par_strings : dictionary
| Maps ASCII strings to their LaTeX string.
| body_labels : list of strings
| Single capital letters that correspond to the four rigid bodies in the
| model.
|
| References
| ==========
|
| .. [Meijaard2007] Meijaard J.P, Papadopoulos Jim M, Ruina Andy and Schwab
| A.L, 2007, Linearized dynamics equations for the balance and steer of a
| bicycle: a benchmark and review, Proc. R. Soc. A., 463:1955–1982
| http://doi.org/10.1098/rspa.2007.1857
|
| Method resolution order:
| Meijaard2007ParameterSet
| ParameterSet
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, parameters, includes_rider)
| Initialize self. See help(type(self)) for accurate signature.
|
| form_inertia_tensor(self, body)
| Returns the inertia tensor with respect to the global coordinate
| system and the body's mass center.
|
| Parameters
| ==========
| body : string
| One of the ``body_labels``.
|
| Returns
| =======
| inertia_tensor : ndarray, shape(3, 3)
| Inertia tensor of the body with respect to the body's mass center
| and the model's coordinate system.
|
| Examples
| ========
|
| >>> from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| >>> from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| >>> p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| >>> p.form_inertia_tensor('H')
| array([[ 0.25337959, 0. , -0.07204524],
| [ 0. , 0.24613881, 0. ],
| [-0.07204524, 0. , 0.09557708]])
|
| form_mass_center_vector(self, body)
| Returns an array representing the 3D vector to the mass center of
| the body from the origin at the rear wheel contact point.
|
| Parameters
| ==========
| body : string
| One of 'B', 'F', 'H', 'R'.
|
| Returns
| =======
| ndarray, shape(3,)
| A vector containing the X, Y, and X coordinates of the mass center
| of the body.
|
| Examples
| ========
|
| >>> from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| >>> from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| >>> p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| >>> p.form_mass_center_vector('B')
| array([ 0.28909943, 0. , -1.04029228])
|
| mass_center_of(self, *bodies)
| Returns the vector locating the center of mass of the collection of
| bodies.
|
| Parameters
| ==========
| bodies : iterable of strings
| One or more of the ``body_labels``.
|
| Returns
| =======
| com : ndarray, shape(3,)
| Vector locating the center of mass of the bodies givien in
| ``bodies``.
|
| Examples
| ========
|
| >>> from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| >>> from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| >>> p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| >>> p.mass_center_of('B', 'H')
| array([ 0.31096918, 0. , -1.02923892])
|
| plot_all(self, ax=None)
| Returns matplotlib axes with the geometry and inertial
| representations of all bodies of the bicycle parameter set.
|
| Parameters
| ==========
| ax : AxesSubplot, optional
| An axes to draw on, otherwise one is created.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_all()
|
| plot_body_mass_center(self, body, ax=None)
| Returns a matplotlib axes with a mass center symbol for the
| specified body to the plot.
|
| Parameters
| ==========
| body : string
| The body string: ``F``, ``H``, ``B``, or ``R``.
| ax : SubplotAxes, optional
| Axes to plot on.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_body_mass_center('B')
|
| plot_body_principal_inertia_ellipsoid(self, body, ax=None)
| Returns a matplotlib axes with an ellipse that respresnts the XZ
| plane view of a constant density ellipsoid which has the same principal
| moments and axes of inertia as the body.
|
| Parameters
| ==========
| body : string
| One of the ``body_labels``.
| ax : SubplotAxes, optional
| Axes to plot on.
|
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_body_principal_inertia_ellipsoid('H')
|
| plot_body_principal_radii_of_gyration(self, body, ax=None)
| Returns a matplotlib axes with lines and a circle that indicate the
| principal radii of gyration of the specified body.
|
| Parameters
| ==========
| body : string
| One of the ``body_labels``.
| ax : SubplotAxes, optional
| Axes to plot on.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_body_principal_radii_of_gyration('B')
|
| plot_geometry(self, show_steer_axis=True, ax=None)
| Returns a matplotlib axes with a simple drawing of the bicycle's
| geometry.
|
| Parameters
| ==========
| show_steer_axis : boolean
| If true, a dotted line will be plotted along the steer axis from
| the front wheel center to the ground.
| ax : AxesSubplot, optional
| An axes to draw on, otherwise one is created.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_geometry()
|
| plot_mass_centers(self, bodies=None, ax=None)
| Returns a matplotlib axes with mass center indicators for each body.
|
| Parameters
| ==========
| bodies: list of strings, optional
| A subset of the strings present in the class attribute
| ``body_labels``.
| ax: matplotlib Axes, optional
| An axes to plot on.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_mass_centers()
|
| plot_principal_inertia_ellipsoids(self, bodies=None, ax=None)
| Returns a Matplotlib axes with 2D representations of 3D solid
| uniform ellipsoids that have the same inertia as the body.
|
| Parameters
| ==========
| bodies: list of strings, optional
| A subset of the strings present in the class attribute
| ``body_labels``.
| ax : AxesSubplot, optional
| An axes to draw on, otherwise one is created.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_principal_inertia_ellipsoids()
|
| plot_principal_radii_of_gyration(self, bodies=None, ax=None)
| Returns a matplotlib axis with principal radii of all bodies
| shown.
|
| Parameters
| ==========
| bodies: list of strings, optional
| A subset of the strings present in the class attribute
| ``body_labels``.
| ax: matplotlib Axes, optional
| An axes to plot on.
|
| Examples
| ========
|
| .. plot::
| :include-source: True
| :context: reset
|
| from bicycleparameters.parameter_dicts import meijaard2007_browser_jason
| from bicycleparameters.parameter_sets import Meijaard2007ParameterSet
| p = Meijaard2007ParameterSet(meijaard2007_browser_jason, True)
| p.plot_principal_radii_of_gyration()
|
| to_parameterization(self, name)
| Returns a specific parameter set based on the provided
| parameterization name.
|
| Parameters
| ==========
| name : string
| The name of the parameterization. These should correspond to a
| subclass of a ``ParameterSet`` and the name will be the string that
| precedes "ParameterSet". For example, the parameterization name of
| ``Meijaard2007ParameterSet`` is ``Meijaard2007``.
|
| Returns
| =======
| ParmeterSet
| If a different parameterization is requested and this class can
| convert itself, it will return a new parameter set of the correct
| parameterization.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| body_labels = ['B', 'F', 'H', 'R']
|
| par_strings = {'IBxx': 'I_{Bxx}', 'IBxz': 'I_{Bxz}', 'IByy': 'I_{Byy}'...
|
| ----------------------------------------------------------------------
| Methods inherited from ParameterSet:
|
| to_ini(self, fname)
| Writes parameters to file in the INI format. Metadata is not
| included.
|
| Parameters
| ==========
| fname : string
| Path to file.
|
| to_yaml(self, fname)
| Writes parameters to file in the YAML format.
|
| Parameters
| ==========
| fname : string
| Path to file.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParameterSet:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
None
Below are a dictionary with parameters for the linear Carvallo-Whipple model with some realistic initial values.
par = {
'IBxx': 11.3557360401,
'IBxz': -1.96756380745,
'IByy': 12.2177848012,
'IBzz': 3.12354397008,
'IFxx': 0.0904106601579,
'IFyy': 0.149389340425,
'IHxx': 0.253379594731,
'IHxz': -0.0720452391817,
'IHyy': 0.246138810935,
'IHzz': 0.0955770796289,
'IRxx': 0.0883819364527,
'IRyy': 0.152467620286,
'c': 0.0685808540382,
'g': 9.81,
'lam': 0.399680398707,
'mB': 81.86,
'mF': 2.02,
'mH': 3.22,
'mR': 3.11,
'rF': 0.34352982332,
'rR': 0.340958858855,
'v': 1.0,
'w': 1.121,
'xB': 0.289099434117,
'xH': 0.866949640247,
'zB': -1.04029228321,
'zH': -0.748236400835,
}
The associated parameter set can then be created with the dictionary:
par_set = Meijaard2007ParameterSet(par, True)
par_set
The dictionary of parameters is stored in the parameters attribute:
par_set.parameters
{'IBxx': 11.3557360401, 'IBxz': -1.96756380745, 'IByy': 12.2177848012, 'IBzz': 3.12354397008, 'IFxx': 0.0904106601579, 'IFyy': 0.149389340425, 'IHxx': 0.253379594731, 'IHxz': -0.0720452391817, 'IHyy': 0.246138810935, 'IHzz': 0.0955770796289, 'IRxx': 0.0883819364527, 'IRyy': 0.152467620286, 'c': 0.0685808540382, 'g': 9.81, 'lam': 0.399680398707, 'mB': 81.86, 'mF': 2.02, 'mH': 3.22, 'mR': 3.11, 'rF': 0.34352982332, 'rR': 0.340958858855, 'v': 1.0, 'w': 1.121, 'xB': 0.289099434117, 'xH': 0.866949640247, 'zB': -1.04029228321, 'zH': -0.748236400835}
The module parameter_sets includes different parameter sets and it may
be possible to convert from one parameter set to another if the conversion is
available.
print(parameter_sets.__all__)
['Meijaard2007ParameterSet', 'Meijaard2007WithFeedbackParameterSet', 'Moore2012ParameterSet', 'Moore2019ParameterSet', 'MooreRiderLean2012ParameterSet', 'ParameterSet']
For example, this parameter set can be converted to the one for the linear Carvallo-Whipple model in [Moore2012]:
par_set_moore = par_set.to_parameterization('Moore2012')
par_set_moore
There is a unique label for each body embedded in the parameter variables, e.g. \(B\) in \(I_{Bxx}\), and these are used in some methods below.
par_set.body_labels
['B', 'F', 'H', 'R']
Many methods take one or more body labels as arguments. For example, the location of the combined mass center of the rear and front wheels can be found with:
par_set.mass_center_of('R', 'F')
array([ 0.44140741, 0. , -0.34197121])
Or for all of the rigid bodies:
par_set.mass_center_of('B', 'H', 'F', 'R')
array([ 0.31838685, 0. , -0.99015586])
The inertia tensor of a single body can be shown with:
par_set.form_inertia_tensor('B')
array([[11.35573604, 0. , -1.96756381],
[ 0. , 12.2177848 , 0. ],
[-1.96756381, 0. , 3.12354397]])
Once the parameter set is available there are various methods that help you calculate and visualize the properties of this parameter set. This set describes the geometry, mass, and inertia of a bicycle. You can plot the geometry like so:
_ = par_set.plot_geometry()
You can then add symbols representing the mass centers of the four bodies like so:
ax = par_set.plot_geometry()
_ = par_set.plot_mass_centers(ax=ax)
You can then add symbols representing the radii of gyration of each rigid body like so:
ax = par_set.plot_geometry()
_ = par_set.plot_principal_radii_of_gyration(ax=ax)
And finally, you can then add symbols representing uniformly dense ellipsoids with the same mass and inertia of each rigid body like so:
ax = par_set.plot_geometry()
_ = par_set.plot_principal_inertia_ellipsoids(ax=ax)
All of the plot features can be shown with a single function call:
_ = par_set.plot_all()
Total running time of the script: (0 minutes 0.491 seconds)