help/html/memory.html

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