An open-source Codex skill for reproducible molecular force-field generation with GAFF2 and OpenFF, native topology audits, mixed-system compatibility review and bounded torsion fitting. It keeps molecular identity, charge assignment, parameter provenance and export evidence together so that a generated model can be reviewed before simulation. Its command-line helpers can also run without Codex.
The workflow draws on the AuToFF official manual and HZW cloud tool. Local generation uses the explicitly selected AmberTools/OpenFF backend. AuToFF-exported Amber or GROMACS files can enter the native audit route. Read the integration boundary for the observed login requirement and documented capabilities.
Release: v1.0.0 · Skill ZIP · Validation record · MIT license
| Route | Packaged behavior | Scientific boundary |
|---|---|---|
| GAFF2 | AmberTools26 typing, explicit AM1-BCC or supplied charges, native Amber assembly and OpenMM evaluation | Suggested missing parameters require review; organic coverage is not universal |
| OpenFF | Optional unconstrained Sage 2.2.1, explicit AmberTools AM1-BCC or supplied charges, OpenMM evaluation | Exact OFFXML and charge backend remain part of the model |
| Native audit | Read supplied Amber or GROMACS topology/coordinates and inspect an isolated model | Loading is not proof of parameter provenance or predictive accuracy |
| Mixture audit | Check declared charge, scaling, mixing, cross-pair and provenance compatibility | Metadata review cannot create missing interactions or validate a heterogeneous system |
| Torsion fitting | Fit bounded Fourier corrections to supplied QM-minus-baseline data with separated train/validation/test groups | No QM launch, automatic topology patch or universal acceptance threshold |
Packaged generation covers one connected, closed-shell organic molecule with a confirmed graph, protonation and stereochemistry. Preparation produces explicit hydrogens and records atom ordering. Generated molecular models and native audits use isolated, unconstrained evaluation. Periodic materials, slab electrostatics, reactive chemistry, polarizable models, Hessian fitting and ML potentials are handled through documented specialist workflows.
OpenMM XML and eligible Amber/GROMACS files are supported outputs. Any requested export failure fails the generation job; partial artifacts and diagnostics are retained. GROMACS roundtrip checks through OpenMM readers are distinct from running GROMACS itself. LAMMPS equivalence is not claimed.
Verified atom mapping preserves authoritative prepared coordinates in native exports, subject to each format's precision. GROMACS includes standard molecule.gro at 0.01 Å precision and molecule-highprecision.gro at
Prerequisites are Git (when cloning), Conda and a POSIX shell. The pinned environment was tested on macOS arm64; installation and native backends on other systems have not been verified. A compatible WebGL browser is needed for the interactive viewer. The release ZIP contains the complete skill and examples; dependencies are installed separately.
Install the complete folder for Codex:
git clone https://github.com/RobinMAJ/forcefield-generator.git ~/.codex/skills/forcefield-generator
cd ~/.codex/skills/forcefield-generator
sh scripts/setup_environment.shGit clone refuses a nonempty destination; the setup script refuses any existing .venv. Preserve an existing installation before choosing a new destination. For a custom Codex home, use its skills/forcefield-generator folder. Alternatively, extract the release ZIP and run the helpers from the extracted folder.
Keep this folder complete, including scripts, references and examples. The setup script creates an isolated Python 3.12 Conda prefix at .venv from environment.yml, using conda-forge with other default channels disabled. It includes the GAFF2 and OpenFF dependencies and refuses to replace an existing environment. Conda must be on PATH, or set FF_GENERATOR_CONDA to its executable. The launcher selects .venv/bin/python; FF_GENERATOR_PYTHON can select another compatible interpreter. Base and unrelated research environments remain separate.
For Codex discovery, install the complete folder at ~/.codex/skills/forcefield-generator; inspect and preserve any existing folder instead of overlaying it.
Run commands from the skill folder, or provide its actual location:
sh scripts/run.sh --help
sh scripts/run.sh prepare --spec assets/examples/dmf_gaff2.json --output work/dmf-preflight
sh scripts/run.sh generate --spec assets/examples/dmf_gaff2.json --output work/dmf-gaff2
sh scripts/run.sh generate --spec assets/examples/dmf_openff.json --output work/dmf-openffExample Codex request:
Use $forcefield-generator to generate a GAFF2/AM1-BCC model for DMF, export OpenMM, Amber and GROMACS files, and report atom mapping, charge policy and export checks.
The DMF examples are initial molecular candidates. SMILES preparation adds explicit hydrogens and generates one seeded conformer. A one-record 3D SDF must already contain explicit hydrogens and confirmed chemical identity; its input atom order is preserved. Every request must declare integer formal charge, multiplicity, backend and charge method. Inspect the example requests and route guide before preparing a different molecule.
Preparation checks identity and supplies the atom-order evidence needed for supplied charges. Generation retains backend inputs, intermediate files and acceptance evidence. Choose a new output directory for every attempt. The optional OpenFF example is assets/examples/dmf_openff.json; audit_amber.json and audit_gromacs.json illustrate native auditing. Native audits require boundary: isolated; files with a box require acknowledge_file_box_ignored_for_isolated_audit: true. mixture_lif_dmf_incomplete.json demonstrates why missing cross interactions leave a model incomplete.
The DMF generation examples explicitly permit bounded AM1-BCC rounding correction. Without charge_normalization, sums must match within uniform_roundoff policy requires explicit total/per-atom bounds, capped at 0.005 e and 0.0005 e respectively; raw charges and corrections are retained. Provided charges are never corrected. This is a numerical charge-sum policy, not chemical refitting.
sh scripts/run.sh audit --spec assets/examples/audit_amber.json --output work/native-audit
sh scripts/run.sh audit --spec assets/examples/audit_gromacs.json --output work/gromacs-audit
sh scripts/run.sh audit-mixture --spec assets/examples/mixture_lif_dmf_incomplete.json --output work/mixture-audit
sh scripts/run.sh fit-torsion --request assets/examples/torsion-synthetic-request.json --output work/torsion-fitThe incomplete mixture example intentionally returns compatibility_blocked with exit 3. The torsion example uses analytic synthetic data to demonstrate the helper and its held-out gate; it is not a physical QM scan or a fitted molecular model.
Request data, including coordinates, charges and parameter files, remain local unless a separate authorized workflow explicitly uses an external service. AuToFF integration consists of optional user-exported native-file auditing; no public API or application source license was verified.
| File | Purpose |
|---|---|
atom-map.json, input.sdf |
Prepared identity, atom order, explicit hydrogens and coordinate provenance |
reference-system.xml, system.xml |
Reference Hamiltonian and requested OpenMM export |
molecule.prmtop, molecule.inpcrd |
Amber topology and coordinates |
molecule.top, molecule.gro, molecule-highprecision.gro |
GROMACS topology and two coordinate precisions |
parameters.json, checks.json, export-checks.json |
Charges/types, parameter inventory and per-force conversion evidence |
manifest.json, backend logs and source records |
Input/tool/output hashes, versions, commands and retained diagnostics |
viewer.html |
Embedded 3D molecule with rotation, zoom, charge coloring and atom-index inspection |
Requested output formats control native exports. OpenFF export type labels are ParmEd labels; SMIRNOFF patterns are recorded in parameter-labels.json. The standalone viewer uses bundled 3Dmol.js bytes and does not fetch external assets. Open it in a WebGL-capable browser; a browser that restricts local HTML can use a localhost preview:
.venv/bin/python -m http.server 8873 --bind 127.0.0.1 --directory work/dmf-gaff2Then visit http://127.0.0.1:8873/viewer.html. This preview is local to that computer. Before sharing a generated run, review its original inputs, backend logs and provenance paths for information you intend to disclose. The public skill package contains no runtime, local research outputs or credentials.
The CLI uses exit 0 for a reported technical pass, exit 2 for invalid/failed execution and exit 3 for blocked mixture compatibility or a failed torsion validation gate. A successful return never establishes scientific accuracy. Use a new output directory for each attempt; the helpers retain failed-run diagnostics rather than overwriting previous results.
Parameter assignment, finite energies, consistent atom mapping and export roundtrips establish technical properties of a candidate. Validation against relevant held-out QM, experimental or material data is a separate step. A DMF topology does not parameterize LiF, and placing DMF above LiF does not supply validated adsorption interactions.
The release validation record documents 142 passing tests, live molecular export checks, independent forward evaluation and remaining scientific limits.
Use route selection to choose the model and validation to review evidence and failures. AuToFF notes explain its documented capabilities and the import boundary. The optional companion Atomistic Structure Builder provides source-geometry preparation; it is not a required dependency or force-field validator.
Original work in this package concerns instructions, orchestration, provenance and validation glue. Parameterization algorithms, force fields, simulation engines and conversion libraries belong to their respective authors and retain their own licenses and citation requirements. Consult the packaged notices and cite the exact versions and parameter sets used.
MIT applies to original code and instructions; the bundled renderer retains its upstream license. See NOTICE.md, renderer provenance and CITATION.cff. This is an independent project; the AuToFF implementation and parameter databases are not bundled. Refer to CHANGELOG.md for release scope.
Primary sources: AmberTools, Amber parameterization tutorial, SMIRNOFF specification, Interchange export limits, and OpenMM documentation.