# Lyapynov
Lyapynov is a Python library to compute Lyapunov exponents, covariant Lyapunov vectors (CLV) and their adjoints for a dynamical system.
The results/algorithms used are taken from [P. Kuptsov's paper on covariant Lyapunov vectors](https://arxiv.org/abs/1105.5228).
## Installation
Use the package manager pip to install Lyapynov.
```bash
pip install lyapynov
```
## Usage
First, one needs to define the system to study (which can be discrete or continuous) using the ContinuousDS or DiscreteDS methods. These methods take the following parameters as input:
* the initial conditions $x_{0}$ and $t_{0}$ $(x(t_{0}) = x_{0})$.
* the function $f$ describing the dynamical system:
```math
\left\{
\begin{array}{ll}
\dot{x} = f(x,t) \\
x_{n+1} = f(x_{n},n)
\end{array}
\right.
```
* the jacobian of $f$ with respect to $x$ or $x_{n}$:
```math
\left\{
\begin{array}{ll}
J(x,t) = \displaystyle \frac{\partial f}{\partial x}(x,t) \\
~ \\
J(x_{n},n) = \displaystyle \frac{\partial f}{\partial x_{n}}(x_{n},n)
\end{array}
\right.
```
</br>
```python
import lyapynov
# Continous dynamical system
continuous_system = lyapynov.ContinuousDS(x0, t0, f, jac, dt)
# Discrete dynamical system
discrete_system = lyapynov.DiscreteDS(x0, t0, f, jac)
```
</br>
</br>
Once the dynamic system has been defined, the following functions can be used:
</br>
* Maximum Lyapunov exponents (MLE) to compute the maximum Lyapunov exponent $\lambda_{1}$.
```python
def mLCE(system : DynamicalSystem, n_forward : int, n_compute : int, keep : bool):
'''
Compute the maximal 1-LCE.
Parameters:
system (DynamicalSystem): Dynamical system for which we want to compute the mLCE.
n_forward (int): Number of steps before starting the mLCE computation.
n_compute (int): Number of steps to compute the mLCE, can be adjusted using keep_evolution.
keep (bool): If True return a numpy array of dimension (n_compute,) containing the evolution of mLCE.
Returns:
mLCE (float): Maximum 1-LCE.
history (numpy.ndarray): Evolution of mLCE during the computation.
'''
```
</br>
* Lyapunov characteristic exponents (LCE) to compute the $p$ first Lyapunov exponents $(\lambda_{1}, \cdots, \lambda_{p})$.
```python
def LCE(system : DynamicalSystem, p : int, n_forward : int, n_compute : int, keep : bool):
'''
Compute LCE.
Parameters:
system (DynamicalSystem): Dynamical system for which we want to compute the LCE.
p (int): Number of LCE to compute.
n_forward (int): Number of steps before starting the LCE computation.
n_compute (int): Number of steps to compute the LCE, can be adjusted using keep_evolution.
keep (bool): If True return a numpy array of dimension (n_compute,p) containing the evolution of LCE.
Returns:
LCE (numpy.ndarray): Lyapunov Charateristic Exponents.
history (numpy.ndarray): Evolution of LCE during the computation.
'''
```
</br>
* Covariant Lyapunov vectors (CLV) to compute covariant Lyapunov vectors $\Gamma(t) = [\gamma_{1}(t), \cdots, \gamma_{m}(t)]$.
```python
def CLV(system : DynamicalSystem, p : int, n_forward : int, n_A : int, n_B : int, n_C : int, traj : bool, check = False):
'''
Compute CLV.
Parameters:
system (DynamicalSystem): Dynamical system for which we want to compute the mLCE.
p (int): Number of CLV to compute.
n_forward (int): Number of steps before starting the CLV computation.
n_A (int): Number of steps for the orthogonal matrice Q to converge to BLV.
n_B (int): Number of time steps for which Phi and R matrices are stored and for which CLV are computed.
n_C (int): Number of steps for which R matrices are stored in order to converge A to A-.
traj (bool): If True return a numpy array of dimension (n_B,system.dim) containing system's trajectory at the times CLV are computed.
Returns:
CLV (List): List of numpy.array containing CLV computed during n_B time steps.
history (numpy.ndarray): Trajectory of the system during the computation of CLV.
'''
```
</br>
* Adjoint covariant vectors (ADJ) to compute the adjoints of CLV $\Theta(t) = [\theta_{1}(t), \cdots, \theta_{m}(t)]$ such that $\Gamma(t)^{T} \Theta(t) = D(t)$ .
```python
def ADJ(CLV : list):
'''
Compute adjoints vectors of CLV.
Parameters:
CLV (list): List of np.ndarray containing CLV at each time step: [CLV(t1), ...,CLV(tn)].
Returns:
ADJ (List): List of numpy.array containing adjoints of CLV at each time step (each column corresponds to an adjoint).
'''
```
</br>
</br>
An example of using the package is given in the notebook Example.ipynb.
Raw data
{
"_id": null,
"home_page": "https://github.com/ThomasSavary08/Lyapynov",
"name": "lyapynov",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Lyapunov,Lyapunov exponents,LCE,Covariant Lyapunov vectors,CLV,Dynamical systems,ODE",
"author": "Thomas Savary",
"author_email": "savarythomas2102@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6a/af/75dc30e566baf60461694e71e7ac9645ce55d8dfe738043a07a0e34f7490/lyapynov-1.0.1.tar.gz",
"platform": null,
"description": "# Lyapynov\n\nLyapynov is a Python library to compute Lyapunov exponents, covariant Lyapunov vectors (CLV) and their adjoints for a dynamical system.\nThe results/algorithms used are taken from [P. Kuptsov's paper on covariant Lyapunov vectors](https://arxiv.org/abs/1105.5228).\n\n## Installation\n\nUse the package manager pip to install Lyapynov.\n\n```bash\npip install lyapynov\n```\n\n## Usage\n\nFirst, one needs to define the system to study (which can be discrete or continuous) using the ContinuousDS or DiscreteDS methods. These methods take the following parameters as input:\n* the initial conditions $x_{0}$ and $t_{0}$ $(x(t_{0}) = x_{0})$.\n* the function $f$ describing the dynamical system:\n```math\n\\left\\{\n \\begin{array}{ll}\n \\dot{x} = f(x,t) \\\\\n x_{n+1} = f(x_{n},n)\n \\end{array}\n\\right. \n```\n* the jacobian of $f$ with respect to $x$ or $x_{n}$:\n```math\n\\left\\{\n \\begin{array}{ll}\n J(x,t) = \\displaystyle \\frac{\\partial f}{\\partial x}(x,t) \\\\\n ~ \\\\\n J(x_{n},n) = \\displaystyle \\frac{\\partial f}{\\partial x_{n}}(x_{n},n)\n \\end{array}\n\\right. \n```\n\n</br>\n\n```python\nimport lyapynov\n\n# Continous dynamical system\ncontinuous_system = lyapynov.ContinuousDS(x0, t0, f, jac, dt)\n\n# Discrete dynamical system\ndiscrete_system = lyapynov.DiscreteDS(x0, t0, f, jac)\n```\n\n</br>\n</br>\n\nOnce the dynamic system has been defined, the following functions can be used:\n\n</br>\n\n* Maximum Lyapunov exponents (MLE) to compute the maximum Lyapunov exponent $\\lambda_{1}$.\n```python\ndef mLCE(system : DynamicalSystem, n_forward : int, n_compute : int, keep : bool):\n '''\n Compute the maximal 1-LCE.\n Parameters:\n system (DynamicalSystem): Dynamical system for which we want to compute the mLCE.\n n_forward (int): Number of steps before starting the mLCE computation. \n n_compute (int): Number of steps to compute the mLCE, can be adjusted using keep_evolution.\n keep (bool): If True return a numpy array of dimension (n_compute,) containing the evolution of mLCE.\n Returns:\n mLCE (float): Maximum 1-LCE.\n history (numpy.ndarray): Evolution of mLCE during the computation.\n '''\n```\n\n</br>\n\n* Lyapunov characteristic exponents (LCE) to compute the $p$ first Lyapunov exponents $(\\lambda_{1}, \\cdots, \\lambda_{p})$.\n```python\ndef LCE(system : DynamicalSystem, p : int, n_forward : int, n_compute : int, keep : bool):\n '''\n Compute LCE.\n Parameters:\n system (DynamicalSystem): Dynamical system for which we want to compute the LCE.\n p (int): Number of LCE to compute.\n n_forward (int): Number of steps before starting the LCE computation. \n n_compute (int): Number of steps to compute the LCE, can be adjusted using keep_evolution.\n keep (bool): If True return a numpy array of dimension (n_compute,p) containing the evolution of LCE.\n Returns:\n LCE (numpy.ndarray): Lyapunov Charateristic Exponents.\n history (numpy.ndarray): Evolution of LCE during the computation.\n '''\n```\n\n</br>\n\n\n* Covariant Lyapunov vectors (CLV) to compute covariant Lyapunov vectors $\\Gamma(t) = [\\gamma_{1}(t), \\cdots, \\gamma_{m}(t)]$.\n```python\ndef CLV(system : DynamicalSystem, p : int, n_forward : int, n_A : int, n_B : int, n_C : int, traj : bool, check = False):\n '''\n Compute CLV.\n Parameters:\n system (DynamicalSystem): Dynamical system for which we want to compute the mLCE.\n p (int): Number of CLV to compute.\n n_forward (int): Number of steps before starting the CLV computation. \n n_A (int): Number of steps for the orthogonal matrice Q to converge to BLV.\n n_B (int): Number of time steps for which Phi and R matrices are stored and for which CLV are computed.\n n_C (int): Number of steps for which R matrices are stored in order to converge A to A-. \n traj (bool): If True return a numpy array of dimension (n_B,system.dim) containing system's trajectory at the times CLV are computed.\n Returns:\n CLV (List): List of numpy.array containing CLV computed during n_B time steps.\n history (numpy.ndarray): Trajectory of the system during the computation of CLV.\n '''\n```\n\n</br>\n\n\n* Adjoint covariant vectors (ADJ) to compute the adjoints of CLV $\\Theta(t) = [\\theta_{1}(t), \\cdots, \\theta_{m}(t)]$ such that $\\Gamma(t)^{T} \\Theta(t) = D(t)$ .\n```python\ndef ADJ(CLV : list):\n '''\n Compute adjoints vectors of CLV.\n Parameters:\n CLV (list): List of np.ndarray containing CLV at each time step: [CLV(t1), ...,CLV(tn)].\n Returns:\n ADJ (List): List of numpy.array containing adjoints of CLV at each time step (each column corresponds to an adjoint).\n '''\n```\n\n</br>\n</br>\nAn example of using the package is given in the notebook Example.ipynb.\n",
"bugtrack_url": null,
"license": "",
"summary": "A python package to compute Lyapunov exponents, covariant Lyapunov vectors (CLV) and adjoints of a dynamical system.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/ThomasSavary08/Lyapynov"
},
"split_keywords": [
"lyapunov",
"lyapunov exponents",
"lce",
"covariant lyapunov vectors",
"clv",
"dynamical systems",
"ode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6aaf75dc30e566baf60461694e71e7ac9645ce55d8dfe738043a07a0e34f7490",
"md5": "5badd79b33b9e2774cdaa795000ea94e",
"sha256": "b45cf601c0abf23bb35daed15194873d6b08537a4b27163a36af28a987830289"
},
"downloads": -1,
"filename": "lyapynov-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5badd79b33b9e2774cdaa795000ea94e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5330,
"upload_time": "2023-09-18T14:01:35",
"upload_time_iso_8601": "2023-09-18T14:01:35.771324Z",
"url": "https://files.pythonhosted.org/packages/6a/af/75dc30e566baf60461694e71e7ac9645ce55d8dfe738043a07a0e34f7490/lyapynov-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-18 14:01:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ThomasSavary08",
"github_project": "Lyapynov",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "lyapynov"
}
JSON
