Metadata-Version: 2.4
Name: chainorder
Version: 0.2.0
Summary: Chain decomposition and order parameters for ReO3-type anion ordering
Author-email: "Benjamin J. Morgan" <b.j.morgan@bath.ac.uk>
License-Expression: MIT
Project-URL: Homepage, https://github.com/bjmorgan/chainorder
Project-URL: Repository, https://github.com/bjmorgan/chainorder
Project-URL: Issues, https://github.com/bjmorgan/chainorder/issues
Keywords: materials-science,crystallography,order-parameters,solid-solution,ase
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: ase
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

[![CI](https://github.com/bjmorgan/chainorder/actions/workflows/ci.yml/badge.svg)](https://github.com/bjmorgan/chainorder/actions/workflows/ci.yml)

# 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.

```bash
pip install chainorder
```

To install the latest development version directly from GitHub:

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

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

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

## Quickstart

```python
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`](docs/concepts.md) -- problem framing, data model,
  and what each order parameter measures, with concrete example cases.
- [`docs/tutorial.ipynb`](docs/tutorial.ipynb) -- end-to-end worked
  example applying all five order parameters to four reference
  structures, with plots.
