dds

dds is a production-oriented Python library for discrete dynamical systems. It provides a small, typed API for orbit iteration, recurrence and attractor detection, fixed-point search, linear stability, Lyapunov analysis, bifurcation sweeps, basin classification, escape-time grids, and box-counting fractal dimension. Plotting is optional.

Project naming

The import package is dds:

from dds import DDS, orbit, periodic_orbit

The initial PyPI distribution target is dds-lib, because the dds distribution name is already occupied on PyPI.

Installation

Core package:

pip install dds-lib

With SciPy-based fixed-point solvers:

pip install "dds-lib[scipy]"

With plotting helpers:

pip install "dds-lib[plot]"

With parallel batch/grid sweeps:

pip install "dds-lib[parallel]"

Development environment:

pip install -e ".[dev,plot,scipy,parallel]"

Quickstart

from dds import DDS


def logistic_map(x: float, r: float = 3.2) -> float:
    return r * x * (1.0 - x)


def logistic_derivative(x: float, r: float = 3.2) -> float:
    return r * (1.0 - 2.0 * x)


system = DDS(logistic_map, derivative=logistic_derivative, name="logistic")

trajectory = system.orbit(0.2, iterations=10, r=3.2)
periodic = system.periodic_orbit(0.2, max_iterations=200, r=3.2, transient=50)
fixed_points = system.search_fixed_points([0.2, 0.8], 2.0, method="iteration")
lyapunov = system.lyapunov_exponent(0.123, 4.0, iterations=2000, transient=100)
bifurcation = system.bifurcation_data(
    [2.5, 3.2, 3.8, 4.0],
    0.2,
    transient=500,
    samples=100,
)

Command-line interface

Installing dds-lib also installs a dds console script for quick, scriptable use of the built-in example maps (logistic, henon, quadratic, collatz_extension) without writing Python:

dds orbit --map logistic --x0 0.2 --iterations 50 --param r=3.9 --output orbit.csv
dds bifurcation --map logistic --x0 0.2 --param-range 2.5 4.0 500 --output bifurcation.npy
dds escape-grid --map quadratic --xrange -2.0 1.0 400 --yrange -1.5 1.5 400 --stop-iterations 50 --output mandelbrot.npy

Add --plot PATH.png to any subcommand to also save a Matplotlib figure (requires the plot extra). python -m dds works the same way as dds.

Notebooks

Runnable Jupyter notebooks covering each feature area (orbits, fixed points and stability, Lyapunov exponents, bifurcation diagrams, basins of attraction, Mandelbrot/Julia sets, and the Collatz function and its smooth extension) live in notebooks/.

Included features

• Deterministic orbit generation for scalar and complex maps
• Exact and tolerance-aware recurrence detection with explicit statuses
• Scalar multipliers and multidimensional monodromy stability analysis
• Scalar Lyapunov exponents and multidimensional spectra
• Parameter sweeps and bifurcation data
• Attractor discovery and two-dimensional basin classification
• Fixed-point search by iteration, Newton, secant, and bisection
• Escape-time grid computation for Mandelbrot- and Julia-style analysis
• Optional plotting helpers that return Matplotlib figures
• Regression tests for known issues in the original project

Documentation

Project docs live in docs/ and are organized around:

• installation and quickstart
• API reference
• worked examples