Skip to main content

scaleinvariance

FIF 2D Example

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

Documentation

View example FIF simulation output in the Multifractal Explorer

Current Features

Analysis

Hurst exponent estimation

  • Haar fluctuation method: haar_fluctuation_hurst()
  • Wavelet fluctuation method: wavelet_fluctuation_hurst() - general wavelet path; choose wavelet= ('haar', 'structure_function', 'mexican_hat', 'morlet'). The Mexican hat and Morlet have more vanishing moments and reach higher H than Haar.
  • 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.

structure_function_hurst(), haar_fluctuation_hurst(), and wavelet_fluctuation_hurst() accept periodic=True for data on a periodic (toroidal) domain — e.g. the output of the periodic=True simulators. (spectral_hurst() is FFT-based and already periodic.)

Structure functions

  • Structure function: structure_function() - Order-q structure function (q may be scalar or array-valued)
  • Co-structure function: costructure_function() - Mixed-moment structure function for two fields
  • Wavelet fluctuation: wavelet_fluctuation() - Order-q fluctuation for a chosen wavelet= ('haar', 'structure_function', 'mexican_hat', 'morlet'). Kernels are L1-normalized so F_q(r) ~ r^{qH-K(q)}; the complex Morlet returns the modulus. 'haar' reproduces haar_fluctuation() and 'structure_function' reproduces structure_function() exactly.

structure_function(), costructure_function(), haar_fluctuation(), and wavelet_fluctuation() (and the intermittency estimators K_empirical() / two_point_C1()) accept periodic=True to treat the domain as periodic along axis: increments and Haar windows wrap around the array end (every lag uses all L samples) rather than dropping the edge pairs. For the structure function S(r) = S(L - r), so lags are capped at L // 2; the Haar fluctuation has no such symmetry and keeps the full lag range.

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, with optional per-axis causality (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
  • Generalized Scale Invariance (GSI): FIF_ND() accepts a custom scale_metric together with the GSI elliptical dimension elliptical_dim (D_el) for anisotropic / stratified multifractals. canonical_scale_metric() builds the canonical stratified metric (last axis anisotropic with stratification exponent Hz).

For FIF simulation methods (FIF_1D, FIF_ND), the currently supported range is 0.5 <= alpha <= 2 with alpha != 1. The kernel construction method 'LS2010' (Lovejoy & Schertzer 2010) is used for flux kernels. For observable kernels, both 'LS2010' and 'spectral' are supported. GSI with a custom scale_metric requires kernel_construction_method_observable='LS2010'.

Installation

pip install scaleinvariance

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

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

Codex:

mkdir -p ~/.codex/skills/scaleinvariance
cp agent-skills/scaleinvariance/SKILL.md ~/.codex/skills/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, FIF_ND,
    canonical_scale_metric, 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)

# Override FIF kernels explicitly if needed
fif_custom = FIF_1D(
    2**16,
    alpha=1.8,
    C1=0.1,
    H=0.3,
    causal=False,
    kernel_construction_method_flux='LS2010',
    kernel_construction_method_observable='spectral',
)

# Anisotropic 2D GSI multifractal (canonical stratified metric)
size = (256, 256)
sim_size = (512, 512)        # non-periodic -> doubled domain for the metric
Hz = 0.556                    # canonical atmospheric stratification
metric = canonical_scale_metric(sim_size, ls=100.0, Hz=Hz)
fif_gsi = FIF_ND(
    size, alpha=1.8, C1=0.1, H=0.3, periodic=False,
    scale_metric=metric, elliptical_dim=1 + Hz,
    kernel_construction_method_observable='LS2010',
)

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

Kernel Selection

For FIF simulations:

  • kernel_construction_method_flux controls the cascade kernel.
  • kernel_construction_method_observable controls the final observable kernel.
  • Flux kernels support 'LS2010' (and deprecated 'naive' for 1D only).
  • Observable kernels support 'spectral' (default) and 'LS2010'. FIF_1D also supports 'spectral_odd' and deprecated 'naive'.
  • The old kernel_construction_method= argument is no longer accepted by FIF_1D or FIF_ND.
  • naive FIF kernels remain available only for comparison and debugging and emit a warning because they are not remotely accurate.

For fBm:

  • fBm_ND_circulant() is recommended. It uses a spectral synthesis method and produces essentially perfectly scale invariant fields.
  • fBm_1D() is included for comparsion or for causal simulations.

Generalized Scale Invariance (GSI)

FIF_ND() supports anisotropic / stratified multifractals via two parameters:

  • scale_metric: an N-D array of generalized distances on the simulation grid. Must match the simulation domain shape after accounting for periodicity (domain is doubled along non-periodic axes). Values must be finite and strictly positive everywhere.
  • elliptical_dim: the GSI elliptical dimension D_el. For canonical stratified anisotropy with exponent Hz, D_el = d - 1 + Hz in d dimensions (i.e. 1 + Hz in 2D, 2 + Hz in 3D, …). Defaults to the spatial dimension (isotropic).

The helper canonical_scale_metric(size, ls, Hz) builds the standard stratified metric — the last axis is anisotropic with exponent Hz, all other axes are isotropic — on the dx=2 grid expected by the LS2010 kernel construction.

GSI with a custom scale_metric currently requires kernel_construction_method_observable='LS2010'; it is not supported on the default 'spectral' observable path, and is therefore incompatible with observable_kernel_odd_axes.

Note: the older keyword scale_metric_dim has been renamed to elliptical_dim. The old name still works but emits a DeprecationWarning and will be removed in a future release.

Examples

Work in progress. See Multifractal Explorer for visuals.

Run examples:

python examples/fif_comparison_demo.py

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

Testing

Tests are organised into three directories under tests/:

Directory Purpose How to run
tests/functional/ Sanity checks and gross-accuracy tests. Should always pass. pytest
tests/numerical/ Theory-validation scripts run directly as Python programs. Some produce failures due to finite-size/discretization effects. python tests/numerical/<script>.py
tests/visual/ Scripts that generate plots for manual inspection. python tests/visual/<script>.py

FIF validation scripts, which test scaling over multiple ranges of scale, live in tests/numerical/. 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 or their spectral alternatives.

Run the functional suite:

pytest

Run a specific visual test:

python tests/visual/test_1D_fif_structure_function.py 0.3 0.1 1.8

Requirements

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

Metadata

Release files for scaleinvariance 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scaleinvariance 0.14.0
File Size Uploaded Provenance Actions
scaleinvariance-0.14.0.tar.gz 59.6 kB Without provenance Details for scaleinvariance-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for scaleinvariance 0.14.0
File Interpreter ABI Platform Actions
scaleinvariance-0.14.0-py3-none-any.whl Python 3 none any Details for scaleinvariance-0.14.0-py3-none-any.whl

Total release size: 124.7 kB

Release files / scaleinvariance-0.14.0.tar.gz

Download URL scaleinvariance-0.14.0.tar.gz
Size 59.6 kB
Tags Source
SHA-256 checksum
How to use checksums
41c3442e90be3b72a1ed40dcf6352792d9b126ef3f86bb39bbc056ec505dd18f
BLAKE2b-256 checksum
How to use checksums
6073507e757bbc2287f6f5a9ce23197a0008d74a9f71e585f6212b4911fc5e1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.12

Release files / scaleinvariance-0.14.0-py3-none-any.whl

Download URL scaleinvariance-0.14.0-py3-none-any.whl
Size 65.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1b4ea57c9017a401b6897fa3c38d8ddaec9f8cb59e884c9ce36b6940b1d88e1d
BLAKE2b-256 checksum
How to use checksums
152c41cf0c8df761d039586ed91980955dbfcd3c47841b46dc69f2bbeb68d81c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.12

Security for scaleinvariance 0.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page