ENH: add average structure

[flokno]

Add average_structure to get time-averaged reference structures

Closes #97

What it does

average_structure computes the symmetry-respecting average structure from an MD simulation with fixed cell (NVT):

1. The internal degrees of freedom allowed by the space group of infile.ucposcar are determined, with the net translation removed (zero-sum constraint).
2. For every timestep, the supercell displacements from the reference positions are projected onto these degrees of freedom.
3. The projections are averaged, and the averaged unit cell and supercell are written to outfile.ucposcar and outfile.ssposcar. Symmetry-breaking displacements are projected out, so the result keeps the space group of the reference.

Input: infile.ucposcar, infile.ssposcar, the MD files (infile.meta, infile.stat, infile.positions, infile.forces) and, optionally, infile.refposcar, the reference positions (defaults to infile.ucposcar).

Changes on top of the tdep-devel version

• Build: use the global optimization flags instead of hardcoded debug flags, link libolle.a like the other codes, fix Makefile dependencies and clean
• infile.refposcar is optional and checked against infile.ucposcar (number of atoms, species and order)
• --stride must be a positive integer, help text no longer copied from eosfit
• No internal degrees of freedom: write the unchanged structure and exit 0 instead of stopping with an error
• Remove the unused npt option; warn that infile.lattice is ignored
• Documentation: manual.md, docs/program/average_structure.md, README and mkdocs entries

Test

tests/average_structure checks a two-atom tetragonal (P4mm) crystal with a two-frame trajectory, where the expected average can be computed by hand: the internal coordinate is averaged, a sideways displacement that breaks the symmetry is projected out, and the centroid is kept fixed.

Known limitations / follow-ups

• Only fixed-cell (NVT) simulations; the lattice is not averaged
• coeffM is rebuilt and solved for every frame, which is slow for long trajectories
• Dead code from tdep-devel is kept for now (e.g. avg_structure, remove_rotations)

🤖 Generated with Claude Code