Merge pull request sympy#26325 from tjstienstra/deprecation-warning-b…

…ody-examples

Deprecation warning body examples

doc/src/modules/physics/mechanics/api/deprecated_classes.rst

@@ -0,0 +1,17 @@
+===============================
+Deprecated Classes (Docstrings)
+===============================
+
+.. deprecated:: 1.13
+    :class:`~.Body` and :class:`~.JointsMethod` have been deprecated. The
+    functionality of :class:`~.Body` is fully captured by :class:`~.RigidBody`
+    and :class:`~.Particle` and the functionality of :class:`~.JointsMethod` is
+    fully captured by :class:`~.System`.
+
+.. autoclass:: sympy.physics.mechanics.body.Body
+    :members:
+    :inherited-members:
+
+.. autoclass:: sympy.physics.mechanics.jointsmethod.JointsMethod
+    :members:
+    :inherited-members:

doc/src/modules/physics/mechanics/api/index.rst

@@ -14,3 +14,4 @@ Mechanics API Reference
    pathway.rst
    actuator.rst
    wrapping_geometry.rst
+   deprecated_classes.rst

sympy/physics/mechanics/body.py

@@ -16,6 +16,10 @@ class Body(RigidBody, Particle):  # type: ignore
     passed in and central_inertia is left as None, the Particle object is
     created. Otherwise a RigidBody object will be created.
 
+    .. deprecated:: 1.13
+        The Body class is deprecated. Its functionality is captured by
+        :class:`~.RigidBody` and :class:`~.Particle`.
+
     Explanation
     ===========
 
@@ -65,12 +69,20 @@ class Body(RigidBody, Particle):  # type: ignore
     Examples
     ========
 
+    As Body has been deprecated, the following examples are for illustrative
+    purposes only. The functionality of Body is fully captured by
+    :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+    warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+
     Default behaviour. This results in the creation of a RigidBody object for
     which the mass, mass center, frame and inertia attributes are given default
     values. ::
 
         >>> from sympy.physics.mechanics import Body
-        >>> body = Body('name_of_body')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     body = Body('name_of_body')
 
     This next example demonstrates the code required to specify all of the
     values of the Body object. Note this will also create a RigidBody version of
@@ -84,15 +96,17 @@ class Body(RigidBody, Particle):  # type: ignore
         >>> frame = ReferenceFrame('frame')
         >>> ixx = Symbol('ixx')
         >>> body_inertia = inertia(frame, ixx, 0, 0)
-        >>> body = Body('name_of_body', masscenter, mass, frame, body_inertia)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     body = Body('name_of_body', masscenter, mass, frame, body_inertia)
 
     The minimal code required to create a Particle version of the Body object
     involves simply passing in a name and a mass. ::
 
         >>> from sympy import Symbol
         >>> from sympy.physics.mechanics import Body
         >>> mass = Symbol('mass')
-        >>> body = Body('name_of_body', mass=mass)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     body = Body('name_of_body', mass=mass)
 
     The Particle version of the Body object can also receive a masscenter point
     and a reference frame, just not an inertia.
@@ -204,12 +218,19 @@ def kinetic_energy(self, frame):
         Examples
         ========
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body, ReferenceFrame, Point
         >>> from sympy import symbols
         >>> m, v, r, omega = symbols('m v r omega')
         >>> N = ReferenceFrame('N')
         >>> O = Point('O')
-        >>> P = Body('P', masscenter=O, mass=m)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     P = Body('P', masscenter=O, mass=m)
         >>> P.masscenter.set_vel(N, v * N.y)
         >>> P.kinetic_energy(N)
         m*v**2/2
@@ -219,7 +240,8 @@ def kinetic_energy(self, frame):
         >>> b.set_ang_vel(N, omega * b.x)
         >>> P = Point('P')
         >>> P.set_vel(N, v * N.x)
-        >>> B = Body('B', masscenter=P, frame=b)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B', masscenter=P, frame=b)
         >>> B.kinetic_energy(N)
         B_ixx*omega**2/2 + B_mass*v**2/2
 
@@ -264,10 +286,17 @@ def apply_force(self, force, point=None, reaction_body=None, reaction_point=None
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy import symbols
         >>> from sympy.physics.mechanics import Body, Point, dynamicsymbols
         >>> m, g = symbols('m g')
-        >>> B = Body('B')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
         >>> force1 = m*g*B.z
         >>> B.apply_force(force1) #Applying force on B's masscenter
         >>> B.loads
@@ -292,10 +321,12 @@ def apply_force(self, force, point=None, reaction_body=None, reaction_point=None
         consider two bodies connected through a spring.
 
         >>> from sympy.physics.mechanics import Body, dynamicsymbols
-        >>> N = Body('N') #Newtonion Frame
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     N = Body('N') #Newtonion Frame
         >>> x = dynamicsymbols('x')
-        >>> B1 = Body('B1')
-        >>> B2 = Body('B2')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B1 = Body('B1')
+        ...     B2 = Body('B2')
         >>> spring_force = x*N.x
 
         Now let's apply equal and opposite spring force to the bodies.
@@ -362,10 +393,17 @@ def apply_torque(self, torque, reaction_body=None):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy import symbols
         >>> from sympy.physics.mechanics import Body, dynamicsymbols
         >>> t = symbols('t')
-        >>> B = Body('B')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
         >>> torque1 = t*B.z
         >>> B.apply_torque(torque1)
         >>> B.loads
@@ -389,9 +427,10 @@ def apply_torque(self, torque, reaction_body=None):
         a torque `T` is acting on one body, and `-T` on the other.
 
         >>> from sympy.physics.mechanics import Body, dynamicsymbols
-        >>> N = Body('N') #Newtonion frame
-        >>> B1 = Body('B1')
-        >>> B2 = Body('B2')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     N = Body('N') #Newtonion frame
+        ...     B1 = Body('B1')
+        ...     B2 = Body('B2')
         >>> v = dynamicsymbols('v')
         >>> T = v*N.y #Torque
 
@@ -434,8 +473,15 @@ def clear_loads(self):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body
-        >>> B = Body('B')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
         >>> force = B.x + B.y
         >>> B.apply_force(force)
         >>> B.loads
@@ -464,8 +510,15 @@ def remove_load(self, about=None):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body, Point
-        >>> B = Body('B')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
         >>> P = Point('P')
         >>> f1 = B.x
         >>> f2 = B.y
@@ -505,9 +558,16 @@ def masscenter_vel(self, body):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body
-        >>> A = Body('A')
-        >>> B = Body('B')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
+        ...     B = Body('B')
         >>> A.masscenter.set_vel(B.frame, 5*B.frame.x)
         >>> A.masscenter_vel(B)
         5*B_frame.x
@@ -536,10 +596,18 @@ def ang_vel_in(self, body):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body, ReferenceFrame
-        >>> A = Body('A')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
         >>> N = ReferenceFrame('N')
-        >>> B = Body('B', frame=N)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B', frame=N)
         >>> A.frame.set_ang_vel(N, 5*N.x)
         >>> A.ang_vel_in(B)
         5*N.x
@@ -568,9 +636,16 @@ def dcm(self, body):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body
-        >>> A = Body('A')
-        >>> B = Body('B')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
+        ...     B = Body('B')
         >>> A.frame.orient_axis(B.frame, B.frame.x, 5)
         >>> A.dcm(B)
         Matrix([
@@ -613,8 +688,15 @@ def parallel_axis(self, point, frame=None):
         Example
         =======
 
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
         >>> from sympy.physics.mechanics import Body
-        >>> A = Body('A')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
         >>> P = A.masscenter.locatenew('point', 3 * A.x + 5 * A.y)
         >>> A.parallel_axis(P).to_matrix(A.frame)
         Matrix([

sympy/physics/mechanics/jointsmethod.py

@@ -11,6 +11,10 @@
 class JointsMethod(_Methods):
     """Method for formulating the equations of motion using a set of interconnected bodies with joints.
 
+    .. deprecated:: 1.13
+        The JointsMethod class is deprecated. Its functionality has been
+        replaced by the new :class:`~.System` class.
+
     Parameters
     ==========
 
@@ -45,6 +49,14 @@ class JointsMethod(_Methods):
     Examples
     ========
 
+    As Body and JointsMethod have been deprecated, the following examples are
+    for illustrative purposes only. The functionality of Body is fully captured
+    by :class:`~.RigidBody` and :class:`~.Particle` and the functionality of
+    JointsMethod is fully captured by :class:`~.System`. To ignore the
+    deprecation warning we can use the ignore_warnings context manager.
+
+    >>> from sympy.utilities.exceptions import ignore_warnings
+
     This is a simple example for a one degree of freedom translational
     spring-mass-damper.
 
@@ -53,12 +65,14 @@ class JointsMethod(_Methods):
     >>> from sympy.physics.vector import dynamicsymbols
     >>> c, k = symbols('c k')
     >>> x, v = dynamicsymbols('x v')
-    >>> wall = Body('W')
-    >>> body = Body('B')
+    >>> with ignore_warnings(DeprecationWarning):
+    ...     wall = Body('W')
+    ...     body = Body('B')
     >>> J = PrismaticJoint('J', wall, body, coordinates=x, speeds=v)
     >>> wall.apply_force(c*v*wall.x, reaction_body=body)
     >>> wall.apply_force(k*x*wall.x, reaction_body=body)
-    >>> method = JointsMethod(wall, J)
+    >>> with ignore_warnings(DeprecationWarning):
+    ...     method = JointsMethod(wall, J)
     >>> method.form_eoms()
     Matrix([[-B_mass*Derivative(v(t), t) - c*v(t) - k*x(t)]])
     >>> M = method.mass_matrix_full
@@ -226,6 +240,15 @@ def form_eoms(self, method=KanesMethod):
         Examples
         ========
 
+        As Body and JointsMethod have been deprecated, the following examples
+        are for illustrative purposes only. The functionality of Body is fully
+        captured by :class:`~.RigidBody` and :class:`~.Particle` and the
+        functionality of JointsMethod is fully captured by :class:`~.System`. To
+        ignore the deprecation warning we can use the ignore_warnings context
+        manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+
         This is a simple example for a one degree of freedom translational
         spring-mass-damper.
 
@@ -235,12 +258,14 @@ def form_eoms(self, method=KanesMethod):
         >>> q = dynamicsymbols('q')
         >>> qd = dynamicsymbols('q', 1)
         >>> m, k, b = symbols('m k b')
-        >>> wall = Body('W')
-        >>> part = Body('P', mass=m)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     wall = Body('W')
+        ...     part = Body('P', mass=m)
         >>> part.potential_energy = k * q**2 / S(2)
         >>> J = PrismaticJoint('J', wall, part, coordinates=q, speeds=qd)
         >>> wall.apply_force(b * qd * wall.x, reaction_body=part)
-        >>> method = JointsMethod(wall, J)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     method = JointsMethod(wall, J)
         >>> method.form_eoms(LagrangesMethod)
         Matrix([[b*Derivative(q(t), t) + k*q(t) + m*Derivative(q(t), (t, 2))]])