structure-factor computes connected structure factors from particle coordinates in a periodic two-dimensional box. It is available as both a Python library and a command-line program.

Version 1.0.0 provides five estimators:

• particle: the microscopic Fourier sum over particle positions;
• occupancy: an FFT of particle counts on a regular grid;
• density: the equivalent FFT of the number-density field;
• binary: an FFT of a thresholded dilute/dense phase field;
• kernel: an FFT after Gaussian, square top-hat, or disk smoothing.

The particle, occupancy, density, and kernel methods use particle normalization. The binary method is an order-parameter spectrum with a different normalization and should not be compared to them by amplitude alone.

Every number and figure in the animation comes from running the command it shows on the bundled xy.dat snapshot; regenerate it with python3 scripts/create_readme_gif.py.

Install

Python 3.10 or newer is required.

python3 -m pip install .

For development:

python3 -m pip install -e ".[dev]"

Quick start

Input files are whitespace-delimited x y tables. Coordinates must lie in 0 <= x < Lx and 0 <= y < Ly.

From the command line:

structure-factor positions.dat 128 128 \
  --method occupancy \
  --grid-size 1.0 \
  --output-data results/occupancy.npz \
  --output-dir results/figures \
  --no-show

From Python:

from structure_factor import (
    StructureFactorConfig,
    compute_structure_factor,
    load_positions,
)

positions = load_positions("positions.dat")
config = StructureFactorConfig(
    box_size=(128.0, 128.0),
    method="particle",
    max_mode=8,
)
result = compute_structure_factor(positions, config)

print(result.spectrum.shape)
print(result.radial_wave_numbers)
print(result.radial_spectrum)

Every result contains the two-dimensional spectrum and its aligned kx and ky angular-wave-number axes. Unless disabled, it also contains a radial average and the number of Fourier modes in each radial bin.

Documentation

• Documentation overview
• Complete command-line interface
• Complete Python interface
• Scientific methods and conventions
• Runnable examples and the bundled xy.dat snapshot

The detailed guides define every option, configuration field, returned array, normalization, plotting output, and numerical caveat.

Examples

The examples/ directory includes:

• a small in-memory calculation using every estimator;
• CLI commands for every estimator;
• particle, grid, and plotting workflows for the bundled 1,048,576-particle xy.dat snapshot;
• a notebook comparing every way to compute $S$ from that snapshot.

For example, generate a polished binary phase map and spectra with:

MPLBACKEND=Agg PYTHONPATH=src \
  python3 examples/xy_plotting.py --grid-size 10

Scope

Version 1.0.0 supports periodic, orthorhombic, two-dimensional boxes. Every estimator returns a connected spectrum, so the zero mode is exactly zero. Grid methods use nearest-grid-point assignment; this release does not apply an assignment-window correction or kernel deconvolution.

Test

PYTHONPATH=src python3 -m unittest discover -s tests -v

With the development dependencies installed:

pytest
ruff check .
ruff format --check .

This project is distributed under the GNU GPL version 3.