help/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>When launched as an Application, Jalview will automatically
  32     configure the amount of memory allocated to the program to be 90% of
  33     physical memory, or 32GB - which ever is smaller.</p>
  34   <p>
  35     This behaviour might not be ideal if you are working on a machine
  36     that runs other memory intensive processes, and (<em>since
  37       Jalview 2.11.2</em>) can be changed via the <a
  38       ref="preferences.html#startup">Startup Preferences</a> panel.
  39   </p>
  40   <p>
  41     <em>Signs that Jalview is Running out of Memory</em><br /> If
  42     Jalview has not explicitly told you that it has run out of memory,
  43     then a common sign is that a function that normally works seems to
  44     have no effect when working with a larger set of sequences (this
  45     might include open dialog boxes for saving PNG files, or when
  46     interpreting the result of a web service calculation).
  47   </p>
  48   <p>
  49     <em>Jalview Memory Usage Monitor</em>: If you are concerned about
  50     memory, or think that things might be behaving strangely because of
  51     a shortage of memory, then you can check this by enabling the memory
  52     usage monitor. This is done by selecting the <strong>Tools&#8594;Show
  53       Memory Usage</strong> option. Once enabled, the memory usage monitor
  54     displays the currently available memory, the total memory, and the
  55     percentage free at the bottom left hand side of the Jalview Desktop
  56     window's background.
  57   </p>
  58   <p>
  59     <em>Increasing the memory available to Jalview</em><br /> The
  60     amount of memory allocated is defined wheb Jalview is launched
  61     because of the way that Java runs on a computer - what is actually
  62     run is a program called a Java virtual machine (a JVM) which
  63     executes the java program instructions. The JVM has limits on the
  64     memory that can be allocated to the java program - and it is often
  65     necessary to adjust them if you are working with particularly large
  66     datasets, or need to make room for other processes on the machine.<br />
  67     <br />Jalview 2.11 includes a launcher that automatically
  68     configures the proportion of memory allocated to Jalview's JVM. By default it requests up to 90% of available memory whilst ensuring that at least 0.5G is available to the operating system and at least 0.5G is available to the Java runtime platform, or a specified 'maximum memory limit' - which ever is smaller. The amount of memory requested can be altered in a number of different ways:
  69   </p>
  70
  71   <ul>
  72     <li><em><font size="3">Jalview's Startup
  73           Preferences panel</font></em> <br /> The easiest way to launch Jalview
  74       with a different percentage of physical memory available is to
  75       adjust your user preferences via the <a
  76       ref="preferences.html#startup">Startup Preferences</a> panel.</li>
  77     <li>
  78       <em><code>jalview</code> command line launch</em>
  79       <br/>
  80       When starting Jalview from a <a href="features/commandline.html">command line launch</a> you can use the memory setting arguments <a href="features/clarguments.html#jvmmemmax"><code>--jvmmemmax=MAXMEMORY</code></a> and <a href="features/clarguments.html#jvmmempc"><code>--jvmmempc=PERCENT</code></a>.  <code>MAXMEMORY</code> should be an integer optionally followed by one of <code>k</code>, <code>m</code>, <code>g</code>, <code>t</code>.  <code>PERCENT</code> should be an integer between 1 and 100.
  81     </li>
  82     <li><em><font size="3">JVL file</font></em> <br />Another way
  83       to adjust launch settings is with a text file with extension <em>.jvl</em>
  84       and a single line to specify the percentage of memory you wish
  85       Jalview to request: <pre>
  86       jalview.jvmmempc=50</pre> In Windows and in macOS you can then launch
  87       Jalview by double clicking on this file, and your memory setting
  88       will be used instead of the default value. <br /> <br /> In
  89       Linux or other unix variants you can launch Jalview on the command
  90       line and provide your JVL file as an argument with <pre>
  91       /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl</pre> If you
  92       want to use a memory setting like this and open a file you can use
  93       both the jvl and alignment files as command line arguments, but
  94       you must put the <em>jvl</em> file first, e.g. <pre>
  95       /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa</pre>
  96       Alternatively, you can use the standard Jalview command line
  97       arguments with or without the jvl file (first), e.g. <pre>
  98        /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl --open https://www.jalview.org/examples/jpred_msa.fasta --annotations https://www.jalview.org/examples/jpred_msa.seq.concise --colour Clustal</pre>
  99       You can use command line arguments to control memory settings in
 100       Windows and macOS too: <br /> In Windows you must use, e.g. <pre>
 101       \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl --open %HOMEPATH%\myalignment.fa</pre>
 102       In macOS you can use the macOS <em>open</em> command like this: <pre>
 103       open /Applications/Jalview.app --args ~/mymemorysetting.jvl --open ~/myalignment.fa</pre><em>(put
 104         all the Jalview arguments <em>after</em> the --args parameter)
 105     </em><br />
 106     <br /></li>
 107     <li><em><font size="3">Maximum memory limit</em><br/>
 108       Since 2.11.1.0, Jalview's configuration includes a 'maximum memory limit':
 109       <pre>jalview.jvmmemmax = 32G</pre>
 110       Adjusting this default (via a JVL file, above) will allow larger amounts (or can limit the amount) of memory to be allocated to Jalview in conjunction with the jalview.jvmmempc setting.
 111       <br/><br/>
 112     </li>
 113     <li><em><font size="3"><a name="jar">Command line arguments when using the executable jar (jalview-all.jar) or jalview.bin.Launcher</a></em><br/>
 114       If you are using the Jalview standalone executable jar (usually named <em>jalview-all-....jar</em> with a Jalview and Java version designation) or using <em>jalview.bin.Launcher</em> to start Jalview,
 115       then you can set the <em>jvmmempc</em> and <em>jvmmemmax</em> values using application command line arguments <em>--jvmmempc=PERCENT</em>
 116       and <em>--jvmmemmax=MAXMEMORY</em> respectively.  <em>PERCENT</em> should be an integer between 1 and 100, and MAXMEMORY should be an amount of memory in bytes, or you can append a "k", "m", "g", or "t" to use units of kilobytes, megabytes, gigabytes or terabytes, e.g.
 117       <pre>java -jar jalview-all-2.11.1.0-j1.8.jar --jvmmempc=50 --jvmmemmax=20g</pre>
 118       (this example will launch Jalview with a maximum heap size of the smaller of 20GB or 50% of physical memory detected).
 119       <br/>The default value for jvmmempc is 90, whilst the default value for jvmmemmax is 32g if Jalview can determine a total physical memory size of the host system, and a more cautious 8g if Jalview is unable to determine a total physical memory size.
 120       <br/><br/>
 121     </li>
 122     <li><em><font size="3"><a name="jvm"/>Directly opening Jalview
 123           with a JVM</font></em> <br /> Launching Jalview directly with a JVM is
 124       entirely possible, but is not recommended for regular interactive
 125       use because it bypasses Jalview's launcher which also handles
 126       automatic updates and configuration of other aspects of Jalview
 127       operation. <br /> However by launching Jalview in this way you
 128       have full access to the Java command line arguments. In particular
 129       you can set the maximum allowed memory with the <em>-Xmx...</em>
 130       JVM argument. <br /> <em>-Xmx</em> should be immediately followed
 131       (no space or equals) by the maximum amount of memory specified in
 132       bytes, or in kilobytes, megabytes or gigabytes by following the
 133       number with a "k", "m" or "g" respectively. <br />For example: <pre>
 134       -Xmx8g</pre>Jalview binaries for Windows and macOS are distributed
 135       with their own JVM which you will find in
 136       <ul>
 137         <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
 138         <li><em>macOS:</em>
 139           .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
 140       </ul> For linux and other unixes you will have to install a Java 1.8
 141       JRE (we recommend the ones found at <a
 142       href="https://adoptopenjdk.net">https://adoptopenjdk.net/</a>) <br />
 143       <br /> You will also need to reference the "appdir" release
 144       folder with all of the Jalview jar files.
 145       <ul>
 146         <li>On Windows this will be <pre>\PATH_TO_JALVIEW\release</pre>
 147         </li>
 148         <li>On macOS it will be <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
 149           and on linux or unix <pre>/PATH_TO_JALVIEW/release</pre>
 150         </li>
 151       </ul> Assuming the <em>java</em> (or <em>java.exe</em> on Windows)
 152       commands are available to you, you can run, e.g. <pre>
 153       java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
 154       </pre> Or on Windows <pre>
 155       java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
 156       </pre> <em>Note:</em> for this to work the classpath argument wildcard <strong>must</strong> be simply
 157       a '*' and not '*.jar'. <br /> <br />
 158       You can also add other <a href="features/commandline.html">Jalview
 159         command line arguments</a> as above after the <em>jalview.bin.Jalview</em>
 160       class name, but <strong>you cannot use <em>jvl</em> files
 161     </strong> if launching Jalview in this way.</li>
 162   </ul>
 163 </body>
 164 </html>