View source for User:AngelHerraez/Sandbox/Two-col TOC

{{File_Formats}}
{{TOC_two_col}}
= 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, <code>File > Open</code>,
* 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

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.''

<br />

== MOL and SD (Symyx MDL) ==
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 [[File_formats/Export|write]] them too).
Original from Molecular Design Limited, then Elsevier MDL, now Symyx Technologies, 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 [[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 now 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 v.12 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:
* 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 [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>jmolscript:</code>.

Official document (PDF): http://www.symyx.com/downloads/public/ctfile/ctfile.pdf, copied [{{SVN Trunk}}Jmol-datafiles/mol/ctfile.pdf here].

Some extra information on SD files at [http://www.epa.gov/ncct/dsstox/MoreonSDF.html US EPA DSSTox].

Example files for MOL and SDF [{{SVN Trunk}}Jmol-datafiles/mol/ v2000] and [{{SVN Trunk}}Jmol-datafiles/v3000/ v3000].

<br />

== MOL2 (Sybyl, Tripos) ==
Jmol reads MOL2 files.
Original from Tripos.
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.

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

[{{SVN Trunk}}Jmol-datafiles/mol2/ Example files].

<br />

== 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 [[Support_for_isotopes | isotopes]] (as D and T); they are all read by Jmol. 
If you need support for partial charges, see the similar [[#PQR|PQR format]] below.

Files may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>REMARK  jmolscript:</code>.

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

[{{SVN Trunk}}Jmol-datafiles/pdb/ Example files].

'''''Special use:'''''

Jmol can get files directly from the Protein Data Bank website. 
To do this, you put an equal sign (=) just before the 4-character PDB ID code (without any extensions). Note that the unsigned applet is not allowed connection to external servers and so does not support this method.

See also [[#CIF|CIF]] for loading ligands directly from the PDB database.

Example:
 load =1CRN

By default, Jmol will connect to the PDB server at http://www.rcsb.org/
To force the use of another server, you can do:
 set loadFormat = "  "
and put between the quotes the url in the proper request format; use <code>%FILE</code> at the position where the PDB ID should be inserted into the url.
[http://chemapps.stolaf.edu/jmol/docs/#k436 More details]

Examples:
 set loadFormat = "<nowiki>http://www.rcsb.org/pdb/files/%FILE.pdb</nowiki>"
 set loadFormat = "<nowiki>http://www.ebi.ac.uk/msd-srv/oca/oca-bin/save-pdb?id=%FILE</nowiki>"

<br />

== 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 [[Support_for_isotopes | 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 [[#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.

[{{SVN Trunk}}Jmol-datafiles/xyz/ Example files].

[[File_formats/Formats/XYZ|Details about the XYZ format]].

<br />

== CIF ==
Jmol reads CIF files.
Crystallographic Information File, the official format from the International Union of Crystallography: 
* v. 1.0 [http://www.iucr.org/iucr-top/cif/standard/cifstd1.html Original documentation], 
''Acta Crystallographica'' A'''47''': 655-685 (1991) <br>[http://dx.doi.org/10.1107/S010876739101067X doi:10.1107/S010876739101067X]
* v. 1.1 the [http://www.iucr.org/iucr-top/cif/spec/version1.1/ 2003 update].

CIF files may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>#jmolscript:</code>.

[{{SVN Trunk}}Jmol-datafiles/cif/ Example files].

'''''Special use:'''''

Jmol can get files directly from the ligand collection at the Protein Data Bank website. 
To do this, you put two equal signs (==) just before the 3-character PDB CIF ID code (without any extensions). Note that the unsigned applet is not allowed connection to external servers and so does not support this method.

Example:
 load ==2TY

By default, Jmol will connect to the PDB server at http://www.rcsb.org/pdb/files/ligand/
To force the use of another server, you can do:
 set ligandLoadFormat = "  "
and put between the quotes the url in the proper request format; use <code>%FILE</code> at the position where the PDB CIF ID should be inserted into the url.

<br />

== mmCIF ==
Jmol reads mmCIF files.
Macromolecular Crystallographic Information File, an expanded format to cope with macromolecules.
[http://www.pdb.org/robohelp/ftp/files_formats/structures/chemical_component_format/chemical_component_mmcif_format.htm Official documentation].

[{{SVN Trunk}}Jmol-datafiles/cif/ Example files].

<br />

== Alchemy (Tripos) ==
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.

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

[{{SVN Trunk}}Jmol-datafiles/alchemy/ Example files] supported by Jmol.

<br />

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

[http://www.msg.ameslab.gov/GAMESS/doc.menu.html Official documentation].

[{{SVN Trunk}}Jmol-datafiles/gamess/ Example files].

<br />

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

There are [{{SVN Trunk}}Jmol-datafiles/gaussian/ example files] of Gaussian input, output and log.

<br />

== Cube (Gaussian) ==
Jmol reads Cube files, original from Gaussian software ([http://www.gaussian.com/ Gaussian website]).

Description of Cube Input and Cube Output formats:
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.

[{{SVN Trunk}}Jmol-datafiles/cube/ Example files].

<br />

== 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 <code>solvent</code> 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 <code>.gro</code>

[http://manual.gromacs.org/current/online/gro.html Description] of the format.

[{{SVN Trunk}}Jmol-datafiles/gromacs/ Example files].

Utilities:
* You can convert from '''gro''' to '''pdb''' using the [http://manual.gromacs.org/current/online/editconf.html 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 [http://manual.gromacs.org/current/online/trjconv.html trjconv] utility, included in the GROMACS installation. It will read a GROMACS trajectory file (.xtc or .trr) and output a .pdb file. So:
:#  Use trjconv to generate a .pdb file.
:#  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) ==
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].

[[File formats/Formats/HIN|Details of HIN format]].

<br />

== MOPAC ==
Jmol reads '''mopout''' output files from [http://openmopac.net/ MOPAC] 
and the new '''graphf''' output from MOPAC2007 (<code>.mgf</code> files), which 
contains coordinates, charges, and molecular orbitals.

openMOPAC, Molecular Orbital PACkage, public domain.

[{{SVN Trunk}}Jmol-datafiles/mopac/ Example files].

<br />

== PQR ==
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

<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 <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://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.''

<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].

<br />

== Amber ==
Jmol (11.7 or later) reads molecular dynamics output files from [http://ambermd.org/ '''Amber''']. The fileset must have a structure like: 

1 (topology file) + n (coordinate files) 

The <code>filter</code> option of the <code>load</code> 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 [http://biomodel.uah.es/Jmol/amber/ example].

[{{SVN Trunk}}Jmol-datafiles/amber/ Example files].

<br />

== V3000 (Symyx MDL) ==
See [[File_formats#MOL_and_SD_.28Symyx_MDL.29|MOL]].

<br />

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

[{{SVN Trunk}}Jmol-datafiles/qchem/ Example files].

<br />

== JME ==
This is the native format from [http://www.molinspiration.com/jme/ JME Molecular Editor] (by Peter Ertl).

See [[File_formats/Chemical_Structure#JME]]

<br />

== CASTEP ==
Jmol (11.8) can read <code>.cell</code> files in the [http://www.castep.org 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. 

<br />

== FHI-aims ==
Jmol (11.8) can read <code>geometry.in</code> files in the [http://www.fhi-berlin.mpg.de/aims/ 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.

<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
 

= 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 [[Jmol_Application | application]] and the [[Jmol_Applet#Unsigned_vs._Signed_Applet_.26_Data_Access | 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 [{{ScriptingDoc}}#write <code>write</code> command] (from script or from the console).

The [[Jmol_Application | application]] and the [[Jmol_Applet#Unsigned_vs._Signed_Applet_.26_Data_Access | signed applet]] also allow to save a '''copy''' of the loaded file (any format) via the pop-up menu > <tt>Save</tt> > <tt>File</tt>.

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