A Codex skill with executable geometry builders for crystal surfaces, coherent heterojunctions, CSL grain boundaries and adsorption configurations. It combines explicit structure choices with periodic collision screens, reproducible manifests and export roundtrip checks.
The reusable contribution is the construction/validation contract and its bounded glue code. ASE and pymatgen supply the underlying scientific geometry methods. Existing input files are preserved. Outputs are unrelaxed starting geometries.
| Capability | Packaged behavior |
|---|---|
| Crystal acquisition | Bounded Materials Project queries, description/XRD evidence comparison, explicit selection and provenance |
| Surfaces | Supplied-cell Miller indices, termination choices, slab thickness, normal vacuum and layer constraints |
| Coherent heterojunctions | ZSL lattice matching, bounded film strain, explicit terminations, registry and gap |
| CSL grain boundaries | Verified angle, axis, plane and lattice metric; no automatic atom deletion |
| Adsorption | Rigid molecular placement, explicit anchor and height, top-side site classification and image clearance |
| Audit and visualization | Periodic collision screens, export readback, atom mappings and self-contained, rotatable 3D HTML |
The image shows coordinate projections of unrelaxed demonstration models. Each generated candidate also includes a rotatable 3D view.
Obtain your Materials Project API key from the MP API page. Configure it locally as MP_API_KEY or enter it at the hidden terminal prompt when requested. Do not put the key in a query, shared file or repository. An existing crystal file can be used without an API key.
Codex converts the material description or readable card evidence into a structured, bounded query, downloads candidate structures, compares symmetry/cell/diffraction evidence and records the selected material ID. Ambiguous phase matches require a scientific choice. MP computed structures and experimental card values can differ; matching is reported as evidence rather than asserted from the formula alone.
sh scripts/run.sh mp-fetch --query request-mp.json --output crystal-candidates
sh scripts/run.sh mp-select --manifest crystal-candidates/retrieval.json \
--material-id mp-149 --reason "Explicit MP ID supplied by the user" \
--output selected-crystalThe ID above illustrates the command syntax; choose the ID supported by your own request and retrieved evidence. Use selected-crystal/structure.json in the build request. Provisional downloads are refused by the builder until a selection is recorded. See the query schema and XRD workflow.
Requirements: Python 3.12 or newer, Git for cloning, and a WebGL-capable browser for the 3D view. The pinned dependency set was validated on Python 3.12. Materials Project downloads also require an internet connection and your own MP API key.
Clone the public repository into your Codex skills directory:
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/RobinMAJ/atomistic-structure-builder.git \
"${CODEX_HOME:-$HOME/.codex}/skills/atomistic-structure-builder"
cd "${CODEX_HOME:-$HOME/.codex}/skills/atomistic-structure-builder"Alternatively, download a release ZIP and extract its complete atomistic-structure-builder folder into that directory. Start a new Codex session if the skill is not listed. Inspect an existing installation before updating it. For a clean Git installation, git pull --ff-only updates the source; rerun setup when dependencies change.
Create an isolated environment inside the skill:
sh scripts/setup_environment.sh
sh scripts/run.sh build \
--spec assets/example-specs/surface_cu111_demo.json \
--output demo-surface-runsetup_environment.sh prefers python3.12 when available, otherwise python3; override the base interpreter with ATOMISTIC_BUILDER_BASE_PYTHON. It includes the Materials Project client by default. Use sh scripts/setup_environment.sh --without-mp for a smaller installation that only uses local crystal files. To use a compatible environment you already have:
ATOMISTIC_BUILDER_PYTHON=/path/to/environment/bin/python \
sh scripts/run.sh audit structure.cif --slab --output new-audit-runRequirements pin the direct tested dependencies, including the separately distributed pymatgen-core; requirements-mp.txt pins the acquisition client. Local construction and visualization need ASE, pymatgen, spglib, NumPy, SciPy and Matplotlib. They run without a private cluster, NAS, VESTA installation or proprietary potential. The scripts can also be used directly without Codex by supplying the documented JSON specifications.
Try all four synthetic construction examples, each in a new output directory:
sh scripts/run.sh build --spec assets/example-specs/surface_cu111_demo.json --output surface-demo-run
sh scripts/run.sh build --spec assets/example-specs/interface_cu_ni111_demo.json --output interface-demo-run
sh scripts/run.sh build --spec assets/example-specs/gb_cu_sigma5_demo.json --output gb-demo-run
sh scripts/run.sh build --spec assets/example-specs/adsorption_co_cu111_demo.json --output adsorption-demo-runUse $atomistic-structure-builder to construct a (111) surface from this
bulk structure. Use the supplied-cell Miller convention, a minimum slab
thickness of 12 angstrom, 18 angstrom of vacuum and a 2x2 in-plane repeat.
Show termination choices, freeze the bottom two layers, and retain
periodic checks, atom mappings, POSCAR and CIF outputs.
Use $atomistic-structure-builder to enumerate coherent interfaces from
these two bulk files with the stated Miller orientations. Keep the
substrate metric fixed and permit at most 3 percent principal film strain.
Compare explicit terminations, registries and gaps within 300 atoms.
Explain the thin-film reflection and any remaining convergence limits.
Use $atomistic-structure-builder to place this molecule on the supplied
slab, anchored at atom 0 at height 1.9 angstrom. Preserve molecular geometry,
compare the requested orientations and sites, and screen adsorbate images.
Use $atomistic-structure-builder to create a Sigma 5 [001] Cu grain boundary
at 36.86989765 degrees with a (310) boundary plane. Verify the supplied
crystallographic basis, retain both periodic boundaries, compare explicit
registry choices within 300 atoms, and preserve rejected geometries.
Use $atomistic-structure-builder to retrieve rock-salt LiF from Materials
Project and build a LiF(100) slab with intact DMF above a surface Li atom.
Confirm the phase and conventional-cell Miller convention. Use a 3x3
in-plane repeat, eight atomic planes, carbonyl-O anchoring at an initial
2.2 angstrom O-Li separation, and freeze the bottom two substrate planes.
Check final vacuum and molecular images; deliver POSCAR, CIF and a
rotatable 3D HTML. Treat this pose as an unrelaxed starting hypothesis.
Codex interprets descriptions and card images and prepares the JSON request. The command-line helpers consume structured JSON; they do not contain a standalone natural-language parser or OCR engine.
Demo JSONs are synthetic examples. Their cutoffs, heights, registries and lattice constants are not scientific recommendations for another system. Inputs in a request resolve relative to that JSON file.
- A request and manifest with source SHA256, dependency versions, search settings, candidates, failures and output hashes.
- For candidates that pass the configured geometric screen:
POSCAR,structure.cif,structure.extxyz, MSONstructure.json,atom-map.jsonand checks before/after export. - Rejected geometries retained as MSON and check reports; failed runs retain diagnostics.
- An offline, self-contained interactive
viewer.htmlfor rotation, zoom, unit-cell and periodic-image viewing, plus three coordinate-projection previews for visual inspection. These are diagnostic views, not a substitute for checking bonds and crystallographic orientation in VESTA or another viewer.
New output directories are mandatory. Existing paths are refused. The default screen uses a 0.7 angstrom absolute minimum plus 0.55 times the sum of covalent radii. These are configurable collision heuristics, not stability or coordination criteria.
The manifest reports geometry_screen_pass, rejected, all_candidates_rejected or failed. Visual review begins as pending. No energy minimization, electronic calculation, automatic atom deletion, global energetic ranking or remote job submission is included.
The packaged interface route handles coherent crystalline epitaxy. The adsorption route uses top-side adsorption on +z-normal slabs with orthogonal c. Flat-surface families are classified from periodic projected coordination; stepped or rumpled selections require explicit ambiguous-site handling. Both the original site-generator tags and the physical classification are retained. GB construction requires a verified CSL angle and a recognized lattice/basis; noncubic metrics need explicit matching rational ratios. Incoherent, chiral/polar reflection-sensitive, chemically bonded and reconstructed interfaces require a focused custom route described in the skill.
Read the skill, mode decisions, validation limits and tool sources. A geometry that passes is a candidate for further review and relaxation, not an accepted equilibrium structure.
The release suite passes 117 behavioral tests. Four synthetic construction workflows and an independently audited live LiF(100)/DMF example are described in VALIDATION.md, with their scope and remaining scientific questions.
Install the test runner and use the skill environment:
.venv/bin/python -m pip install pytest
.venv/bin/python -m pytest -q testsNode.js on PATH is optional for the delivered JavaScript syntax/controller tests; select another executable with ATOMISTIC_BUILDER_NODE. Those tests skip when Node.js is unavailable. Actual WebGL viewing is a separate visual check. The tests address scientific geometry invariants and rejection behavior; dependency pinning and passing tests do not replace validation on your own material.
SKILL.md Codex instructions and scientific decision gates
agents/openai.yaml Skill discovery metadata
scripts/ Builders, MP retrieval, audits, export and 3D rendering
references/ Mode decisions, validation contract, MP/XRD schema and sources
assets/example-specs/ Editable JSON examples
assets/demo-inputs/ Synthetic demonstration structures
assets/vendor/ Offline 3Dmol.js renderer and license notices
tests/ Behavioral tests
VALIDATION.md Dated evidence and scientific limits
Send a candidate's viewer.html to a collaborator. They can open it in a WebGL-capable browser and rotate, zoom, inspect atom indices, switch Cartesian views and display in-plane periodic images without installing Python or contacting a server. The file contains its renderer, atom coordinates and renderer licenses. It omits source-file paths and credentials, but sharing it discloses the displayed structure.
The default canonical view wraps each atom into one unit cell. Switch to original coordinates when a molecule crosses a boundary. Contact guides are optional geometric aids, not assigned chemical bonds. POSCAR/CIF files do not preserve all per-site properties; use MSON structure.json and the mapping when labels or constraints matter.
The original instructions and integration code use the MIT license. NOTICE.md explains its scope. The vendored 3Dmol.js renderer and bundled components retain the notices in assets/vendor/. Scientific dependencies and Materials Project content retain their respective licenses and terms.