Implement Duffing Spring Actuator.py

[eh111eh]

References to other Issues or PRs

#26402

Brief description of what is fixed or changed

The Duffing equation is a nonlinear second order differential equation used to model the dynamics of systems, damped and driven oscillators, with a cubic nonlinearity in the restoring force, which is given by $$\ddot{x} + \delta\dot{x} + \beta x + \alpha x^3 = \gamma \cos(\omega t)$$

However, as a full Duffing second order forced system will not work as an actuator, I modify the Duffing Spring to treat it as a non-second order system.
For $\beta>0$, the Duffing oscillator can be interpreted as a forced oscillator with a spring whose restoring force is written as $$F = -\beta x - \alpha x^3$$
Since the case $\beta<0$ causes the chaotic motions, I will not consider this case for now.

I Implemented a new class DuffingSpring to model the force exerted by a nonlinear spring, based on the Duffing equation: $F = -\beta x - \alpha x^3$
where $x$ is the displacement from the equilibrium position, $\beta$ is the linear spring constant, and $\alpha$ is the coefficient for the nonlinear cubic term.

Task

• Add a unit test to verify the new class DuffingSpring works as expected. Refer to the existing unit tests for actuators as examples.
• Demonstrate the force exerted by a nonlinear spring, based on the Duffing equation, as illustrated in the following example: https://pydy.readthedocs.io/en/latest/examples/mass-spring-damper.html

Other comments

Reference

• http://www.scholarpedia.org/article/Duffing_oscillator
• https://www.cfm.brown.edu/people/dobrush/am34/Matlab/ch3/duffing.html
• https://www.cfm.brown.edu/people/dobrush/am34/Mathematica/ch3/duffing.html

Release Notes

• physics.mechanics
  • implemented DuffingSpring to model the force exerted by a nonlinear spring, based on the Duffing equation

[sympy-bot]

✅

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
  • implemented DuffingSpring to model the force exerted by a nonlinear spring, based on the Duffing equation (#26438 by @eh111eh)

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

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

<!-- Your 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 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). Also, please
write a comment on that issue linking back to this pull request once it is
open. -->
#26402 

#### Brief description of what is fixed or changed
The Duffing equation is a nonlinear second order differential equation used to model the dynamics of systems, damped and driven oscillators, with a cubic nonlinearity in the restoring force, which is given by $$\\ddot{x} + \delta\dot{x} + \beta x + \alpha x^3 = \gamma \cos(\omega t)\$$

However, as a full Duffing second order forced system will not work as an actuator, I modify the Duffing Spring to treat it as a non-second order system.
For $\beta>0$, the Duffing oscillator can be interpreted as a forced oscillator with a spring whose restoring force is written as $$F = -\beta x - \alpha x^3$$
Since the case  $\beta<0$ causes the chaotic motions, I will not consider this case for now. 

I Implemented a new class `DuffingSpring` to model the force exerted by a nonlinear spring, based on the Duffing equation: $F = -\beta x - \alpha x^3$
where $x$ is the displacement from the equilibrium position, $\beta$ is the linear spring constant, and $\alpha$ is the coefficient for the nonlinear cubic term.

#### Task
- [ ] Add a unit test to verify the new class `DuffingSpring` works as expected. Refer to the existing unit tests for actuators as examples.
- [ ] Demonstrate the force exerted by a nonlinear spring, based on the Duffing equation, as illustrated in the following example: https://pydy.readthedocs.io/en/latest/examples/mass-spring-damper.html

#### Other comments
Reference
- http://www.scholarpedia.org/article/Duffing_oscillator 
- https://www.cfm.brown.edu/people/dobrush/am34/Matlab/ch3/duffing.html
- https://www.cfm.brown.edu/people/dobrush/am34/Mathematica/ch3/duffing.html

#### 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
  * implemented `DuffingSpring` to model the force exerted by a nonlinear spring, based on the Duffing equation
<!-- END RELEASE NOTES -->

Update

The release notes on the wiki have been updated.

[eh111eh]

Hi, I've added a test unit for the DuffingSpring class in test_actuator.py and made minor modifications to the DuffingSpring class itself. The test unit covers the following functionalities:

• Fixture Setup
• Inheritance Checks
• Parametrized Tests
• Constructor Validity
• Invalid Constructor Arguments
• Immutability of Properties
• String Representation
• Force Calculation

All tests pass in pytest. I would greatly appreciate any feedback or comments on this work. Thank you!

[tjstienstra]

I am not familiar with the Duffing spring, but the implementation looks mostly good to me. Just suggested a few minor changes.

[tjstienstra]

@eh111eh don't forget to add yourself to the mailmap.

[eh111eh]

I am not familiar with the Duffing spring, but the implementation looks mostly good to me. Just suggested a few minor changes.

Thank you for your thorough feedback. I have made the following changes:

• Added a blank line before and after Explanation and Parameters.
• Removed the try statement.
• Modified the setters to match the implementation in other classes, such as LinearSpring.
• Removed simplify from the displacement calculation. I originally applied simplify to resolve an issue where the actual force output did not match the expected force output and forgot to revert it after resolving it.
• Avoided repeating tests in test_actuator.py and added tests for None.
• Added my name and email to the mailmap.

I would appreciate your comments and feedback. Thank you!

[github-actions]

Benchmark results from GitHub Actions

Lower numbers are good, higher numbers are bad. A ratio less than 1
means a speed up and greater than 1 means a slowdown. Green lines
beginning with + are slowdowns (the PR is slower then master or
master is slower than the previous release). Red lines beginning
with - are speedups.

Significantly changed benchmark results (PR vs master)

Significantly changed benchmark results (master vs previous release)

| Change   | Before [2487dbb5]    | After [b9bafe06]    |   Ratio | Benchmark (Parameter)                                                |
|----------|----------------------|---------------------|---------|----------------------------------------------------------------------|
| -        | 68.3±1ms             | 44.3±0.5ms          |    0.65 | integrate.TimeIntegrationRisch02.time_doit(10)                       |
| -        | 68.4±1ms             | 43.1±0.2ms          |    0.63 | integrate.TimeIntegrationRisch02.time_doit_risch(10)                 |
| +        | 18.6±0.2μs           | 30.2±0.2μs          |    1.63 | integrate.TimeIntegrationRisch03.time_doit(1)                        |
| -        | 5.31±0.02ms          | 2.82±0.01ms         |    0.53 | logic.LogicSuite.time_load_file                                      |
| -        | 72.9±0.3ms           | 29.0±0.1ms          |    0.4  | polys.TimeGCD_GaussInt.time_op(1, 'dense')                           |
| -        | 25.9±0.1ms           | 16.9±0.06ms         |    0.65 | polys.TimeGCD_GaussInt.time_op(1, 'expr')                            |
| -        | 73.6±0.4ms           | 29.3±0.2ms          |    0.4  | polys.TimeGCD_GaussInt.time_op(1, 'sparse')                          |
| -        | 258±2ms              | 126±0.7ms           |    0.49 | polys.TimeGCD_GaussInt.time_op(2, 'dense')                           |
| -        | 258±2ms              | 126±0.6ms           |    0.49 | polys.TimeGCD_GaussInt.time_op(2, 'sparse')                          |
| -        | 652±3ms              | 384±1ms             |    0.59 | polys.TimeGCD_GaussInt.time_op(3, 'dense')                           |
| -        | 654±5ms              | 376±2ms             |    0.57 | polys.TimeGCD_GaussInt.time_op(3, 'sparse')                          |
| -        | 502±2μs              | 290±3μs             |    0.58 | polys.TimeGCD_LinearDenseQuadraticGCD.time_op(1, 'dense')            |
| -        | 1.81±0.01ms          | 1.05±0.01ms         |    0.58 | polys.TimeGCD_LinearDenseQuadraticGCD.time_op(2, 'dense')            |
| -        | 5.85±0.02ms          | 3.11±0.01ms         |    0.53 | polys.TimeGCD_LinearDenseQuadraticGCD.time_op(3, 'dense')            |
| -        | 446±2μs              | 234±3μs             |    0.53 | polys.TimeGCD_QuadraticNonMonicGCD.time_op(1, 'dense')               |
| -        | 1.50±0.01ms          | 697±6μs             |    0.46 | polys.TimeGCD_QuadraticNonMonicGCD.time_op(2, 'dense')               |
| -        | 4.92±0.02ms          | 1.65±0.01ms         |    0.34 | polys.TimeGCD_QuadraticNonMonicGCD.time_op(3, 'dense')               |
| -        | 378±2μs              | 206±1μs             |    0.55 | polys.TimeGCD_SparseGCDHighDegree.time_op(1, 'dense')                |
| -        | 2.44±0.01ms          | 1.23±0.01ms         |    0.5  | polys.TimeGCD_SparseGCDHighDegree.time_op(3, 'dense')                |
| -        | 10.1±0.05ms          | 4.36±0.04ms         |    0.43 | polys.TimeGCD_SparseGCDHighDegree.time_op(5, 'dense')                |
| -        | 361±3μs              | 173±1μs             |    0.48 | polys.TimeGCD_SparseNonMonicQuadratic.time_op(1, 'dense')            |
| -        | 2.52±0.01ms          | 901±9μs             |    0.36 | polys.TimeGCD_SparseNonMonicQuadratic.time_op(3, 'dense')            |
| -        | 9.59±0.02ms          | 2.64±0.02ms         |    0.28 | polys.TimeGCD_SparseNonMonicQuadratic.time_op(5, 'dense')            |
| -        | 1.05±0.01ms          | 428±2μs             |    0.41 | polys.TimePREM_LinearDenseQuadraticGCD.time_op(3, 'dense')           |
| -        | 1.73±0ms             | 499±2μs             |    0.29 | polys.TimePREM_LinearDenseQuadraticGCD.time_op(3, 'sparse')          |
| -        | 5.93±0.05ms          | 1.81±0.02ms         |    0.31 | polys.TimePREM_LinearDenseQuadraticGCD.time_op(5, 'dense')           |
| -        | 8.56±0.04ms          | 1.49±0ms            |    0.17 | polys.TimePREM_LinearDenseQuadraticGCD.time_op(5, 'sparse')          |
| -        | 286±0.9μs            | 66.8±0.5μs          |    0.23 | polys.TimePREM_QuadraticNonMonicGCD.time_op(1, 'sparse')             |
| -        | 3.44±0.02ms          | 397±2μs             |    0.12 | polys.TimePREM_QuadraticNonMonicGCD.time_op(3, 'dense')              |
| -        | 3.97±0.03ms          | 279±1μs             |    0.07 | polys.TimePREM_QuadraticNonMonicGCD.time_op(3, 'sparse')             |
| -        | 7.10±0.03ms          | 1.28±0.01ms         |    0.18 | polys.TimePREM_QuadraticNonMonicGCD.time_op(5, 'dense')              |
| -        | 8.75±0.02ms          | 834±2μs             |    0.1  | polys.TimePREM_QuadraticNonMonicGCD.time_op(5, 'sparse')             |
| -        | 5.00±0.02ms          | 2.95±0.02ms         |    0.59 | polys.TimeSUBRESULTANTS_LinearDenseQuadraticGCD.time_op(2, 'sparse') |
| -        | 12.2±0.06ms          | 6.61±0.04ms         |    0.54 | polys.TimeSUBRESULTANTS_LinearDenseQuadraticGCD.time_op(3, 'dense')  |
| -        | 22.4±0.06ms          | 9.01±0.02ms         |    0.4  | polys.TimeSUBRESULTANTS_LinearDenseQuadraticGCD.time_op(3, 'sparse') |
| -        | 5.21±0.02ms          | 859±4μs             |    0.16 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(1, 'sparse')    |
| -        | 12.6±0.04ms          | 7.03±0.02ms         |    0.56 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(2, 'sparse')    |
| -        | 103±0.6ms            | 25.8±0.2ms          |    0.25 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(3, 'dense')     |
| -        | 166±0.9ms            | 54.0±0.1ms          |    0.32 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(3, 'sparse')    |
| -        | 171±0.8μs            | 111±0.6μs           |    0.65 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(1, 'dense')      |
| -        | 358±0.7μs            | 218±1μs             |    0.61 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(1, 'sparse')     |
| -        | 4.34±0.02ms          | 846±6μs             |    0.19 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(3, 'dense')      |
| -        | 5.29±0.06ms          | 383±1μs             |    0.07 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(3, 'sparse')     |
| -        | 19.9±0.1ms           | 2.83±0.02ms         |    0.14 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(5, 'dense')      |
| -        | 22.8±0.1ms           | 626±5μs             |    0.03 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(5, 'sparse')     |
| -        | 480±2μs              | 140±0.5μs           |    0.29 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(1, 'sparse') |
| -        | 4.75±0.01ms          | 621±6μs             |    0.13 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(3, 'dense')  |
| -        | 5.33±0.03ms          | 141±1μs             |    0.03 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(3, 'sparse') |
| -        | 13.3±0.2ms           | 1.31±0.01ms         |    0.1  | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(5, 'dense')  |
| -        | 13.8±0.1ms           | 144±0.8μs           |    0.01 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(5, 'sparse') |
| -        | 133±1μs              | 74.2±1μs            |    0.56 | solve.TimeMatrixOperations.time_rref(3, 0)                           |
| -        | 247±1μs              | 86.7±0.2μs          |    0.35 | solve.TimeMatrixOperations.time_rref(4, 0)                           |
| -        | 24.6±0.1ms           | 10.2±0.03ms         |    0.41 | solve.TimeSolveLinSys189x49.time_solve_lin_sys                       |
| -        | 28.3±0.1ms           | 15.6±0.3ms          |    0.55 | solve.TimeSparseSystem.time_linsolve_Aaug(20)                        |
| -        | 54.6±0.3ms           | 24.8±0.09ms         |    0.45 | solve.TimeSparseSystem.time_linsolve_Aaug(30)                        |
| -        | 28.2±0.2ms           | 15.2±0.1ms          |    0.54 | solve.TimeSparseSystem.time_linsolve_Ab(20)                          |
| -        | 54.6±0.3ms           | 24.5±0.07ms         |    0.45 | solve.TimeSparseSystem.time_linsolve_Ab(30)                          |

Full benchmark results can be found as artifacts in GitHub Actions
(click on checks at the top of the PR).

[tjstienstra]

LGTM