Unifies the shared attributes and methods on all mechanics _Methods subclasses and makes ABC class MethodBase public by moorepants · Pull Request #29815 · sympy/sympy

moorepants · 2026-05-31T06:58:17Z

References to other Issues or PRs

Brief description of what is fixed or changed

We introduced the _Methods abstract base class some time ago and it unified some attributes among the subclasses (KanesMethod, LagrangesMethod, JointsMethod, System) but there were more common attributes that are helpful for downstream consumers of the *Method classes. This PR makes the renamed _Methods -> MethodBase class public and adds more useful attributes and methods:

frame: most common use (LagrangesMethod uses .inertial also)
holonomic_constraints: only was defined on System, configuration_constraints is used as initialization parameter
nonholonomic_constraints: was only defined on System, all classes need this to given strictly the nonholonomic constraints, had to add new initialization parameter to KanesMethod to unify.
velocity_constraints: was defined on System as this and on Lagranges as coneqs, went with velocity_constraints
acceleration_constraints: had to add to all classes, was only stored internally in parts
bodies: on all classes, but deprecating bodylist
loads: on all classes, but deprecating bodylist
constraints_jacobian: not necessarily used in all class (e.g. KanesMethod) but a very common matrix to want, made it a method with a default behavior, may need to reconsider and make it an attribute because it is computed internally in some pieces in all classes, Lagranges was the only class to have it already, but it returned the negation for some reason.

It also deprecates attributes (but not parameters) for forcelist and bodylist in favor of loads and bodies.

Other comments

TODO:

Decide if constraints_jcaobian should be a method or an attribute. If the underlying EoM method does not calculate this internally already, it could have a high computation cost. I try to avoid attributes doing any significant calculation. KanesMethod calculates the coefficients of the independent and dependent speeds in the velocity constraint equations separately, so maybe just assembling those into the constraint jacobian is minimal computation. So maybe I should make it an attribute.

AI Generation Disclosure

No AI was used.

Release Notes

physics.mechanics
- Introduced a new MethodBase abstract base class (moved from private).
- Added common attributes to all subclasses of MethodBase: frame, holonomic_constraints, nonholomic_constraints, velocity_constraints, acceleration_constraints, bodies, loads, constraints_jacobian
- Deprecated forcelist and bodylist attributes from KanesMethod and LagrangesMethod.
- Improved docstring attributes sections of all Methods classes.

…nify the abstract base methods.

… be more uniform and added some new abstract base class attributes.

…gesMethod classes.

…Method.

… LagrangesMethod along with tests.

…anesMethod and JointsMethod. Adds new nonholonomic_constraints parameter to KanesMethod.

… and u are available for all Methods.

sympy-bot · 2026-05-31T06:58:19Z

✅

Hi, I am the SymPy bot. I'm here to help you write a release notes entry. Please read the guide on how to write release notes.

Your release notes are in good order.

Here is what the release notes will look like:

physics.mechanics
- Introduced a new MethodBase abstract base class (moved from private). (#29815 by @moorepants)
- Added common attributes to all subclasses of MethodBase: frame, holonomic_constraints, nonholomic_constraints, velocity_constraints, acceleration_constraints, bodies, loads, constraints_jacobian (#29815 by @moorepants)
- Deprecated forcelist and bodylist attributes from KanesMethod and LagrangesMethod. (#29815 by @moorepants)
- Improved docstring attributes sections of all Methods classes. (#29815 by @moorepants)

This will be added to https://github.com/sympy/sympy/wiki/Release-Notes-for-1.15.

Click here to see the pull request description that was parsed.

<!-- DO NOT DELETE OR REPLACE THIS TEMPLATE or the PR will be closed.

Read our Policy on AI Generated Code and Communication at
https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html.

As required in the policy do not use AI-generated text to complete the PR
description below or the PR will be closed. Follow the instructions in the
template below and keep all section headings or the PR will be closed.

The PR title above should be a short description of what was changed. Do not
include the issue number in the title. -->

#### References to other Issues or PRs

<!-- If there is an issue related to this PR, include a link to the issue here.
It is important not to waste reviewer's time by skipping this section.

If this pull request fixes an issue, write "Fixes #NNNN" in that exact format,
e.g. "Fixes #1234" (see https://tinyurl.com/auto-closing for more information).

If this does not completely fix the issue, then write "See #NNNN" or "partially
fixes #NNNN", e.g. "See #1234" or "partially fixes #1234". -->

Fixes #21772

#### Brief description of what is fixed or changed

We introduced the `_Methods` abstract base class some time ago and it unified some attributes among the subclasses (KanesMethod, LagrangesMethod, JointsMethod, System) but there were more common attributes that are helpful for downstream consumers of the *Method classes. This PR makes the renamed `_Methods` -> `MethodBase` class public and adds more useful attributes and methods:

- frame: most common use (LagrangesMethod uses .inertial also)
- holonomic_constraints: only was defined on System, configuration_constraints is used as initialization parameter
- nonholonomic_constraints: was only defined on System, all classes need this to given strictly the nonholonomic constraints, had to add new initialization parameter to KanesMethod to unify.
- velocity_constraints: was defined on System as this and on Lagranges as coneqs, went with velocity_constraints
- acceleration_constraints: had to add to all classes, was only stored internally in parts
- bodies: on all classes, but deprecating bodylist
- loads: on all classes, but deprecating bodylist
- constraints_jacobian: not necessarily used in all class (e.g. KanesMethod) but a very common matrix to want, made it a method with a default behavior, may need to reconsider and make it an attribute because it is computed internally in some pieces in all classes, Lagranges was the only class to have it already, but it returned the negation for some reason.

It also deprecates attributes (but not parameters) for `forcelist` and `bodylist` in favor of `loads` and `bodies`.

#### Other comments

TODO:

- [x] Decide if constraints_jcaobian should be a method or an attribute. If the underlying EoM method does not calculate this internally already, it could have a high computation cost. I try to avoid attributes doing any significant calculation. KanesMethod calculates the coefficients of the independent and dependent speeds in the velocity constraint equations separately, so maybe just assembling those into the constraint jacobian is minimal computation. So maybe I should make it an attribute.

#### AI Generation Disclosure

<!-- If this pull request includes AI-generated code or text, please disclose
the tool used and specify which lines were generated. Disclosure is not
required for minor assistive tasks, such as spell-checking or code reviewing,
in primarily human-authored work. Otherwise, write "NO AI USE" in the text area
below.

DO NOT just delete this AI section of the PR template and do not leave this
blank, or the PR will be closed. If you write "NO AI USE" and the code looks
like it was generated by AI then the PR will be closed. -->

No AI was used.

#### Release Notes

<!-- Write the release notes for this release below between the BEGIN and END
statements. The basic format is a bulleted list with the name of the subpackage
and the release note for this PR. For example:

* solvers
  * Added a new solver for logarithmic equations.

* functions
  * Fixed a bug with log of integers. Formerly, `log(-x)` incorrectly gave `-log(x)`.

* physics.units
  * Corrected a semantical error in the conversion between volt and statvolt which
    reported the volt as being larger than the statvolt.

or if no release note(s) should be included use:

NO ENTRY

See https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more
information on how to write release notes. The bot will check your release
notes automatically to see if they are formatted correctly. -->

<!-- BEGIN RELEASE NOTES -->

* physics.mechanics
  * Introduced a new `MethodBase` abstract base class (moved from private).
  * Added common attributes to all subclasses of `MethodBase`:  frame, holonomic_constraints, nonholomic_constraints, velocity_constraints, acceleration_constraints, bodies, loads, constraints_jacobian
  * Deprecated `forcelist` and `bodylist` attributes from `KanesMethod` and `LagrangesMethod`.
  * Improved docstring attributes sections of all `Methods` classes.

<!-- END RELEASE NOTES -->

moorepants · 2026-05-31T07:13:01Z

Code quality is failing on some unrelated files:

ERROR: 'sympy.polys.domains.mpelements:ComplexElement' defines slots but superclass does not.
ERROR: 'sympy.polys.domains.mpelements:RealElement' defines slots but superclass does not.

moorepants · 2026-05-31T08:10:37Z

@sympy/mechanics @Peter230655 this PR is ready enough for review. I am prepping it to better work with new updates in PyDy so we can support all Method classes and I have a PR coming with the TMTMethod which will also use this ABC class.

moorepants · 2026-05-31T08:11:31Z

    P.potential_energy = m * g * P.point.pos_from(O).dot(N.y)
    L = Lagrangian(N, P)
-    raises(ValueError, lambda: LagrangesMethod(L, [q], bodies=P))
+    raises(ValueError, lambda: LagrangesMethod(L, [q], bodies=[P]))


I changed this because my internal adjustments caused it to fail on P not being an iterable before catching the incorrect q type.

sympy-bot · 2026-05-31T08:59:52Z

🟠

Hi, I am the SymPy bot. I've noticed that some of your commits add or delete files. Since this is sometimes done unintentionally, I wanted to alert you about it.

This is an experimental feature of SymPy Bot. If you have any feedback on it, please comment at sympy/sympy-bot#75.

The following commits add new files:

bcc9113:
- doc/src/modules/physics/mechanics/api/method.rst

If these files were added/deleted on purpose, you can ignore this message.

…_form_eoms().

moorepants · 2026-05-31T09:12:12Z

+    # LagrangesMethod: (attr) -lam_coeffs
+    # JointsMethod: NA
+    # System: NA
+    def constraints_jacobian(self):


Should this be a method or attribute?

I am going to change this to an attribute. For all methods, if there are constraints, you have to generate the coefficients of the speeds one way or the other. So, all pieces of this matrix will have been computed and made available when the equations are formed. So I think an attribute is suitable in that case.

Done, now a property attribute.

One minor argument for method would be the options to add keyword arguments in the future. I don't have a good example, but if you can immediately think of one for which you wouldn't create a separate method then it might be worth keeping it a method.
In general though, I agree that a property is nicer.

It is similar to mass_matrix in that it is just the linear coefficients of a specific set of equations.

We have multiple mass_matrix attributes and I plan to add a mass_matrix_augmented or something like that soon. You could of course imagine having extract_mass_matrix(full=True, aug=True) instead. For this Jacobian an analogy would be extract_constraint_jacobian(all=True, holonomic=True, nonholonomic=True) or something like that. But having these as methods don't quite align with the existing design which is:

__init__: provide all necessary input and organize the info

_form_eoms(): do the heavy lifting to compute the equations of motion and extract the pieces

.mass_matrix: available after _form_eoms() as a (mostly) precomputed attribute

I just added the correct extraction of this matrix from precomputed matrices in KanesMethod.

tjstienstra

Nice to see the work to make it more generic and available. As I'm just reading it from my phone I've only left some minor comments/suggestions.

moorepants · 2026-06-03T04:39:05Z

This is new to me:

We have never had to have "all comments resolved". Some comments aren't resolved in PRs but can still be merged. This is an odd/annoying new requirement.

oscarbenjamin · 2026-06-03T10:43:58Z

This is an odd/annoying new requirement.

I've removed it in the settings. I think it was something I added when changing a bunch of settings to make the repo more secure but I don't think this particular setting really helps with that.

moorepants · 2026-06-03T11:20:23Z

Thanks @oscarbenjamin, I agree.

…d in all methods.

…y-methods

…trices.

moorepants · 2026-06-05T11:52:30Z

@tjstienstra I think I'm satisfied with this. I mostly copy the well designed System attributes and replicate them in the other methods classes. Maybe the only significant changes otherwise are the new .constraints_jacobian method, the new parameter nonholonomic_constraints for KanesMethod, and deprecating .forcelist and .bodylist attributes. If you have no objections and approval, then maybe we can merge it. Thanks for the review.

moorepants · 2026-06-05T12:24:09Z

This test has timed out for me about 3 or 4 times in this PR:

FAILED sympy/functions/special/tests/test_zeta_functions.py::test_issue_8404 - Failed: Timeout (>10.0s) from pytest-timeout.

moorepants · 2026-06-05T12:51:22Z

I marked the test as slow.

moorepants · 2026-06-10T06:42:23Z

@tjstienstra have I addressed your comments sufficiently? Do you expect more review or possibly think this is good to go in?

moorepants added 11 commits May 30, 2026 21:55

Added comparison of shared attributes among all methods as start to u…

3b451e9

…nify the abstract base methods.

Test should fail because of incorrect q type, not incorrect bodies type.

22802b4

Rearranged and improved LagrangesMethod and KanesMethod docstrings to…

2d0b2c1

… be more uniform and added some new abstract base class attributes.

Deprecate attributes forcelist and bodylist in KanesMethod and Lagran…

703f4c0

…gesMethod classes.

Add .frame attribute to KanesMethod and LagrangesMethod.

0e9eb64

Add holonomic_constraints to all methods classes and .frame to Joints…

cbd5424

…Method.

Added nonholonomic_constraints and velocity_constraints attributes to…

190182a

… LagrangesMethod along with tests.

Add nonholonomic_cosntraints and velocity_constraints attributes to K…

b91f043

…anesMethod and JointsMethod. Adds new nonholonomic_constraints parameter to KanesMethod.

Make constraints_jacobian a method that works if velocity_constraints…

606f8df

… and u are available for all Methods.

Add acceleration_constraints to all methods.

ef0cdd3

Make the proposed augmented matrices private methods for now.

b9b9283

moorepants added 3 commits May 31, 2026 09:03

Add lagrange.py to the whitelist for unicode in the docstring.

da776c7

Rename _Methods class to Method, making it public.

cdbbf4c

Add Method to __all__ in its module.

24fcd2d

moorepants commented May 31, 2026

View reviewed changes

moorepants added 2 commits May 31, 2026 10:56

Improved docstrings of Method.

c1d2a5f

Add docs api page for Method.

bcc9113

Add tests for empty constraints in JointsMethod and include required …

30195a6

…_form_eoms().

moorepants marked this pull request as ready for review May 31, 2026 09:07

moorepants added the physics.mechanics label May 31, 2026

moorepants commented May 31, 2026

View reviewed changes

Merge branch 'master' into unify-methods

494fbb5

moorepants commented Jun 1, 2026

View reviewed changes

Comment thread sympy/physics/mechanics/kane.py Outdated

moorepants mentioned this pull request Jun 1, 2026

Support LagrangesMethod in System pydy/pydy#599

Open

moorepants added 2 commits June 1, 2026 21:10

Fixed merge conflict.

403443c

Move acceleration_constraints fully after velocity_constraints.

8588bb9

tjstienstra reviewed Jun 2, 2026

View reviewed changes

Comment thread sympy/physics/mechanics/method.py Outdated

Comment thread sympy/physics/mechanics/method.py Outdated

moorepants changed the title ~~Unifies the shared attributes and methods on all mechanics _Methods subclasses~~ Unifies the shared attributes and methods on all mechanics _Methods subclasses and makes ABC class MethodBase public Jun 3, 2026

Rename Method to MethodBase.

1a25a58

moorepants mentioned this pull request Jun 3, 2026

Support Lagrange multipliers and Kane's noncontributing forces in MethodBase #29825

Open

Removed notes on lagrange multipliers and augmented equations of motion.

0f1d28a

Convert constraints_jacobian to a property as it should be precompute…

eff586b

…d in all methods.

moorepants mentioned this pull request Jun 4, 2026

Use linear_eq_to_matrix when forming the Lagrange equations where appropriate #29830

Open

moorepants added 8 commits June 4, 2026 20:22

Change title of method doc page to conform to others.

ef08cdf

Merge branch 'unify-methods' of github.com:moorepants/sympy into unif…

ae89d87

…y-methods

Minimized length of cross references.

795206d

Minimized length of cross references.

9b55b01

Construct the constraints Jacobian in KanesMethod from precomputed ma…

34c45bd

…trices.

Added explanation section in docstring.

b2f6651

Fix cross reference.

3d7535a

Added constraints_jacobian to attribute list in KanesMethod and System.

1812b57

Mark test_zeta_functions.py:test_issue_8404 as slow.

ac36adf

This was referenced Jun 7, 2026

Rename constraint evaluate methods to align with the unfied names in SymPy pydy/pydy#619

Closed

Add plotting methods to System() pydy/pydy#610

Open

moorepants commented Jun 7, 2026

View reviewed changes

Comment thread sympy/physics/mechanics/lagrange.py Outdated

moorepants added 2 commits June 7, 2026 09:28

Fix spelling mistakes.

4f5c422

Remove duplicate method.

d8435ba

moorepants mentioned this pull request Jun 7, 2026

Separate holonomic and nonholonomic constraints in System. pydy/pydy#620

Merged

Merge branch 'master' into unify-methods

16623d2

Uh oh!

Conversation

moorepants commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

References to other Issues or PRs

Brief description of what is fixed or changed

Other comments

AI Generation Disclosure

Release Notes

Uh oh!

sympy-bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

moorepants commented May 31, 2026

Uh oh!

moorepants commented May 31, 2026

Uh oh!

moorepants May 31, 2026

Choose a reason for hiding this comment

Uh oh!

sympy-bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟠

Uh oh!

moorepants May 31, 2026

Choose a reason for hiding this comment

Uh oh!

moorepants Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

moorepants Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

tjstienstra Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

moorepants Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

moorepants Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tjstienstra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

moorepants commented Jun 3, 2026

Uh oh!

oscarbenjamin commented Jun 3, 2026

Uh oh!

moorepants commented Jun 3, 2026

Uh oh!

moorepants commented Jun 5, 2026

Uh oh!

moorepants commented Jun 5, 2026

Uh oh!

moorepants commented Jun 5, 2026

Uh oh!

Uh oh!

moorepants commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

moorepants commented May 31, 2026 •

edited

Loading

sympy-bot commented May 31, 2026 •

edited

Loading

sympy-bot commented May 31, 2026 •

edited

Loading

moorepants Jun 4, 2026 •

edited

Loading