scaleinvariance 0.7.1

Simulation and analysis of multifractal fields

scaleinvariance

Simulation and analysis tools for scale-invariant processes and multifractal fields.

Documentation

Current Features

Analysis

Hurst exponent estimation

• Haar fluctuation method: haar_fluctuation_hurst()
• Structure function method: structure_function_hurst()
• Spectral method: spectral_hurst()

All methods support multi-dimensional arrays, averaging over dimensions that are orthogonal to the specified dimension along which spectra are calculated (specified by axis. Data and fit line for plotting may be returned with return_fit=True.

Simulation

• 1D fractionally integrated flux (FIF): FIF_1D() - Multifractal cascade simulation; causal/acausal
• N-D fractionally integrated flux (FIF): FIF_ND() - Isotropic N-D multifractals for arbitrary dimensions (Example shown above)
• 1D fractional Brownian motion: fBm_1D_circulant() - Fast spectral synthesis
• N-D fractional Brownian motion: fBm_ND_circulant() - Isotropic N-D (2D, 3D, 4D, etc.) fBm fields
• 1D fBm (fractional integration): fBm_1D() - Extended Hurst range (-0.5, 1.5) with causal/acausal kernels

View example simulation outputs here

Agent Skill (Highly Recommended for Agents)

An agent skill is included in this repository. For Claude Code:

mkdir -p ~/.claude/skills/scaleinvariance
cp .claude/skills/scaleinvariance/SKILL.md ~/.claude/skills/scaleinvariance/

Codex:

mkdir -p ~/.codex/skills/scaleinvariance
cp .claude/skills/scaleinvariance/SKILL.md ~/.codex/skills/scaleinvariance/

Installation

pip install scaleinvariance

Performance

By default, scaleinvariance uses NumPy for all computations. However, if PyTorch is installed, the package automatically detects it and uses PyTorch for simulation functions, providing potentially huge performance gains (depending on your machine):

# NumPy-only installation (minimal dependencies)
pip install scaleinvariance

# With PyTorch for faster simulations
pip install scaleinvariance[torch]

Control backend explicitly:

import scaleinvariance

# Check current backend
print(scaleinvariance.get_backend())  # 'torch' if available, else 'numpy'

# Force specific backend
scaleinvariance.set_backend('numpy')  # Always use NumPy
scaleinvariance.set_backend('torch')  # Use torch (raises error if not installed)

# Configure threading (defaults to 90% CPU count)
scaleinvariance.set_num_threads(8)

Basic Usage

from scaleinvariance import fBm_1D_circulant, fBm_ND_circulant, FIF_1D, haar_fluctuation_hurst

# Generate 1D fractional Brownian motion
fBm_1d = fBm_1D_circulant(1024, H=0.7)

# Generate 2D fractional Brownian motion
fBm_2d = fBm_ND_circulant((512, 512), H=0.7)

# Generate 3D fractional Brownian motion
fBm_3d = fBm_ND_circulant((256, 256, 128), H=0.7)

# Generate multifractal FIF timeseries
fif = FIF_1D(2**16, alpha=1.8, C1=0.1, H=0.3)

# Estimate Hurst exponent
H_est, H_err = haar_fluctuation_hurst(fBm_1d)
print(f"Estimated H = {H_est:.3f} ± {H_err:.3f}")

Testing

# Test 1D fBm generation and Hurst estimation
python tests/visual/test_acausal_fBm_hurst_estimation.py 0.7

# Test 2D fBm with isotropy validation
python tests/visual/test_2d_fbm.py 0.7

FIF validation scripts, which test scaling over multiple ranges of scale, live in tests/automated/ (see test_1D_FIF_hurst.py and test_2D_FIF_hurst.py). They are designed to be run as standalone Python programs, not via pytest, and they generate many large FIF realizations to reach statistical convergence. These scripts are also known to produce some failures, especially near grid scales, because finite-size effects are not fully mitigated by the LS2010 corrections.

Examples

See the examples/ directory for comprehensive demonstrations:

• fif_comparison_demo.py: Compare Hurst estimation methods on multifractal FIF simulations with different intermittency parameters
• multi_dataset_haar_analysis.py: Real-world data analysis using Haar fluctuation method

Run examples:

python examples/fif_comparison_demo.py

Data source for LGMR: https://www.ncei.noaa.gov/access/paleo-search/study/33112

Requirements

• Python ≥ 3.8
• NumPy, SciPy
• PyTorch (optional, for simulation speedup)