Jmol Application

Running Jmol / JSmol

• Jmol as a standalone application.
• J(S)mol as a web applet or HTML5 object.
  • compatibility with JavaScript frameworks or libraries.
• J(S)mol embedded in wikis or blogs.
• Borrowed JSmol, or running JSmol without your own server.
• Running Jmol using Java Web Start.
• JSmol in a Jupyter notebook.
• Jmol in an Android tablet.
• Troubleshooting.

Jmol Application

"Jmol Application" is the version of Jmol that runs as a standalone program, in its own window. It uses the Java programming language.

Control of the molecular model is gained through several means:

1. The mouse (documented in Mouse Manual).
2. The application's menu and toolbar (at the top of the window), which offer
   1. File open, export, and print functionalities.
   2. A limited set of selection and rendering options, and several tools.
3. The pop-up menu (or context menu, opened by right-click or Ctrl+click on the model's panel), which offers most funcionality available and is identical to applet menu.
4. The scripting language (same used by the applet); this is available through the File > Script... menu, which opens a "script console" or command-line environment.

Installing Jmol Application

Installing Jmol / JSmol

• Get the files from SourceForge.
• Support and operating systems.
• Users: how to install Jmol application for local, standalone use.
• Web page authors: how to install Jmol objects (Jmol / JSmol) embedded within your web pages.
  • Installing and Enabling Java (Proteopedia wiki). Has step by step instructions for both Windows and Mac OS X, and for the 5 most popular web browsers.
  • Increasing java memory for the applet.
• Web site administrators:
  • How to install the application on a web server to be delivered using Java Web Start.
  • How to configure a wiki so that it uses the Jmol applet.
• Developers: compile the latest Jmol source code via subversion access.

Download the Jmol package (either .zip or tar.gz format) and extract/uncompress only the Jmol.jar file to the folder of your choice.

To open the application, follow these instructions:

Starting Jmol Application

Several ways:

• Double-click on Jmol.jar file.
• Click on a previously created shortcut (Windows terminology) (HowTo).
• Click on a previously created Start menu entry (Windows terminology) (HowTo).
• Execute one of the batch files/shell scripts that are part of Jmol distribution (Windows, MacOS, Linux, Unix).
• From the command line: java -jar Jmol.jar (of course, issued from the folder/directory where Jmol.jar is, or else pointing to it with a full path). See memory options below.
• Double-click on a molecular coordinates file whose extension has been previously associated to Jmol (HowTo).
• only for Macs, Fernanda Foertter has packed Jmol application into a clickable icon / .app type icon that opens up Jmol. This makes it look like a regular 'ol app without all of the exposed jar files. It is available at her site as a dmg file. Instructions: 1) download dmg file; 2) double-click to open; 3) drag Jmol icon to you Applications folder to install; 4) eject dmg; 5) trash dmg file; 6) double-click Jmol icon to open application, or 6a) click and drag to dock to have ready whenever needed.

If you have trouble running the application, see also Solving Java Problems.

Command line options

Basic options

• Show help for command-line options: use either of these:

java -jar Jmol.jar -h
java -jar Jmol.jar --help 

• Load a molecular file: use either of these:

Jmol.jar  fileName
java -jar Jmol.jar  fileName

• Run a script: use either of these:

Jmol.jar -s  script_fileName
Jmol.jar  script_fileName
java -jar Jmol.jar  script_fileName

• Set the window size: use either of these:

Jmol.jar -g  WIDTHxHEIGHT   
Jmol.jar --geometry  WIDTHxHEIGHT
java -jar Jmol.jar  -g  WIDTHxHEIGHT   

using lowercase 'x' and no spaces, e.g. Jmol.jar -g 500x250. By default, size is the last size used or else 500x500.

• Set the language to be used for the interface (default is language of the operating system) see also:

java -Duser.language=ca|cs|de|en|es|et|fr|nl|pt|tr  -jar Jmol.jar

• Report the display speed in either frames per second or milliseconds per frame (the default):

java -Ddisplay.speed=fps|ms  -jar Jmol.jar

• Set a path where to look for plugins for Jmol:

java -Dplugin.dir=/path/to/plugins  -jar Jmol.jar

• Set memory use (see below):

java -Xmxsize  -jar Jmol.jar

Giving Jmol more memory to work with

Memory available to Jmol is determined by Java. Less or more memory can be allocated by using:
java -Xmx###m -jar Jmol.jar
where the ### must be substituted by a number in megabytes (hence the "m" after it).

Technically:

• -Xmx sets the maximum memory heap size.
• -Xms sets the minimum memory heap size.

Batch files and shell scripts included with Jmol distribution are written to give -Xmx512m (512 MB maximum).

See also the procedure for the applet.

Advanced options (Jmol v.11)

Create a JVXL file directly:

 Jmol -ionx iso.spt myfile.xyz > myfile.jvxl

where:

• -i,--silent silent startup operation
• -o,--noconsole no console -- all output to sysout
• -n,--nodisplay no display (much faster)
• -x,--exit run script and exit

and iso.spt is:

   isosurface solvent;show isosurface

creates a JVXL solvent surface file.

Create a list of measurements:

 Jmol -ionx measure.spt myfile.xyz > measure.txt

where measure.spt is:

measure allconnected (*) (*);show measurements

generates a list of measurements.

measure.txt now contains (tab-separated):

Measurement Information

distance 1.1217928 0.112 nm H 1 #1 C 10 #10

distance 1.4158994 0.142 nm N 2 #2 C 6 #6

distance 1.3865448 0.139 nm N 2 #2 C 7 #7

...

Check CIF file symmetry:

 Jmol -ionx symmetry.spt myfile.cif > symmetry.txt

where symmetry.spt is:

   show unitcell;show symmetry;show spacegroup;

Anything that can be "shown" can be dumped to a file this way. And anything you can get from getProperty will do the same.

Forcing Jmol to open in a certain language

Jmol includes several languages (technically called localizations) for the user interface (top menu and pop-up menu). Jmol will open by default with the interface using the language of your operating system (ref.). However, if you need to change this:

1. Starting Jmol 11.1.30, the language in application can be switched anytime, from the pop-up menu, "Language" item near the bottom.
2. Or, using the scripting language: language = "de" (you must use the keyword "language" and the two-letter language code: ca, cs, de, en, es, et, fr, nl, pt, tr)
3. This is an old method, only needed for versions below 11.1.30: If you want to force a certain language, you must start Jmol with

java -Duser.language=es -jar Jmol.jar # forces Spanish (Español)

java -Duser.language=de -jar Jmol.jar # forces German (Deutsch)

java -Duser.language=en -jar Jmol.jar # forces English

etc.

See also the procedure for the applet.

Contributors

AngelHerraez, EricMartz, Pimpim, Cudo29, NicolasVervelle, Green