Wyckoff-based Text Representation

• Wyckoff-based text representation is a symmetry-aware encoding that maps crystal structures into token sequences based on space groups and occupied Wyckoff positions.
• Different schemes, including WyCryst, WyFormer, Matra-Genoa, and SWORD, offer varied approaches for property prediction, generative modeling, and database deduplication.
• Recent implementations demonstrate enhanced data efficiency, invariance to crystallographic transformations, and advanced generative capabilities for discovering novel compounds.

Wyckoff-based text representation denotes a family of symmetry-aware encodings that map a crystal structure into a discrete sequence, token stream, or canonical string organized around space group symmetry and occupied Wyckoff positions. In this formulation, the primary structural units are not individual Cartesian coordinates but symmetry-inequivalent sites, their multiplicities, and their elemental occupations. Recent implementations use this idea for inverse design, autoregressive generation, property prediction, database deduplication, and disorder-aware novelty assessment. Across WyCryst, Matra-Genoa, WyFormer, and SWORD, the representation may be augmented with atomic features, free coordinate parameters, lattice parameters, or partial occupancies, but its defining feature is explicit crystallographic symmetry encoded at the level of space groups and Wyckoff sites (Zhu et al., 2023, Breuck et al., 27 Jan 2025, Kazeev et al., 4 Mar 2025, Yamazaki et al., 21 Mar 2025, Huang et al., 20 Apr 2026).

1. Crystallographic basis and formal motivation

Wyckoff positions specify symmetry-inequivalent atomic sites within a space group. Each position is associated with a multiplicity and a site symmetry, and may carry $0$ to $3$ degrees of freedom depending on whether it is special or general. This makes the Wyckoff description substantially more compressed than a dense list of atomic coordinates, while retaining the symmetry constraints that govern the admissible structure manifold (Zhu et al., 2023, Kazeev et al., 4 Mar 2025).

A central motivation for Wyckoff-based encodings is that conventional structure representations built from lattices and atomic coordinates are dense and, in the formulation emphasized by WyFormer, are not permutation- nor symmetry-invariant. Wyckoff-based encodings instead elevate the symmetry-equivalent orbit to the primitive unit of representation. In WyFormer this is expressed as

$R = (G, \mathbf{E}, \mathbf{W}),$

where $G$ is the space group, $\mathbf{E}$ is the list of elements occupying the inequivalent sites, and $\mathbf{W}$ is the list of Wyckoff positions represented through site symmetry and an enumeration index (Kazeev et al., 4 Mar 2025).

The treatment of the space group is likewise explicit. WyCryst and the multi-property framework of 2025 encode the space group as a one-hot vector of length $230$, corresponding to the $230$ three-dimensional space groups, and combine it with a Wyckoff array that carries stoichiometry, atomic features, and site occupancy information (Zhu et al., 2023, Yamazaki et al., 21 Mar 2025). Matra-Genoa similarly treats the space group as a discrete token in an invertible sequence representation, while also exploiting a shared inventory of $990$ unique Wyckoff positions across space groups (Breuck et al., 27 Jan 2025).

An important refinement introduced by WyFormer is the replacement of group-specific Wyckoff letters by universal site symmetry labels plus an enumeration index. Because Wyckoff letters are local to a space group, this universalization reduces fragmentation across the corpus and improves transferability. The enumeration index resolves cases in which multiple Wyckoff positions in the same space group share the same site symmetry (Kazeev et al., 4 Mar 2025).

2. Representational schemes and tokenization strategies

Different Wyckoff-based text representations share a common symmetry-centric ontology but differ in whether they aim for full invertibility, permutation invariance, or canonical fingerprinting.

In WyCryst, the representation is written as $(S, X)$, with $3$0 the one-hot space-group vector and

$3$1

where $3$2 is the stoichiometry matrix, the atomic feature matrix follows CGCNN-style elemental descriptors, and $3$3 records Wyckoff site occupancy and multiplicity for each element. This representation is used as the input to a property-directed VAE and is intended to be bi-directional, supporting both encoding from CIF data and decoding into a symmetry-compliant structural specification (Zhu et al., 2023).

WyFormer adopts a more explicitly linguistic layout. The first token is the space group, and each occupied Wyckoff position contributes a triplet of tokens: chemical element, site symmetry, and enumeration. The triplets can be shuffled because the model omits positional encoding, so the sequence functions as a permutation-invariant set of structured tokens rather than a sentence with syntactic order (Kazeev et al., 4 Mar 2025).

Matra-Genoa is closer to a conventional autoregressive LLM over a hybrid symbolic–continuous alphabet. A crystal is mapped to a token sequence

$3$4

whose tokens encode composition, space group, Wyckoff positions, free parameters of those positions, unit-cell parameters $3$5, and conditioning variables such as stability or target property. Because the sequence includes the free Wyckoff coordinates and lattice parameters, it is fully invertible: the full three-dimensional crystal can be reconstructed from the tokens and the crystallographic definitions of the relevant Wyckoff positions (Breuck et al., 27 Jan 2025).

SWORD serves a different role. It is a standardized string representation for ordered and disordered crystals, intended for grouping, duplicate detection, and novelty assessment rather than direct structure generation. Its string concatenates a standardized Wyckoff sequence, the space-group number, and the decorated occupations of each symmetry-inequivalent site, including explicit co-occupancy and vacancy labels. The paper gives, for example, $230$8 for a disordered lithium manganese oxide entry (Huang et al., 20 Apr 2026).

The main schemes can be summarized as follows.

Framework	Core representation	Primary use
WyCryst / MPVAE	$3$6 with $3$7	VAE-based generation and property direction
WyFormer	Space-group token followed by element/site-symmetry/enumeration triplets	Permutation-invariant autoregressive generation and property prediction
Matra-Genoa	Invertible token sequence with Wyckoff IDs, free coordinates, and lattice parameters	Autoregressive generation in a hybrid discrete/continuous action space
SWORD	Standardized Wyckoff string with occupations, disorder, and space group	Deduplication, novelty assessment, and database curation

These variants also clarify a common source of confusion: Wyckoff-based text representation does not necessarily mean that coordinates are discarded. WyFormer demonstrates competitive property prediction even without atomic coordinates, but Matra-Genoa explicitly tokenizes free Wyckoff parameters and lattice parameters, and the multi-property augmentation framework also applies symmetry operations to fractional coordinates for structure-aware models (Kazeev et al., 4 Mar 2025, Breuck et al., 27 Jan 2025, Yamazaki et al., 21 Mar 2025).

3. Invariance, canonicalization, and symmetry-preserving augmentation

A major technical issue in any symbolic crystal representation is invariance under identity-preserving transformations such as origin shifts, different Hall settings, affine normalizers, or permutation of symmetry-equivalent sites. Wyckoff-based text representations address this problem by design, but with different mechanisms.

WyFormer enforces permutation invariance at the model level. The Transformer encoder is used without positional encoding, and the occupied Wyckoff triplets may be shuffled. The space group is always placed first to supply the global symmetry context, while the remaining tokens are treated as an unordered collection of occupied symmetry orbits (Kazeev et al., 4 Mar 2025).

SWORD addresses invariance through explicit canonicalization. Its standardization procedure has two stages: Hall setting normalization to a canonical Hall setting, and enumeration of all symmetry-equivalent transformed Wyckoff positions induced by the affine normalizer. Among the admissible decorated Wyckoff sequences, the canonical form is selected deterministically. The standardized representation is written as

$3$8

where $3$9 is the decorated Wyckoff sequence, $R = (G, \mathbf{E}, \mathbf{W}),$0 is the set of symmetry-allowed relabelings and permutations, and $R = (G, \mathbf{E}, \mathbf{W}),$1 is the ordering function used for comparison (Huang et al., 20 Apr 2026).

The 2025 multi-property framework extends invariance from canonicalization to data augmentation. Because space-group theory guarantees that $R = (G, \mathbf{E}, \mathbf{W}),$2-equivalent representations of a crystal have the same properties, each structure can be expanded into multiple symmetry-equivalent views using Euclidean normalizers derived from the Bilbao Crystallographic Server. The procedure extracts the normalizers for each space group, enumerates all symmetry-equivalent Wyckoff representations, updates the Wyckoff positions accordingly, and, for structure-aware models, applies the corresponding normalizer matrices to the fractional coordinates. Space group $R = (G, \mathbf{E}, \mathbf{W}),$3 is given as an example with $R = (G, \mathbf{E}, \mathbf{W}),$4 normalizers, while in space group $R = (G, \mathbf{E}, \mathbf{W}),$5 augmentation occurs only when the occupied Wyckoff positions are among those that can be interchanged (Yamazaki et al., 21 Mar 2025).

This augmentation is label-preserving: the property labels remain unchanged because the transformed views are symmetry-equivalent descriptions of the same crystal. In the reported experiments it increases data size, improves invariance, and reduces the risk that the model learns artifacts of one particular site labeling rather than crystallographically meaningful structure–property relations (Yamazaki et al., 21 Mar 2025).

4. Learning architectures and generative semantics

Wyckoff-based text representation has been instantiated in several model classes, including VAEs, permutation-invariant autoregressive Transformers, and hybrid discrete/continuous autoregressive Transformers.

WyCryst introduced a property-directed VAE built on the Wyckoff representation. Its encoder maps $R = (G, \mathbf{E}, \mathbf{W}),$6 into a latent space, the decoder reconstructs the space group and Wyckoff array, and auxiliary property branches shape the latent geometry toward target quantities such as formation energy and band gap. The loss combines reconstruction, KL regularization, property regression, and an explicit Wyckoff loss that enforces consistency between reconstructed stoichiometry and symmetry-weighted site occupations (Zhu et al., 2023).

The 2025 multi-property framework generalizes this to a Multi-Property Variational Autoencoder (MPVAE). The encoder consumes the Wyckoff representation, the decoder reconstructs the crystal’s Wyckoff representation, and fully connected property branches predict targeted properties such as $R = (G, \mathbf{E}, \mathbf{W}),$7 and $R = (G, \mathbf{E}, \mathbf{W}),$8. The loss combines reconstruction of Wyckoff and space-group information, property prediction, KL divergence, and symmetry-preserving terms. A key addition is transfer learning: the model is pre-trained on a larger source dataset using a broadly available property such as formation energy, then fine-tuned on a smaller target dataset with multiple property labels. During fine-tuning, the entire encoder is frozen and only the property heads and decoder are updated (Yamazaki et al., 21 Mar 2025).

WyFormer replaces latent-variable generation with a permutation-invariant autoregressive distribution over occupied symmetry sites. All generations are conditioned on a fixed space group, and the model samples element, site symmetry, and enumeration autoregressively. Its space-group embedding is not merely categorical: it is derived from the full set of symmetry elements as a one-hot-encoded $R = (G, \mathbf{E}, \mathbf{W}),$9 matrix, flattened and passed through a linear layer. For property prediction, the model can additionally use spherical-harmonic descriptors of the symmetry operations associated with a Wyckoff position (Kazeev et al., 4 Mar 2025).

Matra-Genoa frames the problem as autoregressive generation in a hybrid action space. Discrete tokens represent elements, space-group numbers, Wyckoff identifiers, stoichiometry, and conditioning variables; continuous tokens represent free coordinates and lattice parameters. Discrete tokens use learnable embeddings, whereas continuous values are encoded through Gaussian functions of linear and logarithmic transforms. Sampling follows a Boltzmann distribution over the transformer logits, enabling conditional generation of crystals targeted for low distance to the convex hull or other specified conditions (Breuck et al., 27 Jan 2025).

A plausible implication of these architectures is that Wyckoff-based text representation is not tied to a single learning paradigm. The same symmetry-aware tokenization can support latent-variable models, canonical fingerprints, and autoregressive sequence models, provided that the semantics of the tokens preserve the orbit structure imposed by the space group.

5. Disorder, database curation, and novelty assessment

The extension of Wyckoff-based text representation from ordered crystals to disordered crystals is most explicit in SWORD. Its representation accommodates substitutional disorder, vacancy disorder, and co-occupancy by decorating each symmetry-inequivalent site with the relevant species and occupancies. If the total occupancy of a site is clearly below $G$0 by a threshold, VAC is included explicitly. Positional disorder is identified through proximity criteria, although it is not explicitly included in the paper’s main Shannon-entropy-based disorder descriptor (Huang et al., 20 Apr 2026).

To quantify the degree of disorder within structures that share the same SWORD label, the paper defines a degree of mixing (DOM) descriptor. For a partially occupied Wyckoff site $G$1 with species $G$2 and occupancies $G$3, the normalized Shannon entropy is

$G$4

where $G$5 is the number of species on that site. The structure-level DOM is then computed as a multiplicity-weighted aggregate over disordered sites, together with a mixing-bias indicator that captures the direction of binary compositional preference (Huang et al., 20 Apr 2026).

This representation enables duplicate identification and large-scale grouping without resorting to pairwise geometry matching. All entries with the same SWORD label form an identical-label group, and for disordered systems the DOM refines the grouping so that entries with the same Wyckoff framework but different site stoichiometries can still be distinguished. Benchmarking reported in the paper shows invariance to rigid translations, isotropic strain, cell setting changes, origin changes, and symmetry operations, while retaining tunable sensitivity to random perturbations through the symmetry tolerance parameter (Huang et al., 20 Apr 2026).

The ICSD case study illustrates the database-scale role of such representations. SWORD partitions more than $G$6 ICSD entries into approximately $G$7 groups and is described as scaling linearly with database size because it functions as a fingerprint rather than a pairwise matcher. The same work also reports competitive performance in associating unrelaxed and intermediate structures with their final relaxed states along relaxation trajectories, which suggests a role for Wyckoff-based strings in novelty assessment before full DFT relaxation (Huang et al., 20 Apr 2026).

6. Empirical performance, scope, and research trajectory

The empirical record across papers indicates that Wyckoff-based text representation is valuable both for generative validity and for data efficiency. WyCryst reports near $G$8 validity of generated structures in its benchmarks under DFT relaxation and minimal-atom-distance checks, and reproduces known compounds including CaTiO$G$9, CsPbI$\mathbf{E}$0, BaTiO$\mathbf{E}$1, and CuInS$\mathbf{E}$2, while also generating stable new ternary materials that retain symmetry and pass phonon checks (Zhu et al., 2023).

In the multi-property setting, the main challenge is sparse functional-property supervision. The 2025 MPVAE study reports that Wyckoff-augmented forward models reduce mean absolute error by $\mathbf{E}$3–$\mathbf{E}$4, with dual augmentation yielding up to $\mathbf{E}$5–$\mathbf{E}$6 further improvement. Under severe labeled-data scarcity, transfer learning with augmentation improves Wyckoff reconstruction accuracy from $\mathbf{E}$7 to $\mathbf{E}$8, reduces formation-energy MAE from $\mathbf{E}$9 to $\mathbf{W}$0 eV/atom, and reduces band-gap MAE from $\mathbf{W}$1 to $\mathbf{W}$2 eV. The same framework identifies eight previously unknown thermodynamically and lattice-dynamically stable semiconductors in tetragonal, trigonal, and cubic systems, with DFT-validated band gaps ranging from $\mathbf{W}$3 to $\mathbf{W}$4 eV, and also evaluates their thermoelectric descriptors with DFT (Yamazaki et al., 21 Mar 2025).

For large-scale generation, Matra-Genoa demonstrates the advantages of an invertible Wyckoff tokenization with free coordinates. The model generates $\mathbf{W}$5 million unique structures, including $\mathbf{W}$6 compounds verified by DFT to be within $\mathbf{W}$7 eV/atom of the convex hull. Reported throughput is $\mathbf{W}$8 structures per minute. Validity reaches up to $\mathbf{W}$9 parsable sequences at lower temperature; $230$0 of generated structures have symmetry, fewer than $230$1 have a mismatched declared space group, post-filtering for colliding atoms removes fewer than $230$2, and duplicates can fall to $230$3 at $230$4. The paper further reports that its generated structures are $230$5 times more likely to be stable than a PyXtal baseline with charge compensation, and gives an approximately $230$6 Stable–Unique–Novel ratio at $230$7 (Breuck et al., 27 Jan 2025).

WyFormer emphasizes a complementary profile: best-in-class symmetry-conditioned generation, competitive stability, competitive property prediction even without atomic coordinates, and unparalleled inference speed. Its results support the claim that symmetry and composition alone often encode a large fraction of the information needed for property prediction, although other works show that explicit free coordinates can still be beneficial when full invertibility or detailed structural recovery is required (Kazeev et al., 4 Mar 2025, Breuck et al., 27 Jan 2025).

Taken together, these results define the present scope of Wyckoff-based text representation. It is a symmetry-native formalism that can be canonical, invertible, disorder-aware, or property-conditioned depending on implementation. Its principal technical contribution is to move crystal representation from dense coordinate fields to tokenizable symmetry orbits, thereby aligning crystallographic structure with modern sequence modeling, transfer learning, and large-scale database curation. A plausible implication is that future progress will continue to come from combining three ingredients already visible in the literature: explicit space-group conditioning, standardized or augmented Wyckoff semantics, and downstream physical validation through relaxation and DFT-based screening (Zhu et al., 2023, Yamazaki et al., 21 Mar 2025, Huang et al., 20 Apr 2026).