Pt 2.2 - Decochators Pypi Package – yoshl

Pt 2.2 - Decochators Pypi Package

decochators is a library to facilitate the study (visualization and analysis) of chaotic systems focused on application in CBE (Chaos-Based-Encryption) algorithms.

Structure

Class chaoticMap
│
├── Inherited class mth (Analysis)
│   │
│   ├── func Lyapunov
│   ├── func Kolmogorov-Sinai
│   ├── func Test 0-1
│   └── func Binarized Test 0-1
│
└── Inherited class vwr (Visualization)
    │
    ├── func Draw
    ├── func Bifurcation
    └── func Test 0-1

How it works

Section not included in Pypi package: https://pypi.org/project/decochators/

Based on the interactive decorator attach_chaos_tests, we wrap a function intoa class that generates two sub-namespaces (mth & vwr), each exposing a fixed set of internal methods. The main and useful namespace is mth, refferring to the word: maths is the main way to calculte common tests debated in Creation your own Chaos System.

In the Python module we can appreciate the following file structure:

Decochators Source Code
├── core
│   └── __init__.py
│
├── dimensions
│   ├── __init__.py
│   │
│   ├── one_dimension
│   │   ├── attach_chaos_1d.py
│   │   └── __init__.py
│   │
│   └── three_dimensions
│       ├── attach_chaos_3d.py
│       └── __init__.py
│
├── helpers
│   ├── core_1d.py
│   ├── core_3d.py
│   └── __init__.py
│
└── __init__.py

core.py

Generally, the main code allocates inside core, where transform the simple chaotic function into a “rich object” with mathematical (mth) and visualization (vwr) tools (sub-namespaces).

class ChaosDecoratorBase:
    def __init__()
    def __call__():
        def wrapper()
        
        def _build_mth()
        def _build_vwr()

(one/three)_dimension.py

The core of one & three dimensional systems, where calls and maps functions used for the analysis and visualization of the systems, the structure used is the following:

class Chaos1D(ChaosDecoratorBase): or class Chaos3D(ChaosDecoratorBase): 
    def _build_mth(self, wrapper):
       class mth:
            @staticmethod
            def lyapunov() # calls lyapunov_(1d/3d)

            @staticmethod
            def btest01() # calls btest01_(1d/3d)

            @staticmethod
            def test01() # calls test01_(1d/3d)

            @staticmethod
            def ks() # calls ks_(1d/3d)

        class vwr:
            @staticmethod
            def draw()

            @staticmethod
            def test01()

            @staticmethod
            def bifurcation()

def attach_chaos_tests_1d() or def attach_chaos_tests_3d()

helpers/core_(1d/3d).py

Functions called in (one/three)_dimension.py, simple code with same name functions than the file mentioned, important method to name is the flexibility of new functions and analysis methods thanks to the configuration inside __init__.py:

import inspect
import importlib

__all__ = []

def _import_with_suffix(module_name: str, suffix: str):
    mod = importlib.import_module(f".{module_name}", package=__name__)
    for name, obj in inspect.getmembers(mod, inspect.isfunction):
        globals()[f"{name}_{suffix}"] = obj
        __all__.append(f"{name}_{suffix}")

_import_with_suffix("core_1d", "1d")
_import_with_suffix("core_3d", "3d")

Future support

So if you want to support the library with new functions, dimensions or method, you have a brief idea of how it works. If you would like to contribute your idea, please feel free to submit a push request on our GitHub, which will be reviewed directly by the development team.

Github source code: https://github.com/yoshlsec/decochators

Also there will be some examples of how we call to the functions. One important thing, when you see <function>.__wrapper__ means that you pass the source function without modifications to the namespace function, in each definition it is detailed typed with the Callable function from typing module, such as:

def lyapunov(step_func: Callable[[np.ndarray], np.ndarray], xyz0: np.ndarray, eps: float = 1e-8, idx: int = 10000, discard: int = 100) -> float:

It is called as:

<function>.mth.lyapunov(<function>.__wrapped__, 0.1, r=3.9)

Pypi guide version will be with an error and shows that the lyapunov function is called as: <function>.mth.lyapunov(0.1, r=3.9), in future releases will be fixed.

Supported Python Versions

Python 3.11+

Supported Chaos Systems

One-dimensional
Three-dimensional
- Continuous dynamic systems
- Discrete over time

Installing

Install or upgrade the Python bindings with pip <https://pip.pypa.io/>.

Latest official release:

pip install -U decochators

Specific version (not recommended for versions lower than 1.1.0):

pip install -U decochators==N.N.NxN

Latest official release from TestPypi:

pip install -i https://test.pypi.org/simple/ decochators

Specific version from TestPypi:

pip install -i https://test.pypi.org/simple/ decochators==N.N.NxN

Where $N \in \mathbb{Z}$ and $x \in {a, b, c, \dots, z}$, example: 1.0.4a0.

Note: you should consider using a virtual environment to create an isolated Python environment for installation.

Testing Binary Chaos Test 0-1

Important for versions lower than decochators1.1.0, mth.test01 is a binarized modified test, be careful comparing or testing complex systems.

from decochators import attach_chaos_tests
import numpy as np

@attach_chaos_tests("1d")
def logistic_step(x: float, r: float = 4.0) -> float:
    return r * x * (1 - x)

serie = logistic_step(0.1, r=3.9, N=1000, burn_in=100, seed=42)
k01 = logistic_step.mth.test01(logistic_step.__wrapped__,x0=0.1, r=3.9)

print("Results with burn-in & seed:")
print(f"Test 0-1 with the serie binarized: {k01}")

k01_vwr=logistic_step.vwr.test01(
    logistic_step.__wrapped__,
    x0=0.1,
    N=1000,
    burn_in=100,
    r=3.9
),

print(f"Complete Test 0-1: {k01_vwr}")

Calling 1 Dimensions functions

With the same chaotic system than before:

def logistic_step(x: float, r: float = 4.0) -> float:
    return r * x * (1 - x)

Generating series

logistic_step(0.1, r=3.9, N=1000, burn_in=100, seed=42)

Lyapunov Exponent Analysis

logistic_step.mth.lyapunov(logistic_step.__wrapped__, 0.1, r=3.9)

Kolmorogov-Sinai Analysis

logistic_step.mth.ks(0.1, r=3.9)

Binary Test Analysis

logistic_step.mth.test01(logistic_step.__wrapped__, x0=0.1, r=3.9)

Binarized Test 0-1 Analysis

logistic_step.mth.btest01(0.1, r=3.9

Chaotic Draw Visualization

logistic_step.vwr.draw(logistic_step.__wrapped__, x0=0.3, N=250000, burn_in=100, r=4.0)

Bifurcation System Visualization

import numpy as np

param_range = np.linspace(2.5, 4.0, 300)
logistic_step.vwr.bifurcation(logistic_step.__wrapped__, x0=0.1, param_name="r", param_range=param_range, N=5000, burn_in=200, last_points=50)

Binary Test Visualization

logistic_step.vwr.test01(logistic_step.__wrapped__, x0=0.1, N=5000, burn_in=100, r=3.9)

Calling 3 Dimensions functions

Chaotic System sample:

def rossler_step(xyz: np.ndarray, a: float = 0.2, b: float = 0.2, c: float = 5.7) -> np.ndarray:
    x, y, z = xyz
    dt = 0.01
    dx = -y - z
    dy = x + a*y
    dz = b + z*(x - c)
    return np.array([x + dx*dt, y + dy*dt, z + dz*dt])

Lyapunov Exponent Analysis

rossler_step.mth.lyapunov([0.1,0,0])

Kolmorogov-Sinai Analysis

rossler_step.mth.ks([0.1,0,0])

Binary Test Analysis

As in 1 Dimension, 3D mth.test01 is in base of a binarized test in lower than decochatorsv1.1.0, be careful.

rossler_step.mth.test01(rossler_step.__wrapped__, xyz0=[0.1,0,0], N=5000, burn_in=100)

Binarized Test 0-1 Analysis

rossler_step.mth.btest01(xyz0=[0.1,0,0], N=5000, burn_in=100)

Chaotic Draw Visualization

rossler_step.vwr.draw(rossler_step.__wrapped__, [0.1, 0.0, 0.0], N=10000, burn_in=500, a=0.2, b=0.2, c=5.7)

Bifurcation System Visualization

import numpy as np

rossler_step.vwr.bifurcation(
    step_func=rossler_step,
    xyz0=[0.1,0.0,0.0],
    param_name='c',
    param_range=np.linspace(4, 6, 200),
    coord=2,      # Project on Cord Z | 0=X;1=Y;2=Z
    N=2000,
    burn_in=500
)

Binary Tests Visualization

rossler_step.vwr.test01(rossler_step.__wrapped__, xyz0=[0.1,0,0], N=5000, burn_in=100)

Source code: https://github.com/yoshlsec/decochators PyPi Package Link: https://pypi.org/project/decochators/ TestPyPi Package Link: https://test.pypi.org/project/decochators/

Pt 2.1 - Creation your own Chaos System