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>
  32     When launched as an Application, Jalview automatically tries to
  33     maximise the amount of memory allocated to it (default settings are
  34     to try and use up to 90% of physical memory available to it).
  35     Sometimes it may require more memory, or if you are working in a
  36     shared memory environment you may want to limit the maximum amount
  37     of memory that it might use.
  38     This has to be set at the time Jalview is launched because of the way
  39     that Java runs on a computer - what is actually run is a program called
  40     a Java virtual machine (a JVM) which executes the java program instructions.
  41     The JVM has limits on the memory that can be allocated to the java program - and
  42     you might need to increase them if you are working with particularly
  43     large datasets.<br> If Jalview has not explicitly told you that
  44     it has run out of memory, then a common sign is that a function that
  45     normally works seems to have no effect when working with a larger
  46     set of sequences (this might include open dialog boxes for saving
  47     PNG files, or when interpreting the result of a web service
  48     calculation).
  49   </p>
  50   <p>
  51     <em>Jalview Memory Usage Monitor</em>: If you are concerned about
  52     memory, or think that things might be behaving strangely because of
  53     a shortage of memory, then you can check this by enabling the memory
  54     usage monitor. This is done by selecting the <strong>Tools&#8594;Show
  55       Memory Usage</strong> option. Once enabled, the memory usage monitor
  56     displays the currently available memory, the total memory, and the
  57     percentage free at the bottom left hand side of the Jalview Desktop
  58     window's background.
  59   </p>
  60   <p>
  61     <em>Increasing the memory available to Jalview</em><br/>
  62     Since Jalview 2.11, the program automatically configures the JVM memory settings to set the maximum memory available to Jalview to be 90% of physical memory.
  63     This default setting can be altered in a number of different ways, depending on how you prefer to launch Jalview and how specific you want to be with the maximum memory setting.
  64   </p>
  65
  66   <ul>
  67     <li><em><font size="3">JVL file</font></em>
  68       <p>
  69       The easiest way to launch Jalview with a different percentage of physical memory available is to
  70       create a text file with extension <em>.jvl</em> and with content that contains the line
  71       <pre>
  72       jalview.jvmmempc=50
  73       </pre>
  74       Replace the value with the percentage of memory you wish to allocate to Jalview.
  75       </p>
  76       <p>
  77       In Windows and in macOS you can then launch Jalview by double clicking on this file, and your memory setting will be used instead of the default value of 90.
  78       </p>
  79       <p>
  80       In Linux or other unix variants you can launch Jalview on the command line and provide your JVL file as an argument with
  81       <pre>
  82       /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl
  83       </pre>
  84
  85       </p>
  86       <p>
  87       If you want to use a memory setting like this and open a file you can use both the jvl and alignment files as command line arguments, but you must put the <em>jvl</em> file first, e.g.
  88       <pre>
  89       /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa
  90       </pre>
  91       alternatively, you can use the standard Jalview command line arguments with or without the jvl file (first), e.g.
  92       <pre>
  93        /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
  94       </pre>
  95       </p>
  96
  97       <p>
  98       You can use command line arguments to control memory settings in Windows and macOS too:
  99       <br/>
 100       In Windows you must use, e.g.
 101       <pre>
 102       \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl -open %HOMEPATH%\myalignment.fa
 103       </pre>
 104       and in macOS you can use the macOS <em>open</em> command like this:
 105       <pre>
 106       open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa
 107       </pre>
 108       (put all the Jalview arguments <em>after</em> the --args parameter).
 109
 110       </p>
 111     </li>
 112
 113
 114     <li><em><font size="3">Directly opening Jalview with a JVM</font></em>
 115       <p>
 116       Launching Jalview directly with a JVM is entirely possible, but is not recommended as automatic updates and some other default settings will not operate.
 117       </p>
 118       <p>
 119       However by launching Jalview in this way you have full access to the Java command line arguments.
 120       In particular you can set the maximum allowed memory with the <em>-Xmx...</em>  JVM argument.
 121       <br/>
 122       <em>-Xmx</em> should be immediately followed (no space or equals) by the maximum amount of memory that you might want to launch Jalview with.  This can be specified in bytes as just a number,
 123       or in kilobytes, megabytes or gigabytes by following the number with a "k", "m" or "g" respectively.  e.g.
 124       <pre>
 125       -Xmx8g
 126       </pre>
 127       </p>
 128       <p>
 129       Jalview binaries for Windows and macOS are distributed with their own JVM which you will find in
 130       <ul>
 131       <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
 132       <li><em>macOS:</em> .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
 133       </ul>
 134       For linux and other unixes you will have to install a Java 1.8 JRE (we recommend the ones found at <a href="https://adoptopenjdk.net">https://adoptopenjdk.net/</a>)
 135       </p>
 136       <p>
 137       You will also need to reference the "appdir" release folder with all of the Jalview jar files.
 138       <br/>
 139       On Windows this will be
 140       <pre>\PATH_TO_JALVIEW\release</pre>
 141       whereas on macOS it will be
 142       <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
 143       and on linux or unix
 144       <pre>/PATH_TO_JALVIEW/release</pre>
 145       </p>
 146       <p>
 147       Assuming the <em>java</em> (or <em>java.exe</em> on Windows) commands are available to you, you can run, e.g.
 148       <pre>
 149       java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
 150       </pre>
 151       or on Windows
 152       <pre>
 153       java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
 154       </pre>
 155       <em>Note</em> that the classpath argument wildcard must be simply a '*' and not '*.jar'. This is a limitation of Java.
 156       </p>
 157       <p>
 158       You can also add other Jalview command line arguments as above after the <em>jalview.bin.Jalview</em> class name (you cannot use <em>jvl</em> files if launching Jalview in this way).
 159     </li>
 160
 161
 162   </ul>
 163
 164 </body>
 165 </html>