README ====== Project Home ------------ The source codes for the **OSCILATE** (Oscillators' nonlinear analysis through SymboliC ImpLementATion of the mEthod of multiple scales) project are hosted on `GitHub `_. Nonlinear systems considered ---------------------------- The **OSCILATE** project allows the application of the **Method of Multiple Scales** (MMS) to a nonlinear equation or systems of :math:`N` coupled nonlinear equations of the form .. math:: \begin{cases} \ddot{x}_0 + \omega_0^2 x_0 & = f_0(\boldsymbol{x}, \dot{\boldsymbol{x}}, \ddot{\boldsymbol{x}}, t), \\ & \vdots \\ \ddot{x}_{N-1} + \omega_{N-1}^2 x_{N-1} & = f_{N-1}(\boldsymbol{x}, \dot{\boldsymbol{x}}, \ddot{\boldsymbol{x}}, t). \end{cases} The :math:`x_i(t)` (:math:`i=0,...,N-1`) are the oscillators' coordinates, .. math:: \boldsymbol{x}(t)^\intercal = [x_0(t), x_1(t), \cdots, x_{N-1}(t)] is the vector containing all the oscillators' coordinates (the :math:`^\intercal` denotes the transpose), :math:`\omega_i` are their natural frequencies, :math:`t` is the time and :math:`\dot{(\bullet)} = \textrm{d}(\bullet)/\textrm{d}t` denotes a time-derivative. The :math:`f_i` are functions which can contain: - **Weak linear terms** in :math:`x_i,\; \dot{x}_i`, or :math:`\ddot{x}_i`. - **Weak linear coupling terms** involving :math:`x_j,\; \dot{x}_j`, or :math:`\ddot{x}_j` with :math:`j \neq i`. - **Weak nonlinear terms**. Taylor expansions are performed to approximate nonlinear terms as *polynomial nonlinearities*. - **Forcing terms**: - Can be hard (appearing at leading order) or weak (small). - Primarily *harmonic*, e.g., :math:`F \cos(\omega t)`, where :math:`F` and :math:`\omega` are the forcing amplitude and frequency, respectively. - Modulated by any function (constant, linear, or nonlinear) to model *parametric* forcing (e.g., :math:`x_i(t) F \cos(\omega t)`). Internal resonance relations among oscillators can be specified in a second step by expressing the :math:`\omega_i` as a function of a reference frequency. Detuning can also be introduced during this step. Details on the Method of Multiple Scales are given in :doc:`mms`. Overview -------- The package associated to the **OSCILATE** project is called :mod:`oscilate`. It is organised as follows: .. code-block:: text oscilate │ sympy_functions.py │ __init__.py │ __version__.py │ └───MMS dyn_sys.py mms.py steady_state.py visualisation.py __init__.py - :py:mod:`oscilate.MMS` module is the MMS solver. It is divided into four sub-modules: - :py:mod:`oscilate.MMS.dyn_sys` sub-module defines the dynamical system of interest, - :py:mod:`oscilate.MMS.mms` sub-module applies the MMS to the dynamical system, - :py:mod:`oscilate.MMS.steady_state` sub-module allows for a steady state analysis, - :py:mod:`oscilate.MMS.visualisation` sub-module contains numerical evaluation and plotting functions, - :py:mod:`oscilate.sympy_functions` module contains additional functions that are not directly related to the MMS but which are used in :py:mod:`oscilate.MMS`. Solver ~~~~~~ :py:mod:`oscilate.MMS` embeds 3 main classes: - :py:class:`oscilate.MMS.dyn_sys.Dynamical_system` : the dynamical system considered - :py:class:`oscilate.MMS.mms.Multiple_scales_system` : the system obtained after applying the MMS to the dynamical system - :py:class:`oscilate.MMS.steady_state.Steady_state` : the MMS results evaluated at steady state and (if computed) the system's response and its stability. These classes are described in details in the :doc:`Modules ` section of the `documentation `_. A visual description of their connection with other classes is provided in :doc:`architecture`. Examples ~~~~~~~~ :doc:`Application examples ` are proposed in the documentation. They include: - The Duffing oscillator - Coupled Duffing oscillators - Coupled nonlinear oscillators with quadratic nonlinearities - Parametrically excited oscillators - Hard forcing of a Duffing oscillator - Subharmonic response of 2 coupled centrifugal pendulum modes .. _outputs_section: Outputs ~~~~~~~ Results are returned as SymPy expressions. They can be printed using :math:`\LaTeX` if the code is ran in an appropriate interactive window. Here are possibilities: - `VS Code's interactive window `_, - `Jupyter notebook `_, - `Spyder's IPython consol `_. SymPy expressions can also be printed as unformatted :math:`\LaTeX` using :: print(vlatex(the_expr)) Methods of :py:class:`oscilate.mms.MMS.Steady_state` also allow to evaluate sympy results for given numerical values of system parameters and to plot them. Citation -------- Please cite this package when using it. See the :doc:`Citation ` section for details. Installation guide ------------------ To install the :mod:`oscilate` package, refer to the :doc:`install` section. Disclaimer ---------- This code is provided as-is and has been tested on a limited number of nonlinear systems. Other test cases might trigger bugs or unexpected behavior that I am not yet aware of. If you encounter any issues, find a bug, or have suggestions for improvements, please feel free to: - Open an issue on the `GitHub repository `_, - Propose a solution, - Contact me directly at [vincent.mahe@ec-nantes.fr]. Your feedback is highly appreciated! Vincent MAHE License ------- This project is licensed under the **Apache License 2.0** – see the LICENSE file for details.