chainorder

Chain decomposition and order parameters for ReO3-type anion ordering.

What this is

chainorder is a small NumPy + ASE library for analysing anion ordering of ReO3-type solid solutions (NbO2F, TiOF2, and any other cubic MX3-topology system). It takes an on-lattice ASE Atoms object in an orthorhombic supercell, decomposes the three edge-midpoint anion sublattices into per-direction chains, and exposes a small set of order parameters computed either over the full 3D occupation (coherent structure factor, <111> circulation) or along individual chain directions (Fourier spectra, pair correlation, motif frequencies, inter-chain correlation).

Installation

Requires Python 3.11+, NumPy, and ASE.

pip install chainorder

To install the latest development version directly from GitHub:

pip install git+https://github.com/bjmorgan/chainorder.git

For development, clone and install in editable mode with the test and type-checking extras:

git clone git@github.com:bjmorgan/chainorder.git
cd chainorder
pip install -e ".[dev]"

Quickstart

from ase.io import read
from chainorder import SublatticeOccupation, order_params

atoms = read("frame.xyz")                                   # any ASE-readable format
occ = SublatticeOccupation.from_atoms(atoms, N=6, species="F")  # supercell size (cubic shorthand)

sf = order_params.structure_factor(occ)                      # 3D structure factor
circ = order_params.circulation_invariants(occ, period=3)    # <111> chirality + coherence
spectrum = order_params.chain_fft(occ.x)                     # per x-chain FFT
g_r = order_params.along_chain_correlation(occ.x)            # g(r) along x-chains
freqs = order_params.motif_frequencies(occ.x, window_length=3)   # length-3 motif frequencies
G = order_params.inter_chain_correlation(occ.x, period=3)   # period-p phase correlation

A full trajectory is just a loop: per frame, build a SublatticeOccupation and call whichever order parameter(s) you need.

Public API at a glance

chainorder:

• SublatticeOccupation -- frozen dataclass holding the decomposed anion occupation. Construct it from an ASE Atoms with SublatticeOccupation.from_atoms(atoms, N=...). The primary field .occupation is a read-only (3, Nx, Ny, Nz) integer array; .x, .y, .z are chain-layout transpose views suited to the single-direction tools below.
• order_params -- submodule of order parameters:
  • structure_factor(occ) -- coherent 3D structure factor of the full anion sublattice.
  • circulation_invariants(occ, period=p) -- chirality and coherence of the <111> screw ordering, projected onto the cubic point group.
  • chain_fft(arr) -- discrete Fourier transform along each chain.
  • along_chain_correlation(arr) -- pair correlation g(r) along chains, grand-averaged over the chain-plane.
  • motif_frequencies(arr, window_length=N) -- per-chain frequency of each distinct length-window_length motif (bit pattern).
  • inter_chain_correlation(arr, period=p) -- spatial autocorrelation of the period-p Fourier component across the chain plane.

structure_factor and circulation_invariants take the whole SublatticeOccupation; the other four take a single chain-layout array (occ.x, occ.y, or occ.z).

Each function's docstring covers shape conventions, normalisation, and edge cases in detail.

Related material

• docs/concepts.md -- problem framing, data model, and what each order parameter measures, with concrete example cases.
• docs/tutorial.ipynb -- end-to-end worked example applying all five order parameters to four reference structures, with plots.