[Feature Request] Modernize Input: Support for POSCAR/ASE Structures via Python Bridge

[Liam-Deacon]

Context & Motivation

The current workflow for CLEED relies on legacy input formats (.inp, .bul, .ctr) which define surface structures using a "Layered" philosophy (explicit separation of Bulk and Overlayer).

However, the modern computational materials science community (DFT users, High-Throughput screening) has standardized around the "Supercell" philosophy: a single 3D periodic box containing bulk, surface, and vacuum, typically exchanged via POSCAR (VASP) or CIF files and manipulated via Python libraries like ASE (Atomic Simulation Environment) or pymatgen.

The Problem

There is a structural mismatch between modern tools and CLEED:

1. Modern Tools (VASP/ASE): "Here is a bag of atoms in a box." (3D periodicity, vacuum is just empty space).
2. CLEED: "Here is a semi-infinite Bulk (.bul) and a finite Overlayer (.inp)." (2D periodicity, vacuum is handled analytically).

Currently, a user wanting to simulate a structure from VASP must manually decompose their POSCAR into CLEED's specific format, which is error-prone and hinders automation.

Proposed Solution: The "Python Bridge"

Instead of refactoring the core C/Fortran kernel to parse complex formats, we should implement a Python-based pre-processor (e.g., tools/cleed_converter.py) that acts as a bridge.

Workflow:

1. Input: User provides a standard file (POSCAR, .cif, .xyz).
2. Processing:
   • The script uses ASE to read the geometry.
   • It applies an "Automated Slicing" algorithm to identify the periodic bulk unit from the bottom layers of the slab.
   • It treats the remaining top layers as the Overlayer.
3. Output: The script generates valid .bul and .inp files for CLEED.

This approach immediately grants CLEED compatibility with 30+ file formats supported by ASE and aligns it with tools like ViPErLEED, which natively uses POSCARs.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• feat(phaseshifts): Integrate phaseshifts Python package for phase shift generation #44
• docs(io): Thoroughly document CLEED input formats (.inp/.bul/.ctr) + cleedpy YAML alternative #50
• feat(python): Ship CLEED as a cleed Python package #37
• feat(io): Support cleedpy YAML input format (and schema upstream) #36
• docs(examples): Add Jupyter notebook examples for CLEED workflows #45

👤 Suggested Assignees

• Liam-Deacon

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[Liam-Deacon]

1. The "Modern Standard" Context

To understand the target workflow, we should look at ViPErLEED, a modern LEED code that has successfully adopted these standards.

ViPErLEED's Approach:

• It accepts a POSCAR file directly.
• It enforces a Convention:
  • Vectors $\vec{a}$ and $\vec{b}$ are in the surface plane.
  • The slab is asymmetric: "Bottom" layers are Bulk, "Top" layers are Surface.
  • $\vec{c}$ vector points into the vacuum.

The Structural Mismatch:

Feature	Standard Formats (POSCAR / ASE)	CLEED (.bul + .inp)
Philosophy	"Supercell": Single box. Vacuum is explicit empty space.	"Layered": Explicit separation. Vacuum is implied/analytic.
Periodicity	3D Periodic.	2D Periodic.
Z-Direction	Arbitrary.	Strict (relative to previous layers).
Atom Types	Elements (Ni, O).	Labels (Ni_bulk, O_surf) mapped to phase shifts.

References:

• ViPErLEED Input Format
• ASE Atoms Object Documentation

[Liam-Deacon]

2. Investigation of cleedpy

I have investigated the empa-scientific-it/cleedpy repository (a Python wrapper for CLEED) to see if this is already solved.

Findings:

1. Architecture: cleedpy wraps the compiled C library (libcleed) using ctypes. It is not a pure Python rewrite of the physics core.
2. Input Format: It uses a structured YAML input, which is a major improvement over .inp/.bul, but it still requires the user to explicitly define bulk_layers vs overlayers.
3. ASE Support:
   • Export (YES): It has a get_ase_structure() method in config.py to visualize the setup.
   • Import (NO): It lacks the logic to read a POSCAR and automatically populate the bulk_layers list.

Code Reference (cleedpy/config.py):
The InputParameters class defines the schema but expects pre-separated layers:

class InputParameters(BaseModel):
    """Non geometrical parameters for bulk calculations"""
    system_name: str
    unit_cell: UnitCellParameters
    superstructure_matrix: SuperstructureMatrix
    overlayers: list[AtomParametersVariants]  # <--- User must populate this manually
    bulk_layers: list[AtomParametersVariants] # <--- User must populate this manually

Conclusion: cleedpy has the infrastructure (ASE dependency, Python bindings) but is missing the specific algorithm to slice a 3D slab into 2D LEED layers. Implementing this here (or contributing it there) is the missing link.

[Liam-Deacon]

3. Implementation Plan: The Slicing Algorithm

Here is a prototype for the "Bridge Script" that could be added to tools/. This demonstrates how to translate an ASE object into CLEED concepts.

Proposed Logic:

1. Read Structure: Use ase.io.read('POSCAR').
2. Identify Bulk:
   • Sort atoms by Z-coordinate.
   • Group atoms into "atomic layers" (grouping those with similar Z within a tolerance).
   • Check the bottom $N$ layers. If Layer 1 and Layer 2 are identical (by translation of a lattice vector), define that repeating unit as the Bulk.
3. Identify Overlayer:
   • All layers above the detected bulk region are treated as the Overlayer (.inp).
4. Generate Output:
   • Write lattice vectors to .bul.
   • Write bulk atom relative coords to .bul (pb:).
   • Write overlayer atom relative coords to .inp (po:).

Prototype Snippet:

from ase.io import read
import numpy as np

def poscar_to_cleed(filename="POSCAR"):
    atoms = read(filename)
    
    # 1. Enforce ViPErLEED-style conventions
    # Ensure c-axis is roughly normal to surface
    cell = atoms.get_cell()
    # (Add validation checks here for 2D cell in xy plane)

    # 2. Slice Layers
    # Simple clustering by Z-coordinate
    z_coords = atoms.positions[:, 2]
    tolerance = 0.5 # Angstrom
    # ... clustering logic ...

    # 3. Detect Periodicity
    # Compare bottom layers to find the "Bulk Unit"
    # ... logic to find repetition ...

    # 4. Write .bul and .inp
    # Map Element symbols to Phase Shift files (e.g. Ni -> Ni.phs)
    with open("output.bul", "w") as f:
        f.write(f"a1: {cell[0][0]:.4f} {cell[0][1]:.4f} {cell[0][2]:.4f}\n")
        # ... write bulk atoms ...
    
    with open("output.inp", "w") as f:
        # ... write overlayer atoms ...

[Liam-Deacon]

4. Alternative: Native C Support (Not Recommended)

We considered implementing a native POSCAR or YAML parser directly in the C src/.

Pros:

• Single executable, no Python dependency.

Cons:

• Complexity: Parsing text formats (especially flexible ones like YAML or free-form POSCARs) in C is notoriously brittle and error-prone.
• Maintenance: Any change in the VASP format or edge cases (e.g., selective dynamics tags in POSCAR) would require recompiling CLEED.
• Ecosystem: We would re-invent the wheel. libase and pymatgen already handle thousands of edge cases for file parsing.

Verdict:
Stick to the Python Bridge. It decouples the "Input Parsing" (which changes often and needs flexibility) from the "Physics Engine" (which assumes a strict, clean input state). This maintains the stability of the core CLEED solver while providing the user experience of a modern tool.

[Liam-Deacon]

Comprehensive Plan: Bi-Directional Conversion & Workflow Integration

This comment outlines the strategy for implementing "Two-Way" support for modern formats (POSCAR, ASE, YAML) and integrating them directly into the CLEED program loop via environment hooks.

1. The Core Strategy: "The Python Bridge" (cleed.io)

We will implement a Python sub-package (e.g., cleed.io) acting as a universal translator.

A. Bi-Directional Conversion

• Import (from_modern): POSCAR / ASE / YAML $\to$ .inp + .bul
  • Slicing Algorithm: Automatically detects periodicity in bottom layers to define "Bulk" vs "Overlayer".
  • Metadata Embedding:
    • YAML: Natively supports CLEED params.
    • ASE/ExtXYZ: Stores params in atoms.info dict.
    • POSCAR: Uses strict comment lines (e.g., !CLEED: energy_range=50-200) or a sidecar cleed.json.
• Export (to_modern): .inp + .bul $\to$ POSCAR / ASE / YAML
  • Reconstruction: Stacks .bul and .inp layers back into a single 3D unit cell for visualization in VESTA/Ovito.

B. Library Integration

• ase (Optional): If installed, enables POSCAR, CIF, XYZ support.
• cleedpy (Native): We adopt the cleedpy YAML schema as the "Gold Standard" for structured input.
• **phaseshifts (Integration):
  • The converter checks atoms.symbols.
  • If Ni.phs is missing in CLEED_PHASE, it calls phaseshifts (if installed) to generate it from the element definition.

---

2. Program Loop Integration: "The Hook Strategy"

CLEED's optimizer (csearch) uses environment variables to call its components. We can exploit this to inject our Python logic inside the loop without recompiling C code.

Standard Loop:
csearch $\to$ CSEARCH_LEED (cleed_nsym) $\to$ CSEARCH_RFAC (crfac)

Proposed Hook Loop:
csearch $\to$ CSEARCH_LEED (cleed-wrapper) $\to$ cleed_nsym

The cleed-wrapper Script

A Python script that:

1. Intercepts: Receives the temp .par (parameter) file from csearch.
2. Syncs: Updates the "Master" modern file (e.g., search_trajectory.traj or history.yaml) with the current geometry.
   • Result: Users get a real-time visual trajectory of the LEED optimization in ASE format!
3. Executes: Calls the actual bin/cleed_nsym to do the physics.
4. Returns: Passes the result back to csearch.

---

3. Implementation Checklist

Phase 1: The Converter (cleed.io)

• Implement StructureSlicer class (ASE -> Bulk/Overlayer).
• Implement LegacyWriter (Bulk/Overlayer -> .bul/.inp).
• Implement LegacyReader (.bul/.inp -> ASE).
• Add CLI tool: cleed-convert <input> -o <output>.

Phase 2: Workflow & Hooks

• Create cleed-wrapper entry point.
• Add support for CSEARCH_LEED injection in set_env.sh / set_env.py.
• Implement "Live Trajectory" writing (append-mode for .traj or .xyz).

Phase 3: phaseshifts Support

• Add try_generate_phaseshifts(element) function.
• Integrate with Liam-Deacon/phaseshifts API.

---

4. Dependencies & Packaging

We will support optional extras to keep the core lightweight:

[project.optional-dependencies]
io = ["ase>=3.22", "pyyaml"]
phaseshifts = ["phaseshifts>=0.1.5"]
all = ["ase", "pyyaml", "phaseshifts"]

This ensures that cleed remains a focused physics kernel while enabling powerful workflow integrations for the Python ecosystem.