heterojunction

heterojunction is a Python 3 engineering alpha for enumerating and building explicit 2D heterostructure supercell candidates. It replaces the previous Python 2, first-match workflow with a ranked candidate list, an explicit strain-allocation choice, geometric failure checks, and versioned JSON manifests.

Supported workflow

python -m pip install -e .

# Keep several candidates rather than silently selecting the first match.
heterojunction-mvp search film.POSCAR substrate.POSCAR candidates.json \
  --max-area-multiple 8 --max-length-strain 0.03 \
  --max-angle-difference 1.0 --max-total-atoms 20000 \
  --max-pair-evaluations 250000 --max-cross-layer-pairs 4000000 \
  --limit 50

# Build one explicitly selected candidate.
heterojunction-mvp build film.POSCAR substrate.POSCAR \
  candidates.json 0 output/POSCAR \
  --strain-allocation split --gap 3.2 --vacuum 20 \
  --max-cross-layer-pairs 4000000

Search enumerates positive-orientation two-dimensional Hermite-normal-form supercells, compares their in-plane lengths and angle, and ranks all candidates passing the requested limits. Build requires a candidate index and an explicit policy:

• substrate: strain the film to the substrate supercell;
• film: strain the substrate to the film supercell;
• split: use the arithmetic mean of the two canonical in-plane cells.

Search and build both enforce max_total_atoms and max_cross_layer_pairs (default 4,000,000). A candidate exceeding either ceiling is skipped during search and rejected again before supercell or distance-vector allocation. Cross-layer minimum distances are evaluated in blocks of at most 65,536 pairs. Search also precomputes reduced-cell metrics, rejects more than max_pair_evaluations matrix pairs before evaluation, and retains only the bounded top-k candidate set. Raising these ceilings increases memory and runtime risk.

The candidate file records the complete search configuration and a content-integrity digest. Candidate JSON is staged and fsynced before an atomic same-directory publish. Build replays the complete search and compares every candidate and its order before construction. Its POSCAR and manifest are staged, fsynced, verified, and published as a rollback-capable pair. The manifest records both integer matrices, source digests, mismatch metrics, applied principal strains, gap, vacuum, atom and cross-layer-pair counts, minimum cross-layer distance, and output digest. Output and sidecar paths that directly, symbolically, or by hard link alias an input are always rejected; --force only permits replacement of unrelated outputs.

Scientific boundary

This is a deterministic structure-construction MVP, not an interface-stability predictor.

• Inputs must be 2D POSCAR files whose first two lattice vectors define the plane and whose third vector is parallel to its normal.
• Candidate search currently compares canonical cells without twist-angle enumeration, crystallographic termination generation, reconstruction, or elastic-energy ranking.
• Integer-basis and point-group-equivalent supercells may remain as separate candidates; the alpha does not claim symmetry-unique interface registries.
• Selective-dynamics constraints are rejected before construction rather than silently remapped; search metrics do not depend on constraints, and constraint-aware supercell construction remains future work.
• The selected gap is a layer-envelope separation, not a relaxed equilibrium spacing.
• split strain is a transparent geometric convention, not an elasticity-weighted physical model.
• Collision screening is necessary but not sufficient for chemical validity.
• Candidate integrity hashes detect accidental or unreviewed edits but are not signatures and do not authenticate a malicious author.
• Every retained candidate still requires relaxation, convergence testing, and independent scientific review.

The old Python 2 heterostructure generator and POSCAR concatenator are in the legacy directory. Unrelated analysis notes and a third-party example without a compatible license are excluded from the release branch. Legacy files are not imported or executed by the package.

Validation

python -m unittest discover -s tests -v
python -m build

Tests cover scaled Cartesian POSCAR input, multiple-candidate retention, deterministic ranking, no-match failure, explicit strain allocation, supercell atom counts, collision rejection, output round trips, overwrite protection, and CLI status codes.

Ecosystem and integration

Pymatgen implements the broader Zur--McGill interface-matching family and coherent interface construction. Twister targets commensurate moire cells and relaxation. ASE provides the maintained POSCAR I/O and supercell machinery used by this MVP. Atomate2 is an appropriate downstream workflow layer for calculation provenance and error handling. See ECOSYSTEM.md and STRUCTURE_CONTRACT.md.

The package is available under the BSD 3-Clause License. Public release remains BLOCKED pending the ownership and disclosure review described in RELEASE_GATES.md.