PolarGen

Learning Polar-Nonpolar Phase Competition for LLM-Planned Ferroelectric Crystal Generation

PolarGen is an LLM-planned, parent-conditioned crystal-generation framework. For a known nonpolar (NP) parent, a language branch and a periodic graph branch jointly rank 18 role- and motif-aware structural operations. The fused selector retains the three highest-priority operations, while operation magnitude, signed direction, and conformal uncertainty remain graph-derived. Operations with validated continuous geometric realizations then guide diffusion over NP-relative coordinate and lattice residuals.

This repository follows the terminology and interfaces used in the manuscript. Historical engineering version names, server launchers, private paths, model caches, and non-redistributable assets are intentionally excluded.

Method

The language model acts at the structural-operation selection level. Language hidden states are not passed to the crystal denoiser.

Included code

• polargen.gnn_model and polargen.gnn_infer: the angle-aware periodic graph branch with ranking, quantile, and direction heads.
• polargen.llm_hidden, polargen.llm_heads, and polargen.llm_merge: the crystallography-adapted language prior and sequential adapter workflow.
• polargen.fusion: frozen language-graph score fusion that changes operation order without changing graph-derived numerical outputs.
• polargen.public_api: the stable Top-3 operation-plan interface.
• polargen.public_diffusion: an independently written, compact reference implementation of parent-relative coordinate and lattice residual diffusion.
• polargen.public_guidance: generic late-stage gradient normalization and bounding for caller-supplied differentiable terms.
• Versioned public schemas, synthetic examples, and focused tests.

The reference diffusion modules explain the paper-level algorithm and are executable, but they are not copies of the production diffusion workspace. The trained denoiser, exact schedule and losses, symmetry projectors, pair-alignment pipeline, and operation-specific energy library are not distributed here. See docs/public_diffusion.md.

Installation

Python 3.10 or newer is recommended.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[language,test]"

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[language,test]"

Quick reference example

Run the public residual-diffusion interface with a synthetic parent and a toy zero-noise predictor:

python examples/reference_diffusion_demo.py

The output demonstrates the public interface only and is not a physical prediction.

Run focused tests:

pytest -q

Final diffusion screening evaluation

The frozen DPA-screened evaluation covers 1,250 attempted generations:

Metric	Result
Successful surrogate evaluations	1,249 / 1,250
Stable candidates	445 (35.60%)
Unique stable candidates	443
Uniqueness conditional on stability	99.55%
Train-relative SUN	431 (34.48%)
MP20-catalog SUN	129 (10.32%)

These are calibrated DPA-3.1-3M screening results at a 0.1 eV/atom stability threshold. They are not final DFT-relaxed stability results, and external-database novelty was not evaluated. See docs/evaluation.md for the partition-level results and metric definitions.

Model assets

The 32B base language model is not redistributed. Use the official Qwen/Qwen3-32B weights and apply the crystallography adapter before the operation-ranking adapter. LoRA adapters, graph checkpoints, language-prior heads, and production residual-diffusion checkpoints are not included in this public source repository.

The public source tree contains no real training rows, private training structures, or generated candidate ledger. Any future example subset derived from the training corpora will be capped at 10% of the corresponding full corpus. Validation and test records will not be included in that quota.

Frozen operation-ranking result

On the 323-row frozen validation set described in the manuscript:

Route	Top-1	Top-3 hit
Primary graph route	46.44%	-
Joint language-graph ranking	50.46%	79.26%

The fusion changes ranking only. Magnitude, direction, and conformal intervals remain those of the primary graph branch.

Public diffusion boundary

• The public reference state contains parent-relative coordinate and lattice residuals.
• Its coordinate example removes global translation.
• It exposes a caller-supplied denoiser protocol and generic bounded guidance.
• It does not reproduce the production equivariant denoiser, symmetry projection, operation-energy mapping, exact hyperparameters, or training and sampling pipeline.

Citation

The manuscript citation will be updated with the journal identifier and DOI after publication. See CITATION.cff.

License and attribution

PolarGen source code is released under the MIT License. The compact public diffusion reference was independently written for this repository. DiffCSP and SGEquiDiff remain important scientific precedents and are cited in THIRD_PARTY_NOTICES.md.