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. You may wish to change this behaviour -
  34     particularly if you are working on a machine that runs other memory
  35     intensive processes.
  36   <p>
  37     <em>Signs that Jalview is Running out of Memory</em><br /> If
  38     Jalview has not explicitly told you that it has run out of memory,
  39     then a common sign is that a function that normally works seems to
  40     have no effect when working with a larger set of sequences (this
  41     might include open dialog boxes for saving PNG files, or when
  42     interpreting the result 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
  56     amount of memory allocated is defined wheb Jalview is launched
  57     because of the way that Java runs on a computer - what is actually
  58     run is a program called a Java virtual machine (a JVM) which
  59     executes the java program instructions. The JVM has limits on the
  60     memory that can be allocated to the java program - and it is often
  61     necessary to adjust them if you are working with particularly large
  62     datasets, or need to make room for other processes on the machine.<br />
  63     <br />Jalview 2.11 includes a launcher that automatically
  64     configures the proportion of memory allocated to Jalview's JVM, and
  65     its behaviour can be altered in a number of different ways:
  66   </p>
  67
  68   <ul>
  69     <li><em><font size="3">JVL file</font></em> <br /> The easiest
  70       way to launch Jalview with a different percentage of physical
  71       memory available is to create a text file with extension <em>.jvl</em>
  72       and a single line to specify the percentage of memory you wish
  73       Jalview to request: <pre>
  74       jalview.jvmmempc=50</pre> In Windows and in macOS you can then launch Jalview by
  75       double clicking on this file, and your memory setting will be used
  76       instead of the default value. <br /> <br /> In Linux or other
  77       unix variants you can launch Jalview on the command line and
  78       provide your JVL file as an argument with <pre>
  79       /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl</pre> If you want to use a memory setting like this and open a
  80       file you can use both the jvl and alignment files as command line
  81       arguments, but you must put the <em>jvl</em> file first, e.g. <pre>
  82       /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa</pre> Alternatively, you can use the standard Jalview command line
  83       arguments with or without the jvl file (first), e.g. <pre>
  84        /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl -open http://www.jalview.org/examples/jpred_msa.fasta -annotations http://www.jalview.org/examples/jpred_msa.seq.concise -colour Clustal</pre> You can use command line arguments to control memory
  85       settings in Windows and macOS too: <br /> In Windows you must
  86       use, e.g. <pre>
  87       \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl -open %HOMEPATH%\myalignment.fa</pre> In macOS you can use the macOS <em>open</em> command like this: <pre>
  88       open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa</pre><em>(put all the Jalview arguments <em>after</em> the --args
  89         parameter)
  90     </em><br/><br/></li>
  91     <li><em><font size="3"><a name="jvm"/>Directly opening Jalview
  92           with a JVM</font></em> <br /> Launching Jalview directly with a JVM is
  93       entirely possible, but is not recommended for regular interactive
  94       use because it bypasses Jalview's launcher which also handles
  95       automatic updates and configuration of other aspects of Jalview
  96       operation. <br /> However by launching Jalview in this way you
  97       have full access to the Java command line arguments. In particular
  98       you can set the maximum allowed memory with the <em>-Xmx...</em>
  99       JVM argument. <br /> <em>-Xmx</em> should be immediately followed
 100       (no space or equals) by the maximum amount of memory specified in
 101       bytes, or in kilobytes, megabytes or gigabytes by following the
 102       number with a "k", "m" or "g" respectively. <br />For example: <pre>
 103       -Xmx8g</pre>Jalview binaries for Windows and macOS are distributed
 104       with their own JVM which you will find in
 105       <ul>
 106         <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
 107         <li><em>macOS:</em>
 108           .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
 109       </ul> For linux and other unixes you will have to install a Java 1.8
 110       JRE (we recommend the ones found at <a
 111       href="https://adoptopenjdk.net">https://adoptopenjdk.net/</a>) <br />
 112       <br /> You will also need to reference the "appdir" release
 113       folder with all of the Jalview jar files.
 114       <ul>
 115         <li>On Windows this will be <pre>\PATH_TO_JALVIEW\release</pre>
 116         </li>
 117         <li>On macOS it will be <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
 118           and on linux or unix <pre>/PATH_TO_JALVIEW/release</pre>
 119         </li>
 120       </ul> Assuming the <em>java</em> (or <em>java.exe</em> on Windows)
 121       commands are available to you, you can run, e.g. <pre>
 122       java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
 123       </pre> Or on Windows <pre>
 124       java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
 125       </pre> <em>Note:</em> for this to work the classpath argument wildcard <strong>must</strong> be simply
 126       a '*' and not '*.jar'. <br /> <br />
 127       You can also add other <a href="features/commandline.html">Jalview
 128         command line arguments</a> as above after the <em>jalview.bin.Jalview</em>
 129       class name, but <strong>you cannot use <em>jvl</em> files
 130     </strong> if launching Jalview in this way.</li>
 131   </ul>
 132 </body>
 133 </html>