Difference between revisions of "File formats/Coordinates"

From Jmol
Jump to navigation Jump to search
(new CASTEP and AIMS formats)
(SPARTAN, SMOL, SPARCHIVE)
 
(41 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
= File Formats for the Atomic Coordinates of the Molecule =
 
= File Formats for the Atomic Coordinates of the Molecule =
  
== MOL and SD (Symyx MDL) ==
+
These files are loaded into Jmol by either of the following methods:
 +
* using the application's topbar menu,
 +
** <code>File > Open</code> will open a standard dialog for browsing local disk
 +
** <code>File > Open URL</code> will ask for a location on the web
 +
** <code>File > Get PDB</code> will ask for a 4-character PDB ID and retrieve the file from PDB at RCSB (see [[Database Connection]])
 +
** <code>File > Get MOL</code> will ask for some kind of supported chemical name or id and retrieve the file from Cactus Resolver at NCI (see [[Database Connection]])
 +
* using the <code>load</code> command in the command line, in the Jmol scripting console, or in a script,
 +
* dragging and dropping the file onto the Jmol application window
 +
 
 +
Jmol will read any file and try to determine its format from its content. The file extension is not taken into account for identifying the format.
 +
You can instruct Jmol as to which format to assume using this special command syntax:
 +
 
 +
: <code>load </code>''fileFormat''<code>::</code>''fileName''
 +
where ''fileName'' includes the path, the file name itself and the file extension; paths may be absolute or relative; a full URL may also be used.
 +
 
 +
''fileFormat'' will be a keyword recognized by Jmol that designates that format. (Here is a [[File_formats/LoadFormatPrefixes|list of format values]])
 +
 
 +
Examples:
 +
load mol::aspirin.txt
 +
load pqr::1crn.pdb
 +
load tinker::molecs/abc.txt
 +
load molpro(xml)::ethanol.txt
 +
 
 +
What follows is a collection of specifications and comments on several formats, but is not a complete listing of all formats supported.
 +
''Feel free to add a subsection with a description of a format you know well.''
 +
 
 +
 
 +
__TOC__
 +
 
 +
 
 +
== MOL and SD ==
 
MOL = MDL molfile = MOL v2000
 
MOL = MDL molfile = MOL v2000
  
Line 11: Line 41:
 
: This newer format applies to both MOL and SDF, hasn't got the 1000-atom limit and is also supported by Jmol.
 
: This newer format applies to both MOL and SDF, hasn't got the 1000-atom limit and is also supported by Jmol.
  
Jmol reads MOL v2000 and v3000, and SD files (and can write MOLv2000 files under some circumstances).
+
Jmol reads MOL v2000 and v3000, and SD files (and can [[File_formats/Export|write]] them too).
Original from Molecular Design Limited, then Elsevier MDL, now Symyx Technologies, widely adopted by many other programs.
+
Original from Molecular Design Limited, then Elsevier MDL, then Symyx Technologies, then BIOVIA Dassault Systèmes, widely adopted by many other programs.
 
Contains atom coordinates and bonds. V2000 (the most common) is limited to 1000 atoms.
 
Contains atom coordinates and bonds. V2000 (the most common) is limited to 1000 atoms.
  
These formats support formal charges and [[Support_for_isotopes | isotopes]]; both are read by Jmol.
+
These formats support formal charges and [[Support_for_isotopes | isotopes]]; both are read by Jmol. A variant used in PubChem adds partial charges using a custom field <code><PUBCHEM_MMFF94_PARTIAL_CHARGES></code>, and this is also read by Jmol.
  
 
There are often MOL and SD files with two-dimensional data (i.e, all atoms have Z=0); Jmol will read them too, but the resulting flat model will not be realistic.
 
There are often MOL and SD files with two-dimensional data (i.e, all atoms have Z=0); Jmol will read them too, but the resulting flat model will not be realistic.
 
The defining tag (2D or 3D) must be located in line 2, columns 21-22, but is ignored by Jmol, which just uses the Z coordinates provided, be they zero or not.
 
The defining tag (2D or 3D) must be located in line 2, columns 21-22, but is ignored by Jmol, which just uses the Z coordinates provided, be they zero or not.
 +
 +
: Jmol has two ways to deal with such flat models:
 +
:* you can run the [{{ScriptingDoc}}#minimize<code>minimize</code> command] after loading; this will apply a simple UFF force field to reach a reasonable 3D structure;
 +
:* or you can load the file using the [{{ScriptingDoc}}#loadgeneraloptions<code>filter "2D"</code> switch] of the load command, in this way:
 +
::<code>load myfile.mol filter "2D"</code>
 +
:: That will load the flat model and, before it is displayed, will add hydrogens if needed and then run a minimization; the result is a 3D model of the input 2D structure with a feasible conformation.
  
 
MOL header lines:
 
MOL header lines:
Line 25: Line 61:
 
* The third line is for comments, and may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>jmolscript:</code>.
 
* The third line is for comments, and may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>jmolscript:</code>.
  
Official document (PDF): http://www.mdl.com/downloads/public/ctfile/ctfile.pdf, copied [{{SVN Trunk}}Jmol-datafiles/mol/ctfile.pdf here].
+
Official document (PDF):  
 +
* [http://accelrys.com/products/informatics/cheminformatics/ctfile-formats/no-fee.php 2003 version], copied [{{SVN Trunk}}Jmol-datafiles/mol/ctfile.pdf here].
 +
* [http://help.accelrysonline.com/ulm/onelab/1.0/content/ulm_pdfs/direct/reference/ctfileformats2016.pdf 2015 version] (BIOVIA)
  
 
Some extra information on SD files at [http://www.epa.gov/ncct/dsstox/MoreonSDF.html US EPA DSSTox].
 
Some extra information on SD files at [http://www.epa.gov/ncct/dsstox/MoreonSDF.html US EPA DSSTox].
Line 31: Line 69:
 
Example files for MOL and SDF [{{SVN Trunk}}Jmol-datafiles/mol/ v2000] and [{{SVN Trunk}}Jmol-datafiles/v3000/ v3000].
 
Example files for MOL and SDF [{{SVN Trunk}}Jmol-datafiles/mol/ v2000] and [{{SVN Trunk}}Jmol-datafiles/v3000/ v3000].
  
 +
<br />
  
 
== MOL2 (Sybyl, Tripos) ==
 
== MOL2 (Sybyl, Tripos) ==
Line 37: Line 76:
 
Contains atom coordinates, bonds, substructure information.
 
Contains atom coordinates, bonds, substructure information.
  
This format supports formal charges, partial charges and [[Support_for_isotopes | isotopes]], but only partial charges are currrently supported by Jmol.
+
This format supports <!--formal charges,--> partial charges and [[Support_for_isotopes | isotopes]], but only partial charges are currrently supported by Jmol.
  
 
A single MOL2 file may contain several structures, which will be read by Jmol as multiple models or frames.
 
A single MOL2 file may contain several structures, which will be read by Jmol as multiple models or frames.
Line 45: Line 84:
 
[{{SVN Trunk}}Jmol-datafiles/mol2/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/mol2/ Example files].
  
 +
<br />
  
 
== PDB ==
 
== PDB ==
Line 57: Line 97:
 
(Official Protein Data Bank document) Atomic Coordinate Entry Format.
 
(Official Protein Data Bank document) Atomic Coordinate Entry Format.
 
Description:
 
Description:
http://www.wwpdb.org/documentation/format23/v2.3.html
+
http://www.wwpdb.org/docs.html
  
 
[{{SVN Trunk}}Jmol-datafiles/pdb/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/pdb/ Example files].
  
 +
'''''Special use:'''''
 +
 +
Jmol can get files directly from the Protein Data Bank website. See [[Database_Connection]].
 +
 +
<br />
  
 
== XYZ ==
 
== XYZ ==
Jmol reads XYZ files (and can write XYZ files under some circumstances). Originally from XMol package, but has been widely adopted by many other programs. Contains only atom coordinates (no bonds) and, optionally, charges and vectors (e.g. for atom vibration). Supports multi-model data (multi-frame, animations).
+
Jmol reads XYZ files (and can write XYZ files under some circumstances). This format was originally from the XMol package, but has been widely adopted by many other programs. Contains only atom coordinates (no bonds) and, optionally, charges and vectors (e.g. for atom vibration). Supports multi-model data (multi-frame, animations).
  
 
An extension of this format supports [[Support_for_isotopes | isotopes]], and they are read by Jmol.
 
An extension of this format supports [[Support_for_isotopes | isotopes]], and they are read by Jmol.
Line 69: Line 114:
 
XYZ header lines:
 
XYZ header lines:
 
* The first line is reserved for the number of atoms.
 
* The first line is reserved for the number of atoms.
* The second line is for comments, and may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]]  starting with <code>jmolscript:</code>.
+
* The second line is for comments, and may contain an [[File_formats/Scripting#Script_inline_within_a_molecular_coordinates_file | inline script]]  starting with <code>jmolscript:</code>.
  
[http://local.wasp.uwa.edu.au/~pbourke/dataformats/xyz/ Example] by Paul Bourke.
+
[http://paulbourke.net/dataformats/xyz/ Example] by Paul Bourke.
  
 
[{{SVN Trunk}}Jmol-datafiles/xyz/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/xyz/ Example files].
  
Description:
+
[[File_formats/Formats/XYZ|Details about the XYZ format]].
:XYZ datafiles specify molecular geometries using a Cartesian coordinate system. This simple, stripped-down, ASCII-readable format is intended to serve as a "transition" format for the XMol series of applications. For example, suppose a molecular datafile was in a format not supported by XMol. In order to read the data into XMol, it would be possible to modify the datafile, perhaps by creating a shell script, so that it fit the relatively lenient requirements of the XYZ format specification. Once data is in XYZ format, it may be examined by XMol, or converted to yet another format.
 
:The XYZ format supports '''multi-step datasets'''. '''Each step''' is represented by a two-line "header," followed by one line for each atom. The '''first line''' of a step's header is the number of atoms in that step. This  integer  may be preceded by whitespace; anything on the line after the integer is ignored.  The '''second line''' of the header leaves room for a descriptive string. This line may be blank, or it may contain some information pertinent to that particular step, but it must exist, and  it must be just one line long. '''Each line of text describing a single atom''' must  contain at least four fields of information, separated by whitespace: the atom's type (a short string of alphanumeric characters), and  its x-, y-, and z-positions. Optionally, extra fields may be used to specify a charge for the atom, and/or a vector associated with the atom. If an input line contains five or eight fields, the fifth field is interpreted as the atom's charge; otherwise, a charge of zero is assumed. If an input line contains seven or eight fields, the last three fields are interpreted as the components of a vector. These components should be specified in angstroms.
 
:Note that the XYZ format doesn't contain '''connectivity''' information. This intentional omission allows for greater flexibility: to create an XYZ file, you don't need to know where a molecule's bonds are; you just need to know where its atoms are. Connectivity information is generated automatically for XYZ files as they are read into XMol-related applications. Briefly, if the distance between two atoms is less than the sum of their covalent radii, they are considered bonded.
 
 
 
:''Source: man page for XYZ (part of XMol), quoted at http://www.ccl.net/chemistry/resources/messages/1996/10/21.005-dir/index.html''
 
 
 
The XYZ reader in Jmol reads any of the following (updated for Jmol v. 11.4.5 and 11.5.41):
 
<pre>
 
Sym  x  y  z
 
Sym  x  y  z    vibX  vibY  vibZ
 
Sym  x  y  z    FormalCharge(integer)
 
Sym  x  y  z    FormalCharge(integer)    vibX  vibY  vibZ
 
Sym  x  y  z    PartialCharge(decimal)
 
Sym  x  y  z    PartialCharge(decimal)    vibX  vibY  vibZ
 
</pre>
 
:where <code>Sym</code> is either an element symbol (C, Fe, Si) or an element symbol preceded by a supported isotope number (2H, 13C, etc.)
 
  
 +
<br />
  
 
== CIF ==
 
== CIF ==
Line 105: Line 135:
 
[{{SVN Trunk}}Jmol-datafiles/cif/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/cif/ Example files].
  
 +
'''''Special use:'''''
 +
 +
Jmol can get files directly from the ligand collection at the Protein Data Bank website. See [[Database_Connection#PDB]].
 +
 +
<br />
  
 
== mmCIF ==
 
== mmCIF ==
Line 113: Line 148:
 
[{{SVN Trunk}}Jmol-datafiles/cif/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/cif/ Example files].
  
 +
<br />
  
 
== Alchemy (Tripos) ==
 
== Alchemy (Tripos) ==
 
Jmol does not fully support reading of Alchemy and Alchemy2000 files. A simple Alchemy reader is implemented starting Jmol 11.7.18.
 
Jmol does not fully support reading of Alchemy and Alchemy2000 files. A simple Alchemy reader is implemented starting Jmol 11.7.18.
[http://local.wasp.uwa.edu.au/~pbourke/dataformats/alc/alc3/ Alchemy example] and [http://local.wasp.uwa.edu.au/~pbourke/dataformats/alc/ Alchemy2000 description] by Paul Bourke.
+
[http://paulbourke.net/dataformats/alc/alc3/ Alchemy example] and [http://paulbourke.net/dataformats/alc/ Alchemy2000 description] by Paul Bourke.
  
 
A complete specification of these formats would be needed to fully implement the reader. If you have those details, please contact the developers team.
 
A complete specification of these formats would be needed to fully implement the reader. If you have those details, please contact the developers team.
Line 122: Line 158:
 
[{{SVN Trunk}}Jmol-datafiles/alchemy/ Example files] supported by Jmol.
 
[{{SVN Trunk}}Jmol-datafiles/alchemy/ Example files] supported by Jmol.
  
 +
<br />
  
 
== GAMESS ==
 
== GAMESS ==
Line 130: Line 167:
 
[{{SVN Trunk}}Jmol-datafiles/gamess/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/gamess/ Example files].
  
 +
<br />
  
 
== Gaussian ==
 
== Gaussian ==
Line 137: Line 175:
 
There are [{{SVN Trunk}}Jmol-datafiles/gaussian/ example files] of Gaussian input, output and log.
 
There are [{{SVN Trunk}}Jmol-datafiles/gaussian/ example files] of Gaussian input, output and log.
  
 +
<br />
  
 
== Cube (Gaussian) ==
 
== Cube (Gaussian) ==
Line 144: Line 183:
 
http://www.nersc.gov/nusers/resources/software/apps/chemistry/gaussian/g98/00000430.htm
 
http://www.nersc.gov/nusers/resources/software/apps/chemistry/gaussian/g98/00000430.htm
  
[http://local.wasp.uwa.edu.au/~pbourke/dataformats/cube/ Description] by Paul Bourke.
+
[http://paulbourke.net/dataformats/cube/ Description] by Paul Bourke.
  
 
[{{SVN Trunk}}Jmol-datafiles/cube/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/cube/ Example files].
  
 +
<br />
  
 
== GROMACS ==
 
== GROMACS ==
Line 167: Line 207:
 
:#  Load the .pdb file into Jmol (using the [http://www.stolaf.edu/academics/chemapps/jmol/docs/#loadtrajectory trajectory] option) and animate.
 
:#  Load the .pdb file into Jmol (using the [http://www.stolaf.edu/academics/chemapps/jmol/docs/#loadtrajectory trajectory] option) and animate.
  
 +
<br />
  
 
== HIV / HIN (Hyperchem) ==
 
== HIV / HIN (Hyperchem) ==
 
Jmol reads HIV (or HIN) files, the native format of Hyperchem, a software sold by [http://www.hyper.com/ Hypercube Inc.].
 
Jmol reads HIV (or HIN) files, the native format of Hyperchem, a software sold by [http://www.hyper.com/ Hypercube Inc.].
  
[http://local.wasp.uwa.edu.au/~pbourke/dataformats/hyperchem/ Example] by Paul Bourke, and other [{{SVN Trunk}}Jmol-datafiles/hin/ example files].
+
[http://paulbourke.net/dataformats/hyperchem/ Example] by Paul Bourke, and other [{{SVN Trunk}}Jmol-datafiles/hin/ example files].
  
 +
[[File formats/Formats/HIN|Details of HIN format]].
 +
 +
<br />
  
 
== MOPAC ==
 
== MOPAC ==
Line 183: Line 227:
 
[{{SVN Trunk}}Jmol-datafiles/mopac/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/mopac/ Example files].
  
 +
<br />
  
 
== PQR ==
 
== PQR ==
Jmol (11.1.30 or later) reads PQR files.
+
Jmol reads and writes PQR files. However, since they are very similar to <code>pdb</code> files, they may be misread.
 +
: ''Version support'': reading {{file|pqr}} started at Jmol v. 11.1.30; writing {{file|pqr}} files started at v. 12.3.2
 +
: If the file contains a line that starts with "REMARK 1 PQR" (3 spaces before the '1', one after it), it will be interpreted as <code>pqr</code> format. Otherwise, Jmol will interpret it as a <code>pdb</code> file (and so will not get the charge and radii correct). To force the file be read as <code>pqr</code>, add <code>pqr::</code> just before the filepath in the <code>load</code> command, like this:
 +
load pqr::somePath/someFileName.pqr
  
PQR format is a format based on <code>[[#PDB|pdb]]</code>, where the ''occupancy'' is replaced with the atomic charge and the ''temperature'' (or ''B factor'') is replaced with atomic radius (however, the column positions in many pqr files do not match those of pdb files). This gives the acronym: '''P''' for pdb, '''Q''' for charge, '''R''' for radius. Jmol interprets the charge values (property ''partialcharge'') and the radii (property ''vanderwaals''), and can hence use them e.g. in <code>color atoms partialCharge</code> and <code>spacefill</code>.
+
<code>pqr</code> is a format based on <code>[[#PDB|pdb]]</code>, where the ''occupancy'' is replaced with the atomic charge and the ''temperature'' (or ''B factor'') is replaced with atomic radius (however, the column positions in many pqr files do not match those of pdb files). This gives the acronym: '''P''' for pdb, '''Q''' for charge, '''R''' for radius. Jmol interprets the charge values (property ''partialcharge'') and the radii (property ''vanderwaals''), and can hence use them e.g. in <code>color atoms partialCharge</code> and <code>spacefill</code>.
  
The PQR format has somewhat uncertain origins, but is used by several computational biology packages, including MEAD, AutoDock and [http://apbs.sourceforge.net/ APBS], for which it is the primary input format.
+
The <code>pqr</code> format has somewhat uncertain origins, but is used by several computational biology packages, including MEAD, AutoDock and [http://apbs.sourceforge.net/ APBS], for which it is the primary input format.
  
[http://apbs.sourceforge.net/doc/user-guide/index.html#pqr-format PQR format description] within APBS documentation. ''Note that APBS reads PQR loosely, based only on white space delimiters, but Jmol may be more strict about column positions.''
+
[http://www.poissonboltzmann.org/file-formats/biomolecular-structurw/pqr PQR format description]. ''Note that APBS reads PQR loosely, based only on white space delimiters, but Jmol may be more strict about column positions.''
  
PDB files can be converted to PQR by the [http://pdb2pqr.sourceforge.net/ PDB2PQR] software, which adds missing hydrogen atoms and calculates the charge and radius parameters from a variety of force fields.
+
Ideally, one should follow the PDB specifications, which are:
 +
* pdb ''occupancy'' / pqr ''charge'': columns 55 to 60, decimal point at 58.
 +
* pdb ''B-factor'' / pqr ''radius'': columns 61 to 66, decimal point at 64.
 +
 
 +
<code>pdb</code> files can be converted to <code>pqr</code> by the [http://pdb2pqr.sourceforge.net/ PDB2PQR] software, which adds missing hydrogen atoms and calculates the charge and radius parameters from a variety of force fields.
  
 
[{{SVN Trunk}}Jmol-datafiles/pqr/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/pqr/ Example files].
  
 +
<br />
  
 
== Amber ==
 
== Amber ==
Line 210: Line 263:
 
[{{SVN Trunk}}Jmol-datafiles/amber/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/amber/ Example files].
  
 +
<br />
  
 
== V3000 (Symyx MDL) ==
 
== V3000 (Symyx MDL) ==
See [[File_formats#MOL_and_SD_.28Symyx_MDL.29|MOL]].
+
See [[File_formats/Coordinates#MOL_and_SD_.28Symyx_MDL.29|MOL]].
  
 +
<br />
  
 
== Q-Chem ==
 
== Q-Chem ==
Line 220: Line 275:
 
[{{SVN Trunk}}Jmol-datafiles/qchem/ Example files].
 
[{{SVN Trunk}}Jmol-datafiles/qchem/ Example files].
  
 +
<br />
  
 
== JME ==
 
== JME ==
The [http://www.molinspiration.com/jme/ JME Molecular Editor] (by Peter Ertl) is an applet which allows to draw, edit and display molecules and reactions within a web page.
+
This is the native format from [http://www.molinspiration.com/jme/ JME Molecular Editor] (by Peter Ertl).
Among its output formats there is a proprietary [http://www.molinspiration.com/jme/doc/jme_functions.html JME format], formed by a single line of text with atom and bond data.
 
Jmol has a basic support to read this format from a file (only single and multipart structures are supported, but not reactions).
 
Of course, being a drawing program, the structures produced are flat.
 
  
''This support is rather experimental and not much needed, since JME-ME can also export to 2D MOL format, much better supported by Jmol.''
+
See [[File_formats/Chemical_Structure#JME]]
 
 
[{{SVN Trunk}}Jmol-datafiles/jme/ Example files].
 
  
 +
<br />
  
 
== CASTEP ==
 
== CASTEP ==
Line 236: Line 288:
 
: CASTEP is a software package which uses density functional theory to provide a good atomic-level description of all manner of materials and molecules.  
 
: CASTEP is a software package which uses density functional theory to provide a good atomic-level description of all manner of materials and molecules.  
  
 +
<br />
  
 
== FHI-aims ==
 
== FHI-aims ==
Line 241: Line 294:
 
:  FHI-aims (from Fritz-Haber-Institut der Max-Planck-Gesellschaft) is an all-electron electronic structure code based on numeric atom-centered orbitals.
 
:  FHI-aims (from Fritz-Haber-Institut der Max-Planck-Gesellschaft) is an all-electron electronic structure code based on numeric atom-centered orbitals.
  
 +
<br />
 +
 +
== DGRID ==
 +
Jmol (11.9.14) can read DGRID files; this format is a generalized representations of output from a variety of quantum mechanical calculation packages, including especially ADF (Amsterdam Density Functional).
 +
 +
<br />
 +
 +
== Z-matrix ==
 +
Jmol (12.3.7) can open files with [http://en.wikipedia.org/wiki/Z-matrix_%28chemistry%29 Z-matrix data], an
 +
internal coordinate representation, that provides for each atom its element symbol, bond lengths, bond angles and dihedral angles.
 +
This format is used e.g. by the MOPAC ([http://openmopac.net Molecular Orbital PACkage]) programs.
 +
 +
This format will be assumed when reading a file whose content starts with
 +
<code>#ZMATRIX</code> or by using
 +
load zmatrix::myFileName
 +
Any line that starts with # will be taken as a comment (and it can contain an
 +
[[File_formats/Scripting#Script_inline_within_a_molecular_coordinates_file|inline script]]). Blank lines are ignored.
 +
 +
Any position number may be replaced by a unique atom name+number (as in example number 3 below).
 +
 +
Dummy atoms are allowed, using X or Xn.
 +
 +
Bond order may be specified as an additional integer on the line.
 +
 +
Examples:
 +
<pre>#ZMATRIX
 +
# methane
 +
C
 +
H  1 1.089000
 +
H  1 1.089000  2  109.4710
 +
H  1 1.089000  2  109.4710  3  120.0000
 +
H  1 1.089000  2  109.4710  3 -120.0000
 +
</pre>
 +
<pre>#ZMATRIX
 +
# carbon dioxide
 +
C
 +
O  1 1.3000               2 
 +
O  1 1.3000    2  180     2
 +
</pre>
 +
<pre>#ZMATRIX
 +
# carbon dioxide
 +
C1
 +
O1  C1 1.3000             2
 +
O2  C1 1.3000  O1  180    2
 +
</pre>
 +
<pre>#ZMATRIX
 +
# ammonia (using simple angles only)
 +
# Negative distance indicates that the second angle is a normal angle, not a dihedral:
 +
N1
 +
H1 N1  1.0
 +
H2 N1  1.0  H1  107 
 +
H3 N1 -1.0  H1  107  H2 107
 +
</pre>
 +
<pre>#ZMATRIX
 +
# ammonia (using simple angles only)
 +
# Negative distance and one negative angle reverses the chirality:
 +
N1
 +
H1 N1  1.0
 +
H2 N1  1.0  H1  107
 +
H3 N1 -1.0  H1 -107  H2 107
 +
</pre>
 +
 +
<br />
 +
 +
== KCF ==
 +
'''This format is not supported by Jmol'''.
 +
''These notes are here for future reference.''
 +
 +
KCF (KEGG Chemical Function) format is the standard used by the
 +
Kyoto Encyclopedia of Genes and Genomes ([http://www.genome.jp/kegg/ KEGG]) and the Resource for Informatics of Glycomes at Soka ([http://rings.t.soka.ac.jp/ RINGS]). It is somewhat similar to the {{file|mol}} format.
 +
* Development of a chemical structure comparison method for integrated analysis of chemical and genomic information in the metabolic pathways. M. Hattori, Y. Okuno, S. Goto, M. Kanehisa (2003) ''Journal of the American Chemical Society'' '''125''':11853-11865 PMID:14505407 doi:10.1021/ja036030u
 +
 +
<br />
 +
 +
== SPARTAN, SMOL, SPARCHIVE ==
 +
Jmol can read these, which are proprietary formats of the Spartan software by [https://www.wavefun.com/support WaveFunction]
 +
 +
See [https://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-datafiles/spartan/ some examples] of these files.
 +
 +
<br />
  
 
= Exporting Coordinates =
 
= Exporting Coordinates =

Latest revision as of 16:52, 17 February 2023

File Formats

File Formats for the Atomic Coordinates of the Molecule

These files are loaded into Jmol by either of the following methods:

  • using the application's topbar menu,
    • File > Open will open a standard dialog for browsing local disk
    • File > Open URL will ask for a location on the web
    • File > Get PDB will ask for a 4-character PDB ID and retrieve the file from PDB at RCSB (see Database Connection)
    • File > Get MOL will ask for some kind of supported chemical name or id and retrieve the file from Cactus Resolver at NCI (see Database Connection)
  • using the load command in the command line, in the Jmol scripting console, or in a script,
  • dragging and dropping the file onto the Jmol application window

Jmol will read any file and try to determine its format from its content. The file extension is not taken into account for identifying the format. You can instruct Jmol as to which format to assume using this special command syntax:

load fileFormat::fileName

where fileName includes the path, the file name itself and the file extension; paths may be absolute or relative; a full URL may also be used.

fileFormat will be a keyword recognized by Jmol that designates that format. (Here is a list of format values)

Examples:

load mol::aspirin.txt
load pqr::1crn.pdb
load tinker::molecs/abc.txt
load molpro(xml)::ethanol.txt

What follows is a collection of specifications and comments on several formats, but is not a complete listing of all formats supported. Feel free to add a subsection with a description of a format you know well.



MOL and SD

MOL = MDL molfile = MOL v2000

SD = SDF = Structure Data Format

SD files share the MOL format but may contain several structures (separated by lines with $$$$), which will be read by Jmol as multiple models or frames.

MOLv3000 = extended molfile or extended connection table

This newer format applies to both MOL and SDF, hasn't got the 1000-atom limit and is also supported by Jmol.

Jmol reads MOL v2000 and v3000, and SD files (and can write them too). Original from Molecular Design Limited, then Elsevier MDL, then Symyx Technologies, then BIOVIA Dassault Systèmes, widely adopted by many other programs. Contains atom coordinates and bonds. V2000 (the most common) is limited to 1000 atoms.

These formats support formal charges and isotopes; both are read by Jmol. A variant used in PubChem adds partial charges using a custom field <PUBCHEM_MMFF94_PARTIAL_CHARGES>, and this is also read by Jmol.

There are often MOL and SD files with two-dimensional data (i.e, all atoms have Z=0); Jmol will read them too, but the resulting flat model will not be realistic. The defining tag (2D or 3D) must be located in line 2, columns 21-22, but is ignored by Jmol, which just uses the Z coordinates provided, be they zero or not.

Jmol has two ways to deal with such flat models:
  • you can run the minimize command after loading; this will apply a simple UFF force field to reach a reasonable 3D structure;
  • or you can load the file using the filter "2D" switch of the load command, in this way:
load myfile.mol filter "2D"
That will load the flat model and, before it is displayed, will add hydrogens if needed and then run a minimization; the result is a 3D model of the input 2D structure with a feasible conformation.

MOL header lines:

  • The first line is reserved for the molecule name and will be so used by Jmol in the popup menu.
  • The second line is in principle reserved for information on the originating program, date, user, etc. (Jmol will ignore this line).
  • The third line is for comments, and may contain an inline script starting with jmolscript:.

Official document (PDF):

Some extra information on SD files at US EPA DSSTox.

Example files for MOL and SDF v2000 and v3000.


MOL2 (Sybyl, Tripos)

Jmol reads MOL2 files. Original from Tripos. Contains atom coordinates, bonds, substructure information.

This format supports partial charges and isotopes, but only partial charges are currrently supported by Jmol.

A single MOL2 file may contain several structures, which will be read by Jmol as multiple models or frames.

Official document: http://www.tripos.com/data/support/mol2.pdf

Example files.


PDB

Jmol reads PDB files (and can write PDB files under some circumstances). Contains atom coordinates and information on biomolecular residues, sequence, chains, hydrogen and disulfide bonds, secondary structure, biologically relevant sites, cofactors. Can also contain temperature factor, formal charge, element symbol, alternate locations.

This format supports formal charges, and only hydrogen isotopes (as D and T); they are all read by Jmol. If you need support for partial charges, see the similar PQR format below.

Files may contain an inline script starting with REMARK jmolscript:.

(Official Protein Data Bank document) Atomic Coordinate Entry Format. Description: http://www.wwpdb.org/docs.html

Example files.

Special use:

Jmol can get files directly from the Protein Data Bank website. See Database_Connection.


XYZ

Jmol reads XYZ files (and can write XYZ files under some circumstances). This format was originally from the XMol package, but has been widely adopted by many other programs. Contains only atom coordinates (no bonds) and, optionally, charges and vectors (e.g. for atom vibration). Supports multi-model data (multi-frame, animations).

An extension of this format supports isotopes, and they are read by Jmol.

XYZ header lines:

  • The first line is reserved for the number of atoms.
  • The second line is for comments, and may contain an inline script starting with jmolscript:.

Example by Paul Bourke.

Example files.

Details about the XYZ format.


CIF

Jmol reads CIF files. Crystallographic Information File, the official format from the International Union of Crystallography:

Acta Crystallographica A47: 655-685 (1991)
doi:10.1107/S010876739101067X

CIF files may contain an inline script starting with #jmolscript:.

Example files.

Special use:

Jmol can get files directly from the ligand collection at the Protein Data Bank website. See Database_Connection#PDB.


mmCIF

Jmol reads mmCIF files. Macromolecular Crystallographic Information File, an expanded format to cope with macromolecules. Official documentation.

Example files.


Alchemy (Tripos)

Jmol does not fully support reading of Alchemy and Alchemy2000 files. A simple Alchemy reader is implemented starting Jmol 11.7.18. Alchemy example and Alchemy2000 description by Paul Bourke.

A complete specification of these formats would be needed to fully implement the reader. If you have those details, please contact the developers team.

Example files supported by Jmol.


GAMESS

Jmol reads GAMESS files (General Atomic and Molecular Electronic Structure System, by Gordon research group at Iowa State University).

Official documentation.

Example files.


Gaussian

Jmol reads only the output format. Recent versions of Jmol application can also export to files in Gaussian input format.

There are example files of Gaussian input, output and log.


Cube (Gaussian)

Jmol reads Cube files, original from Gaussian software (Gaussian website).

Description of Cube Input and Cube Output formats: http://www.nersc.gov/nusers/resources/software/apps/chemistry/gaussian/g98/00000430.htm

Description by Paul Bourke.

Example files.


GROMACS

Jmol (11.7.47 or later) reads GRO files; coordinates are assumed to be in nanometers; data are read as if a PDB file, with secondary structure assigned automatically and elements inferred from atom names. UREA and SOL are included in the solvent set. Also, force vectors are read and included as vibrations (activated by default on file load).

File format is called gro or Gromos87. Usual extension is .gro

Description of the format.

Example files.

Utilities:

  • You can convert from gro to pdb using the editconf program, which is a part of the GROMACS package that can be run from the command line:
editconf -f whatever.gro -o whatever.pdb
  • You can also use the trjconv utility, included in the GROMACS installation. It will read a GROMACS trajectory file (.xtc or .trr) and output a .pdb file. So:
  1. Use trjconv to generate a .pdb file.
  2. Load the .pdb file into Jmol (using the trajectory option) and animate.


HIV / HIN (Hyperchem)

Jmol reads HIV (or HIN) files, the native format of Hyperchem, a software sold by Hypercube Inc..

Example by Paul Bourke, and other example files.

Details of HIN format.


MOPAC

Jmol reads mopout output files from MOPAC and the new graphf output from MOPAC2007 (.mgf files), which contains coordinates, charges, and molecular orbitals.

openMOPAC, Molecular Orbital PACkage, public domain.

Example files.


PQR

Jmol reads and writes PQR files. However, since they are very similar to pdb files, they may be misread.

Version support: reading File icon.gifpqr started at Jmol v. 11.1.30; writing File icon.gifpqr files started at v. 12.3.2
If the file contains a line that starts with "REMARK 1 PQR" (3 spaces before the '1', one after it), it will be interpreted as pqr format. Otherwise, Jmol will interpret it as a pdb file (and so will not get the charge and radii correct). To force the file be read as pqr, add pqr:: just before the filepath in the load command, like this:
load pqr::somePath/someFileName.pqr

pqr is a format based on pdb, where the occupancy is replaced with the atomic charge and the temperature (or B factor) is replaced with atomic radius (however, the column positions in many pqr files do not match those of pdb files). This gives the acronym: P for pdb, Q for charge, R for radius. Jmol interprets the charge values (property partialcharge) and the radii (property vanderwaals), and can hence use them e.g. in color atoms partialCharge and spacefill.

The pqr format has somewhat uncertain origins, but is used by several computational biology packages, including MEAD, AutoDock and APBS, for which it is the primary input format.

PQR format description. Note that APBS reads PQR loosely, based only on white space delimiters, but Jmol may be more strict about column positions.

Ideally, one should follow the PDB specifications, which are:

  • pdb occupancy / pqr charge: columns 55 to 60, decimal point at 58.
  • pdb B-factor / pqr radius: columns 61 to 66, decimal point at 64.

pdb files can be converted to pqr by the PDB2PQR software, which adds missing hydrogen atoms and calculates the charge and radius parameters from a variety of force fields.

Example files.


Amber

Jmol (11.7 or later) reads molecular dynamics output files from Amber. The fileset must have a structure like:

1 (topology file) + n (coordinate files)

The filter option of the load command can be used, as well as a new option to allow selective "first,last,step" loading of coordinate trajectories.

(This is preliminary and needs testing). You can see an example.

Example files.


V3000 (Symyx MDL)

See MOL.


Q-Chem

Jmol reads files output from the computational chemistry package Q-Chem. See the Q-Chem specific section.

Example files.


JME

This is the native format from JME Molecular Editor (by Peter Ertl).

See File_formats/Chemical_Structure#JME


CASTEP

Jmol (11.8) can read .cell files in the CASTEP format (only periodic boundary conditions).

CASTEP is a software package which uses density functional theory to provide a good atomic-level description of all manner of materials and molecules.


FHI-aims

Jmol (11.8) can read geometry.in files in the FHI-aims format (both cluster models and periodic boundary conditions).

FHI-aims (from Fritz-Haber-Institut der Max-Planck-Gesellschaft) is an all-electron electronic structure code based on numeric atom-centered orbitals.


DGRID

Jmol (11.9.14) can read DGRID files; this format is a generalized representations of output from a variety of quantum mechanical calculation packages, including especially ADF (Amsterdam Density Functional).


Z-matrix

Jmol (12.3.7) can open files with Z-matrix data, an internal coordinate representation, that provides for each atom its element symbol, bond lengths, bond angles and dihedral angles. This format is used e.g. by the MOPAC (Molecular Orbital PACkage) programs.

This format will be assumed when reading a file whose content starts with #ZMATRIX or by using

load zmatrix::myFileName

Any line that starts with # will be taken as a comment (and it can contain an inline script). Blank lines are ignored.

Any position number may be replaced by a unique atom name+number (as in example number 3 below).

Dummy atoms are allowed, using X or Xn.

Bond order may be specified as an additional integer on the line.

Examples:

#ZMATRIX
# methane
C
H  1 1.089000
H  1 1.089000  2  109.4710
H  1 1.089000  2  109.4710  3  120.0000
H  1 1.089000  2  109.4710  3 -120.0000
#ZMATRIX
# carbon dioxide
C 
O  1 1.3000               2 
O  1 1.3000    2  180     2 
#ZMATRIX
# carbon dioxide
C1 
O1  C1 1.3000             2 
O2  C1 1.3000  O1  180    2 
#ZMATRIX
# ammonia (using simple angles only)
# Negative distance indicates that the second angle is a normal angle, not a dihedral:
N1
H1 N1  1.0
H2 N1  1.0  H1  107 
H3 N1 -1.0  H1  107  H2 107
#ZMATRIX
# ammonia (using simple angles only)
# Negative distance and one negative angle reverses the chirality:
N1
H1 N1  1.0
H2 N1  1.0  H1  107 
H3 N1 -1.0  H1 -107  H2 107


KCF

This format is not supported by Jmol. These notes are here for future reference.

KCF (KEGG Chemical Function) format is the standard used by the Kyoto Encyclopedia of Genes and Genomes (KEGG) and the Resource for Informatics of Glycomes at Soka (RINGS). It is somewhat similar to the File icon.gifmol format.

  • Development of a chemical structure comparison method for integrated analysis of chemical and genomic information in the metabolic pathways. M. Hattori, Y. Okuno, S. Goto, M. Kanehisa (2003) Journal of the American Chemical Society 125:11853-11865 PMID:14505407 doi:10.1021/ja036030u


SPARTAN, SMOL, SPARCHIVE

Jmol can read these, which are proprietary formats of the Spartan software by WaveFunction

See some examples of these files.


Exporting Coordinates

Jmol has a limited capability for writing molecular coordinates, including only the currently selected set of atoms. (This allows to save the whole model, maybe in a format different from the original one, or to extract a subset of the atoms in the original model).

Due to Java security restraints, only the application and the signed applet can write to files on disk. The unsigned applet can however display the exported data in the console window, from where you can copy it, paste into a text editor and save it to file.

Only MOL, XYZ and PDB formats are supported for export. The method is to use the write command (from script or from the console).

The application and the signed applet also allow to save a copy of the loaded file (any format) via the pop-up menu > Save > File.

The application can also export to Gaussian input format using the top menu and a dialog.

Contributors

AngelHerraez, Pbourke