pynamicalsys: A Python toolkit for the analysis of dynamical systems

Table of Contents

• Overview
• Related Publication
• Installation
  • Prerequisites
  • Install via PyPI
  • Upgrade via PyPI
  • Install from source
  • Verifying the installation
  • Troubleshooting
• Documentation
• Citation
  • BibTeX
  • API Style
  • Short citation style
• Contributing
• License
• Acknowledgments
• Disclaimer

Overview

pynamicalsys is designed to provide a fast, flexible, and user-friendly environment for analyzing nonlinear dynamical systems. It is intended for students, researchers, educators, and enthusiasts who want to explore the world of chaos and dynamical systems. Beyond standard tools like trajectory generation and Lyapunov exponents calculation, pynamicalsys includes advanced features such as

• Bifurcation diagrams, Poincaré sections, and stroboscopic maps for analyzing system trajectories.
• Symplectic integrators for analyzing Hamiltonian systems.
• Linear dependence index for chaos detection.
• Recurrence plots and recurrence time statistics.
• Chaos indicators based on weighted Birkhoff averages.
• Statistical measures of diffusion and transport in dynamical systems.
• Computation of periodic orbits, their stability and their manifolds.
• Basin metric for quantifying the structure of basins of attraction.
• Plot styling for consistent and customizable visualizations.

pynamicalsys is built on top of NumPy and Numba, ensuring high performance and efficiency. Thanks to Numba accelerated computation, pynamicalsys offers speedups up to 130x compared to the original Python implementation of the algorithms. This makes it suitable for large-scale simulations and analyses.

Related Publication

The methods and applications implemented in pynamicalsys are presented and discussed in our research article:

M. Rolim Sales et al., pynamicalsys: A Python toolkit for the analysis of dynamical systems, Chaos, Solitons and Fractals 201, 117269 (2025).

You can reproduce the numerical experiments, figures, and performance benchmarks presented in the paper using the companion Jupyter notebooks:

• Reproducibility Notebook
• Benchmarks

Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package installer)

Install via PyPI

To install the latest stable release, run in your command line:

pip install pynamicalsys

Note: On Windows, it is strongly recommended to use Anaconda. It simplifies dependency management and avoids potential issues with scientific libraries during installation. Be sure to run the command from the Anaconda Prompt, not from Command Prompt or PowerShell, to ensure the correct environment is activated.

Upgrade via PyPI

To upgrade your current version of pynamicalsys to the latest stable release, run in your command line:

pip install pynamicalsys --upgrade

Install from source

If you want to install the development version from the source repository, clone the repo and install with:

git clone https://github.com/mrolims/pynamicalsys.git
cd pynamicalsys
pip install .

Verifying the installation

After installation, you can verify it by running Python and importing the package:

>>> import pynamicalsys
>>> pynamicalsys.__version__

Troubleshooting

If you encounter any issues, make sure you have the latest version of pip:

pip install --upgrade pip build

Documentation

For detailed instructions, examples, and API references, please visit the full documentation page:

pynamicalsys.readthedocs.io

The documentation includes:

• Getting Started — installation and quick-start examples.
• Tutorial — step-by-step explanations of key concepts and pratical demonstrations.
• API Reference — detailed descriptions of all functions, parameters, and return values.

Citation

If you use pynamicalsys in your work, please cite our research paper. Below are recommended citation formats for different use cases.

BibTeX

@article{pynamicalsys,
  title={pynamicalsys: A Python toolkit for the analysis of dynamical systems},
  author={Matheus Rolim Sales and Leonardo Costa de Souza and Daniel Borin and Michele Mugnaine and José Danilo Szezech and Ricardo Luiz Viana and Iberê Luiz Caldas and Edson Denis Leonel and Chris G. Antonopoulos},
  journal={Chaos, Solitons & Fractals},
  volume={201},
  pages={117269},
  year={2025},
  doi={https://doi.org/10.1016/j.chaos.2025.117269},
  url={https://www.sciencedirect.com/science/article/pii/S0960077925012822},
}

API Style

Rolim Sales, M., Costa de Souza, L., Borin, D., Mugnaine, M., Szezech Jr., J. D., Viana, R. L., Caldas, I. L., Leonel, E. D., & Antonopoulos, C. G. (2025). pynamicalsys: A Python toolkit for the analysis of dynamical systems. Chaos, Solitons & Fractals, 201, 117269. https://doi.org/10.1016/j.chaos.2025.117269

Short citation style

Matheus Rolim Sales et al., "pynamicalsys: A Python toolkit for the analysis of dynamical systems," Chaos, Solitons & Fractals, vol. 201, p. 117269, 2025. https://doi.org/10.1016/j.chaos.2025.117269

Contributing

We welcome contributions from the community! To get started, please see our Contributing Guidelines.

License

This project is licensed under the GNU General Public License v3.0.
See the LICENSE file for details.

Acknowledgments

This project was financed, in part, by the São Paulo Research Foundation (FAPESP, Brazil), under process numbers 2023/08698-9 and 2024/09208-8.

Disclaimer

As opiniões, hipóteses e conclusões ou recomendações expressas neste material são de responsabilidade do(s) autor(es) e não necessariamente refletem a visão da Fundação de Amparo à Pesquisa do Estado de São Paulo (FAPESP, Brasil).

The opinions, hypotheses, and conclusions or recommendations expressed in this material are the sole responsibility of the author(s) and do not necessarily reflect the views of the São Paulo Research Foundation (FAPESP, Brazil).