{"id":33175303,"url":"https://github.com/paduagroup/fftool","last_synced_at":"2025-11-20T20:02:33.930Z","repository":{"id":12344537,"uuid":"14987727","full_name":"paduagroup/fftool","owner":"paduagroup","description":"Tool to build force field input files for molecular simulation","archived":false,"fork":false,"pushed_at":"2025-02-20T14:17:46.000Z","size":357,"stargazers_count":179,"open_issues_count":1,"forks_count":60,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-09-08T21:59:04.555Z","etag":null,"topics":["force-field","lammps","molecular-dynamics","packmol"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paduagroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-06T16:32:18.000Z","updated_at":"2025-09-06T04:35:38.000Z","dependencies_parsed_at":"2023-12-03T19:28:43.186Z","dependency_job_id":"14c86e8a-ba61-4527-8b6d-81208015a4d5","html_url":"https://github.com/paduagroup/fftool","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/paduagroup/fftool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduagroup%2Ffftool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduagroup%2Ffftool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduagroup%2Ffftool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduagroup%2Ffftool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paduagroup","download_url":"https://codeload.github.com/paduagroup/fftool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduagroup%2Ffftool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285503668,"owners_count":27182913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-20T02:00:05.334Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["force-field","lammps","molecular-dynamics","packmol"],"created_at":"2025-11-16T02:00:37.344Z","updated_at":"2025-11-20T20:02:33.923Z","avatar_url":"https://github.com/paduagroup.png","language":"Python","funding_links":[],"categories":["Simulations"],"sub_categories":["Force Fields"],"readme":"# fftool\n\n[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.18618.svg)](http://dx.doi.org/10.5281/zenodo.18618)\n\n_[Agilio Padua](http://perso.ens-lyon.fr/agilio.padua)_\n\nThis is a Python tool to build force field input files for molecular dynamics\nsimulations of systems composed of molecules, ions or extended materials.\n\n`fftool` creates initial files for classical, fixed-charge molecular dynamics\nsimulations. A force field database ionic liquids is available in\n[CL\u0026P](https://github.com/agiliopadua/clandp). For polarizable force field and\nsimulations, check the [CL\u0026Pol](https://github.com/agiliopadua/clandpol) tools\nand database.\n\n\n## Contents\n\n* `fftool`: builds a simulation box and the corresponding force field for\n    systems containing molecules, ions or extended materials. It requires the\n    [Packmol](http://www.ime.unicamp.br/~martinez/packmol/) software to generate\n    coordinates in the box. It outputs files in formats suitable for the\n    [LAMMPS](http://lammps.sandia.gov/), [OpenMM](http://openmm.org),\n    [GROMACS](http://www.gromacs.org) or\n    [DL_POLY](http://www.stfc.ac.uk/CSE/randd/ccg/software/DL_POLY/25526.aspx)\n    molecular dynamics packages.\n\n* `tools/`: utility scripts.\n\n* `examples/`: examples of molecule files and force field databases.\n\n\n## Requirements\n\n* [Python](http://www.python.org/)\n\n* [Packmol](http://www.ime.unicamp.br/~martinez/packmol/) to pack\n  molecules and materials in the simultion box.\n  \n\n## Obtaining\n\nDownload the files or clone the repository:\n\n    git clone https://github.com/agiliopadua/fftool.git\n\n\n## Tutorial\n\nThese are instructions on how to build an force field files and an initial\nconfiguration for a system composed of molecules, ions or materials. \n\n1. For each molecule, ion or fragment of a material prepare a file with atomic\n   coordinates and eventually connectivity (covalent bonds). The formats\n   accepted by this tool are `.zmat`, `.xyz`, `.pdb` or `.mol`, which are\n   common formats in computational chemistry.\n\n   A `.zmat` file has the molecule name in the first line, followed by one empty\n   line, then the z-matrix. See the `examples` directory and the Wikipedia entry\n   [Z-matrix(chemistry)](https://en.wikipedia.org/wiki/Z-matrix).  Variables can\n   be used in place of distances, angles and dihedrals. `fftool` infers\n   connectivity (topology) from the z-matrix by default. In this case cyclic\n   molecules require additional `connect` records to close rings. Improper\n   dihedrals can be indicated by `improper` records. If a `reconnect` record is\n   present, then connectivity will be guessed based on bond distances from the\n   force field (see below). Below the z-matrix and the informations above, the\n   name of a file with force field parameters can be supplied.\n\n   The XYZ file format `.xyz` contains atomic coordinates only. The name of a\n   file with force field parameters can be given in the second line after the\n   molecule name, and in this case connectivity is deduced from the bond lengths\n   in the force field.\n\n   The PDB file format `.pdb` is widely used for proteins. The name of a file\n   with force field parameters can be given on a `COMPND` record after the\n   molecule name.  `fftool` infers connectivity from the bond lengths in the\n   force field (`CONECT` records are not read).\n \n   The MDL Molfile `.mol` file format contains a table with coordinates and\n   also bonds. The name of a file with force field parameters can be given in\n   the first line after the molecule name or in the third line. If the keyword\n   `reconnect` is present after the force field filename, then connectivity\n   will be deduced based on bond distances from the force field.\n\n   There are many tools ([Open Babel](http://openbabel.org/),\n   [Avogadro](http://avogadro.cc/), [VESTA](http://jp-minerals.org/vesta/en/))\n   to create file in the above formats. Manual editing of the files is usually\n   necessary in order to match the atom names with those of the force field.\n\n2. Use `fftool` to create an input file for `packmol`, which will use new\n   `_pack.xyz` files with atomic coordinates for the components of your\n   system. For help type `fftool -h`. For example, to build a simulation box\n   with 40 ethanol and 300 water molecules and a density of 38.0 mol/L do:\n\n        fftool 40 ethanol.zmat 300 spce.zmat -r 38.0\n\n    Alternatively, the side length of the the simulation box (here cubic) can\n    be supplied in angstroms:\n\n        fftool 40 ethanol.zmat 300 spce.zmat -b 20.0\n\n3. Use `packmol` with the `pack.inp` file just created to generate the\n   atomic coordinates in the simulation box:\n\n        packmol \u003c pack.inp\n\n   A difficult convergence may indicate that density is too high, so adjust\n   density or box size if necessary. For more complex spatial arrangements of\n   molecules and materials you can modify the `pack.inp` to suit your needs (see\n   the [Packmol](http://www.ime.unicamp.br/~martinez/packmol/) documentation).\n   Atomic coordinates for the full system are written to `simbox.xyz`.\n\n4. Use `fftool` to create input files for LAMMPS (-l), OpenMM (-x), GROMACS\n   (-g) ou DL_POLY (-d) containing the force field parameters and the\n   coordinates of all the atoms (taken from `simbox.xyz`):\n\n        fftool 40 ethanol.zmat 300 spce.zmat -r 38.0 -l\n\n    If no force field information was given explicitly in the molecule files, a\n    default LJ potential with parameters zeroed will be assigned to atoms. No\n    terms for bonds, angles or torsions will be created. This is suitable when\n    working with non-additive, bond-order or other potentials often used for\n    materials. The input files for MD simulations will have to be edited\n    manually to include interaction potentials.\n\n\n## Deducing Bonds and Angles\n\nWhen inferring connectivity from atomic coordinates, distances in the\ncoordinates file are compared with equilibrium distances specified for bonds in\nthe force field, and a tolerance of +/-0.25 angstrom is used to decide if a bond\nis created. So, the bond lengths in the conformation present in the molecule\nfile must be close to those in the force field specification for those bonds to\nbe included in the potential energy fonction of the system. The user is advised\nto check the number of bonds by creating a test system with the minimum of\nmolecules.\n\nAngles will be assigned to groups of three atoms i-j-k, with i-j and j-k bonded,\nif the value of the angle in the conformation from the molecule file is within\n+/-15 degrees of the equilibrium angle in the force field. If not, even if the\natoms i-j-k are bonded, their angle will not be present in the final potential\nenergy function, although topologically the angle is there. When running\n`fftool` to create a force field file (with `-l`, `-x`, ` -g` or `-d` option) a\nwarning message will show which such topological angles have been \"removed\"\nbecause they deviate too much from the equilibrium angles in the force\nfield. This removal of angles avoids problems with atoms that have more than\nfour ligands, such as S or P atoms with five or six ligands. Around these\ncenters there are topological angles of 180 degrees to which no potential energy\nof bending is attributed in force fields. For example, in the octahedral PF6-\nanion there are two different values of F-P-F angles: twelve 90 degree angles\nbetween adjacent F atoms, and three 180 degree angles between opposite F atoms;\nonly the twelve 90 degree angles contribute with a harmonic potential energy\nfunction in most force fields.\n\nThe tolerances for bond distances and angle values, 0.25 angstrom and 15\ndegrees, respectively, were chosen based on judgement. They can be set by\nediting the `fftool` source, namely the global variables `BondTol` and\n`AngleTol`. Use with care because spurious bonds and angles may be created if\nthe tolerances are set too large.\n\n\n## Improper Dihedrals\n\nImproper dihedrals are often used to increase the rigidity of planar atoms (sp2)\nand differ from proper dihedrals in how they are defined. A proper dihedral\ni-j-k-l is defined between bonded atoms i-j, j-k, and k-l and corresponds to\ntorsion around bond j-k, the dihedral being the angle between planes i-j-k and\nj-k-l. An improper dihedral i-j-k-l is defined between bonded atoms i-k, j-k and\nk-l, therefore k is a central atom bonded to the other three. `fftool` assumes\nthe central atom of the improper dihedral to be the third in the list. Often in\nforce fields the same potential energy function is used both for proper and\nimproper torsions.\n\nIf `improper` records are supplied in a molecule file (in `.zmat` format) then\nthose improper dihedrals are read by `fftool`. Otherwise, the script will search\nfor candidate improper dihedrals on all atoms with three bonds, whatever the\ninput format. Warning messages will be printed if there are atoms with three\nbonds, and these messages can be ignored if the atoms in question are not\ncenters of improper torsions. The user is advised to check the number and order\nof the atoms in the true improper dihedrals in the files created, by testing\nwith a minimal system.\n\n\n## Periodic Boundary Conditions\n\nIn molecular systems the initial configuration will generaly not contain\nmolecules crossing boundaries of the simulation box. A buffer distance of 1.5\nangstrom is reserved at the box boundaries to avoid overlap of molecules from\nperiodic images in the initial configuration, as explained in the `packmol`\ndocumentation (this empty space is added by `fftool` only for orthogonal\nboxes). So the user should be aware of this empty volume when choosing the size\nof the box.\n\nFor simulations with extended materials it is possible to create chemical bonds\nacross boundaries. Option `-p` allows specification of periodic conditions along\nx, y, z or combinations thereof. It is important in this case to supply box\ndimensions using the option `-b \u003cl\u003e` for a cubic box, `-b \u003clx,ly,lz\u003e` for a\ngeneral orthogonal box, or `-b \u003ca,b,c,alpha,beta,gamma\u003e` for a general\nparallelepiped (triclinic box). An energy minimization step prior to the start\nof the MD simulation is highly recommended because `fftool` will leave no extra\nspace near the boundaries and certain molecules may overlap with those of\nneighboring images.\n\nThe coordinates of the atoms of the material have to be supplied in `.xyz`\nformat and prepared carefully so that distances across periodic boundaries are\nwithin the tolerance to identify bonds. The user is advised to check the number\nof bonds in the output files created.\n\nIt is important that only the material for which bonds are to be established\nacross boudaries is supplied in `.xyz` format. The initial files for other\nmolecules in the system should be in `.zmat` or `.mol` formats, which contain\nconnectivity information. This is to avoid spurious bonds between atoms of the\nmolecular species that may happen to be positioned too close to boundaries.\n\nThe `pack.inp` file will likely need manual editing in order to position the\natoms of the material precisely.\n\n\n## Force Field File Format\n\nThe `fftool` script reads a database of molecular force field parameters in `xml` format (similar to the format used by OpenMM), or in the original `.ff` format described below. See the `examples` directory.\n\nThe `ff2xml` script converts from the original to the `xml` format.\n\n### .ff format\n\nBlank lines and lines starting with `#` are ignored.\n\nThere are five sections, with headings `ATOMS`, `BONDS`, `ANGLES`, `DIHEDRALS`\nand `IMPROPER`. Under each section heading, registers concerning the different\ntypes of term in the force field are given.\n\n`ATOMS` records describe, for each type of atom:\n* the non-bonded atom type used for intermolecular interactions (these\n  types may differ in the charges or intermolecular potential\n  parameters)\n* the bonded atom type used in intermolecular interactions (these\n  types determine the intramolecular terms such as bonds, angles\n  dihedrals)\n* the mass in atomic units\n* the electrostatic charge in elementary units\n* the non-bonded potential type, e.g. `lj`\n* potential parameters, namely Lennard-Jones `sigma` (angstrom) and `epsilon`\n  (kJ mol-1)\n\n        C3H   CT  12.011  -0.18   lj    3.50   0.27614\n\n`BONDS` records describe covalent bonds between intramolecular atom types:\n* two bonded atom types\n* type of bond potential, e.g. `harm` for harmonic potential or\n  `cons` for a constrained bond.\n* bond potential parameters, namely equilibrium distance (angstrom) and force\n  constant in the form k/2 (x - x0)^2 (kJ mol-1 A-2)\n\n        CT  CT   harm   1.529   2242.6\n\n`ANGLES` records describe valence angles between intramolecular atom types:\n* three bonded atom types, in which the central atom is bonded to the other\n  two, e.g. i-j and j-k are bonded.\n* type of angle potential, e.g. `harm` for harmonic potential or\n  `cons` for a constrained angle.\n* angle potential parameters, namely equilibrium angle (degrees) and force\n  constant in the form k/2 (x - x0)^2 (kJ mol-1 rad-2)\n\n        HC  CT  CT   harm   110.7   313.8\n\n`DIHEDRALS` records describe torsion angles between intramolecular\natom types:\n* four bonded atom types, in which atoms i-j, j-k, k-l are bonded.\n* type of dihedral potential, e.g. `opls` for OPLS cosine series with\n  four terms.\n* dihedral potential parameters, with the coefficients in the form V_n/2\n  (1 +/- cos(n phi)) (kJ mol-1).\n\n        CT  CT  CT  CT   opls    5.4392   -0.2092    0.8368    0.0000\n\n`IMPROPER` records describe improper dihedral angles between\nintramolecular atom types:\n* four bonded atom types, in which atoms i-k, j-k, k-l are bonded.\n* type of dihedral potential, e.g. `opls` for OPLS cosine series with\n  four terms.\n* dihedral potential parameters, with the coefficients in the form\n  V_n/2 (1 +/- cos(n phi)) (kJ mol-1).\n\n        CA  CA  CA  HA   opls    0.0000    9.2048    0.0000    0.0000\n\n\n## References\n\n* [Packmol](http://www.ime.unicamp.br/~martinez/packmol/):\n  L. Martinez et al. J Comp Chem 30 (2009) 2157, DOI:\n  [10.1002/jcc.21224](http://dx.doi.org/10.1002/jcc.21224) \n  \n* [LAMMPS](http://lammps.sandia.gov/): S. Plimton, J Comp Phys\n  117 (1995) 1, DOI:\n  [10.1006/jcph.1995.1039](http://dx.doi.org/10.1006/jcph.1995.1039)\n\n* [OpenMM](http://openmm.org): P. Eastman, J. Swails, J. D. Chodera,\n  R. T. McGibbon, Y. Zhao, K. A. Beauchamp, L.-P. Wang, A. C. Simmonett,\n  M. P. Harrigan, C. D. Stern, R. P. Wiewiora, B. R. Brooks, and\n  V. S. Pande. PLOS Comp. Biol. 13 (2017) e1005659, DOI:\n  [10.1371/journal.pcbi.1005659](https://doi.org/10.1371/journal.pcbi.1005659)\n\n* [GROMACS](http://www.gromacs.org/): H.J.C. Berendsen, D. van der\n  Spoel, R. van Drunen, Comp Phys Commun, 91 (1995) 43, DOI:\n  [10.1016/0010-4655(95)00042-E](https://doi.org/10.1016/0010-4655(95)00042-E)\n\n* [DL_POLY](http://www.stfc.ac.uk/CSE/randd/ccg/software/DL_POLY/25526.aspx):\n  I.T. Todorov and W. Smith, Daresbury Lab. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaduagroup%2Ffftool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaduagroup%2Ffftool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaduagroup%2Ffftool/lists"}