Search molecular conformers, plan adsorption poses, and compare accepted calculation results with reproducible candidate identities and explicit scientific limits.
This Codex skill preserves initial geometries, optimized candidates, duplicate/exclusion decisions, atom indices and source hashes. It helps retain chemical diversity before higher-level refinement and keeps nonconverged calculations out of energy rankings.
Download the skill ZIP · Read the skill instructions · Validation evidence · MIT license
- Seeded organic-molecule ensembles from SMILES or a single explicit-H 3D SDF.
- Optional MMFF94s local optimization, with coverage and per-candidate convergence checks.
- Heavy-atom symmetry-aware RMSD deduplication without mirror reflection; energy-aware duplicate gates, windows and explicit caps.
- Initial/final/retained SDFs, individual SDF/XYZ structures, atom maps, hashes and an offline interactive 3D viewer.
- Conformer × anchor frame × height × rotation planning for the companion Atomistic Structure Builder, which supplies surface site enumeration and periodic collision audits.
- Immutable-source, separately grouped ranking of externally calculated energies; failed calculations are excluded. Optional populations are conditional on caller-declared comparable Gibbs energies and thermochemistry.
CREST/xTB, coordination/ion-pair, periodic registry and DFT refinement routes are documented agent workflows. This package does not bundle or execute those engines. Its organic force field does not validate metal coordination, LiF, LiF–DMF cross interactions or reactive chemistry.
Python 3.12+ is required. Download and extract the complete release ZIP, or clone the repository:
git clone https://github.com/RobinMAJ/multi-configuration-search.git
cd multi-configuration-searchCreate a local environment and run the included examples:
sh scripts/setup_environment.sh
sh scripts/run.sh molecular --spec assets/examples/butane.json --output work/butane
sh scripts/run.sh molecular --spec assets/examples/dmf.json --output work/dmf
sh scripts/run.sh adsorption-plan --spec assets/examples/adsorption_dmf_demo.json --output work/adsorption-plan
sh scripts/run.sh rank --spec assets/examples/ranking_synthetic.json --output work/ranking-demoThe setup creates only a new skill-local .venv and refuses to overwrite one. To use an existing compatible environment, set MULTICONFIG_PYTHON to its Python executable. Requirements permit compatible library versions; each run records the actual versions. See VALIDATION.md for the tested environment.
If your default python3 is older than 3.12, select the supported interpreter with MULTICONFIG_SETUP_PYTHON when running setup. No existing environment is modified.
To install for Codex discovery, copy the complete multi-configuration-search folder into your Codex skills directory, usually ~/.codex/skills/, without overwriting an existing version. Alternatively, clone directly into a new skill folder:
task_skill_root="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$task_skill_root"
git clone https://github.com/RobinMAJ/multi-configuration-search.git "$task_skill_root/multi-configuration-search"
sh "$task_skill_root/multi-configuration-search/scripts/setup_environment.sh"Refresh Codex's skill list, or start a new chat if the skill has not appeared, then invoke $multi-configuration-search. You can also use it directly by providing the path to SKILL.md in a request. Running the helpers from the repository does not require Codex.
Example requests:
Use $multi-configuration-search to sample this molecule with three seeds, preserve stereochemistry, retain diverse candidates and prepare a consistent Gaussian refinement list.
Use $multi-configuration-search to search DMF poses on this LiF(100) slab across carbonyl-O anchors, sites, heights and tilts. Preserve all candidate audits and identify the required interface model before energy ranking.
Open generated viewer.html to switch candidates, rotate/zoom and pick source atom indices. The renderer is embedded and needs no network access. Serve the generated folder on localhost if your browser restricts opening local HTML. Visual review starts pending; an HTML file is not a review receipt.
| Helper | Main outputs | What completion establishes |
|---|---|---|
molecular |
Initial/final/retained SDF ensembles, individual SDF/XYZ files, candidate ledger, atom map, 3D HTML | Bounded organic-molecule sampling and configured local-model screening |
adsorption-plan |
Copied inputs, normalized anchor-frame XYZ files, portable builder requests, candidate-budget ledger | A bounded plan; the companion builder performs placement and periodic audits |
rank |
Immutable result/geometry snapshots and separately grouped ranks | Ranking of caller-declared converged records with verified file hashes |
All helpers require a new output directory and preserve the request, tool snapshots and output-hash manifest. A time-limited or failed search keeps its logs and partial evidence. Full JSON contracts are documented in input contracts.
The release has 40 passing behavioral tests. The examples sampled 48 butane candidates and retained three heavy-atom conformers; 32 DMF candidates retained one under their configured gates. One adsorption batch produced 12 geometries passing the companion builder's geometry screen after the demonstrated periodic-image correction. These are technical checks, with scope and negative evidence recorded in VALIDATION.md.
The lowest sampled score is not a proven global minimum. MMFF scores are preliminary isolated-molecule values, not DFT energies, adsorption energies, free energies or experimental populations. Candidate discovery counts are not statistical weights.
Different chemistry, coverage, constraints or methods require separate comparison/reference treatment. Native logs, final geometry and frequency evidence must support refinement and thermochemistry. Endpoint ensembles alone do not establish barriers, kinetics or selectivity. Search plans refuse oversized Cartesian products instead of silently capping them.
Read search routes, input contracts, acceptance criteria and validation evidence.
Original instructions, orchestration and integration are MIT licensed. RDKit and the embedded 3Dmol.js renderer retain their own licenses; see NOTICE.md. Scientific software/data used for subsequent refinement must be cited and licensed separately.
Backend API references: RDKit conformer generation, RDKit alignment, CREST sampling examples. CREST is optional and was not run in package validation.