help/html/memory.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3
  11  * of the License, or (at your option) any later version.
  12  *
  13  * Jalview is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty
  15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  * PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  * The Jalview Authors are detailed in the 'AUTHORS' file.
  21  -->
  22 <head>
  23 <title>Memory Settings</title>
  24 </head>
  25 <body>
  26   <h2>
  27     <center>
  28       <strong>Memory Usage Settings for Jalview</strong>
  29     </center>
  30   </h2>
  31   <p>
  32     Jalview sometimes runs out of memory. This is because of the way
  33     that Java runs on a computer - what is actually run is a program
  34     called a virtual machine (the JVM) which executes the java
  35     instructions. The JVM has limits on the memory that can be allocated
  36     to the java program - and you might need to increase them if you are
  37     working with particularly large datasets.<br> If Jalview has
  38     not explicitly told you that it has run out of memory, then a common
  39     sign is that a function that normally works seems to have no effect
  40     when working with a larger set of sequences (this might include open
  41     dialog boxes for saving PNG files, or when interpreting the result
  42     of a web service calculation).
  43   </p>
  44   <p>
  45     <em>Jalview Memory Usage Monitor</em>: If you are concerned about
  46     memory, or think that things might be behaving strangely because of
  47     a shortage of memory, then you can check this by enabling the memory
  48     usage monitor. This is done by selecting the <strong>Tools&#8594;Show
  49       Memory Usage</strong> option. Once enabled, the memory usage monitor
  50     displays the currently available memory, the total memory, and the
  51     percentage free at the bottom left hand side of the Jalview Desktop
  52     window's background.
  53   </p>
  54   <p>
  55     <em>Increasing the memory available to Jalview</em><br> The way
  56     you increase the memory settings for the JVM depends on which
  57     installation of Jalview you use:
  58   </p>
  59   <ul>
  60     <li><em><font size="3">Web Start Version</font></em>
  61       <p>
  62         JavaWS sets the JVM parameters through special tags in the JNLP
  63         file. You can obtain a JNLP file with modified memory settings
  64         from our service with the following link (replace 2G with
  65         desired memory in G or M):<br /> <a
  66           href="http://www.jalview.org/services/launchApp?jvm-max-heap=2G"
  67         >http://www.jalview.org/services/launchApp?jvm-max-heap=2G</a>
  68       </p>
  69       <p>
  70         Alternatively, if you want to create your own JNLP file then
  71         please download the latest JNLP file from <a
  72           href="http://www.jalview.org/webstart/jalview.jnlp"
  73         >http://www.jalview.org/webstart/jalview.jnlp</a> and modify the
  74         max-heap-size parameter for the j2se tag in the
  75         &lt;resources&gt; element. e.g.
  76       <pre>
  77 &lt;j2se version="1.7+" initial-heap-size="500M" max-heap-size="1000M"/&gt;
  78 </pre> In both cases, you should save your new jnlp file somewhere and then
  79       either point your web browser at the file's url, launch it from
  80       your file browser, or from a terminal window run javaws (located
  81       in your Java installation's bin directory) with the file location
  82       as its argument. The file's url is something like :<br> <pre>
  83 file://&lt;full path to file&gt;
  84 </pre> If Jalview doesn't start up, see <a href="#memsetting">below</a>.
  85       You'll have to edit the above settings in the JNLP file using a
  86       text editor, save it, and try starting Jalview with it once more.
  87       </p></li>
  88     <li><em><font size="3">Install Anywhere version</font></em>
  89       <p>You need to change the InstallAnywhere configuration
  90         settings for the application. These are found in different
  91         places depending upon which operating system you have :
  92       <ul>
  93         <li><em>Unix/Windows</em>
  94           <p>Take a look inside the Jalview program installation
  95             directory (this might be in C:\Program Files\Jalview on
  96             windows). You should find a file called 'Jalview.lax' in it
  97             - make a backup, and then add the following lines to the end
  98             of the original file :
  99           <pre>
 100 lax.nl.java.option.java.heap.size.max=1000m
 101 lax.nl.java.option.java.heap.size.initial=500m
 102 </pre> Case and (lack of) spaces are important here! Do not add any spaces
 103           after the m in each line, and do not put any spaces before
 104           'lax'.<br> Also there MUST be a carriage return after the
 105           final line.
 106           <p></p></li>
 107         <li><em>Mac OSX</em>
 108           <p>
 109             The lines you need to change are in the <em>Info.plist</em>
 110             file inside the <em>Jalview.app/Contents</em> directory
 111             (which is where the installAnywhere installation was made) :
 112
 113           <pre>
 114 &lt;key&ht;VMOptions&lt;/key&ht;
 115 &lt;array&gt;
 116 ! &lt;string&gt;-Xms2M&lt;/string&gt;
 117 ! &lt;string&gt;-Xmx64M&lt;/string&gt;
 118 &lt;/array&gt;
 119 </pre> Exchange the above two string tags for : <pre>
 120 &lt;string&gt;-Xms500M&lt;/string&gt;
 121 &lt;string&gt;-Xmx1000M&lt;/string&gt;
 122 </pre>
 123           <p></p></li>
 124       </ul>
 125     <li><font size="3"><em>In all cases</em></font><br> Save
 126       the file and try to start Jalview in the normal way. If it doesn't
 127       start, see below...</li>
 128   </ul>
 129   <font size="3"><em>Jalview doesn't start... What do the
 130       memory settings mean ?<a name="memsetting"></a>
 131   </em></font>
 132   <p>The 1000m value corresponds to the maximum number of megabytes
 133     of space that java objects can occupy. The 500m is the initial heap
 134     size that java will run in - increasing this can speed up memory
 135     allocation if you know you will need 500 meg of memory to begin with
 136     (ie it should speed up loading large alignments).</p>
 137   <p>If, after setting the initial and maximum heap size to some
 138     large value, you cannot actually start Jalview, then the max and
 139     initial sizes are too big for your machine (there seems to be a
 140     physical limit related to physical RAM - email the usual address to
 141     enlighten us if you know better!). Our experiments found 1000m to be
 142     the biggest setting that could be used on a 1GB machine. Just try
 143     reducing the sizes until Jalview starts up properly!</p>
 144   <p>&nbsp;</p>
 145 </body>
 146 </html>