VOFD Python Package

Overview

The VOFD Python package provides tools for simulating and solving Variable-Order Fractional Derivatives (VOFD) in dynamical systems. This package is designed for researchers and practitioners to analyze and visualize systems modeled with variable-order derivatives, such as chaotic systems, hereditary processes, and control strategies.

The package supports three main types of VO derivatives:

• V1: Caputo Variable-Order Derivative.
• V2,V3: Variable-Order Derivatives with convolution.

Overview

VOFD provides high-performance numerical routines accelerated with the Numba JIT compiler. The package includes:

• Caputo variable-order derivatives (V1)
• Convolution-based VO derivatives (V2 and V3)
• Simulation of nonlinear and chaotic systems with time-varying fractional order
• Parallel computation of bifurcation diagrams
• Plotting utilities for time-series, phase portraits, and bifurcation structures

The use of Numba significantly reduces computation time in derivative evaluation and large-scale bifurcation analysis, enabling efficient exploration of variable-order fractional models.

This package is part of an ongoing research project on variable-order fractional modeling and its applications in nonlinear system analysis. The numerical schemes implemented are based on the finite-difference approximations described in: B. Parsa Moghaddam and J. A. Tenreiro Machado, “Extended Algorithms for Approximating Variable Order Fractional Derivatives with Applications,” Journal of Scientific Computing, 2017. DOI: 10.1007/s10915-016-0343-1.

Repository Structure

VOFD/
│
├── vofd/                  # The Python package
│   ├── __init__.py
│   ├── maxima.py  
│   ├── plot_data.py
│   ├── vo_core.py
│   │__ sim_manager.py
│
├── examples/              # Example scripts
│   ├── sim_vo_ricatti.py
│   ├── sim_vo_chen.py
│   ├── sim_5Dvo_Lorenz.py
│   ├── bif_vo_chen.py
│   ├── bif_5Dvo_Lorenz.py
│
├── LICENSE
├── README.md
├── pyproject.toml


# Installation Options

You can install VOFD in two ways:
(1) via PyPI or (2) directly from the source repository.

---

## **Option 1 — Install from PyPI (recommended)**

```bash
pip install vofd

Recommended workflow:

1. Create a working directory:

   mkdir VOFD_analysis
   cd VOFD_analysis
   

2. (Optional) activate a Python virtual environment:

   Linux/macOS

   python3 -m venv venv
   source venv/bin/activate
   

   Windows

   python -m venv venv
   venv\Scripts\activate
   

3. Install the package:

   pip install vofd
   

4. Download the example scripts from the GitHub repository (examples/) and run with python:

   python sim_vo_chen.py
   python bif_vo_chen.py
   

Option 2 — Clone the Repository and Install Locally

1. Clone:

   git clone https://github.com/DClementeL/VOFD.git
   cd VOFD
   

2. (Optional) activate a Python virtual environment:

   Linux/macOS

   python3 -m venv venv
   source venv/bin/activate
   

   Windows

   python -m venv venv
   .\venv\Scripts\activate
   

3. Install:

   pip install -e .
   

This provides access to:

• Full source code (vofd/)
• Example scripts (examples/)
• Development configuration

Usage

Simulation Setup (sim_vo_chen.py)

This script demonstrates how to set up and run a simulation for a --Variable-Order Chaotic Chen System--

1. Setup the system: The script defines the Chen system, a commonly used chaotic system, with initial conditions and a time span.

2. Run the simulation: It computes the trajectory of the system using a VO derivative.

3. Output: The script saves the results of the simulation (y1, y2, y3) into .txt files and generates a plot of y1 vs. y2. y1 vs. y3 and y2 vs. y3.

To run the simulation, simply execute:

python sim_vo_chen.py

Bifurcation Analysis Setup (bif_vo_chen.py)

This script is used to perform --bifurcation analysis-- of the --Variable-Order Chaotic Chen System--.

1. Setup the system: Similar to the simulation script, but this one focuses on analyzing how the system behavior changes as the bifurcation parameter (in this case the a parameter), varies.

2. Bifurcation Process: The script calculates bifurcation points for svar and xmax and stores them in .txt files.

3. Output: The bifurcation analysis results are visualized in a plot.

To run the bifurcation analysis, execute:

python bif_vo_chen.py

Key Functions

chen_system: Defines the equations of the Chen system (used in both scripts). vo_algorithm: Variable-order derivative algorithm used for numerical integration.

• In sim_vo_chen.py: you may use v1_alg, v2_alg, or v3_alg.
• In bif_vo_chen.py: you may use v1_bifurcation, v2_bifurcation, or v3_bifurcation.

save_pairwise_plots: Generates automatic pairwise phase-plane plots, e.g., y1–y2, y1–y3 and y2-y3. create_xy_figure: Plots phase portraits, time-evolution curves, and bifurcation diagrams with automatic axis scaling. Plot specifications are optional for phase portraits and time-evolution diagrams, while bifurcation diagrams require specifying the scatter plot option. save_time_series: Saves each state variable (y1, y2, y3) to .txt files. save_bifurcation_data: Stores the bifurcation values (e.g., parameter sweep and maxima) into .txt files.

Results Directory

results/

Plots, time-series, and bifurcation data are stored here. The folder is generated automatically if it does not exist.

License

The VOFD package is released under the MIT License.