3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
6 * This file is part of Jalview.
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.
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.
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.
23 <title>Memory Settings</title>
28 <strong>Memory Usage Settings for Jalview</strong>
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
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).
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→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
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. 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:
68 <li><em><font size="3">JVL file</font></em> <br /> The easiest
69 way to launch Jalview with a different percentage of physical
70 memory available is to create a text file with extension <em>.jvl</em>
71 and a single line to specify the percentage of memory you wish
72 Jalview to request: <pre>
73 jalview.jvmmempc=50</pre> In Windows and in macOS you can then launch Jalview by
74 double clicking on this file, and your memory setting will be used
75 instead of the default value. <br /> <br /> In Linux or other
76 unix variants you can launch Jalview on the command line and
77 provide your JVL file as an argument with <pre>
78 /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl</pre> If you want to use a memory setting like this and open a
79 file you can use both the jvl and alignment files as command line
80 arguments, but you must put the <em>jvl</em> file first, e.g. <pre>
81 /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa</pre> Alternatively, you can use the standard Jalview command line
82 arguments with or without the jvl file (first), e.g. <pre>
83 /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
84 settings in Windows and macOS too: <br /> In Windows you must
86 \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>
87 open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa</pre><em>(put all the Jalview arguments <em>after</em> the --args
90 <li><em><font size="3">Maximum memory limit</em><br/>
91 Since 2.11.1.0, Jalview's configuration includes a 'maximum memory limit':
92 <pre>jalview.jvmmemmax = 32G</pre>
93 Adjusting this default (via a JVL file, above) will allow larger amounts of memory to be allocated to Jalview in connjunction with the jalview.jvmmempc setting.
95 <li><em><font size="3"><a name="jvm"/>Directly opening Jalview
96 with a JVM</font></em> <br /> Launching Jalview directly with a JVM is
97 entirely possible, but is not recommended for regular interactive
98 use because it bypasses Jalview's launcher which also handles
99 automatic updates and configuration of other aspects of Jalview
100 operation. <br /> However by launching Jalview in this way you
101 have full access to the Java command line arguments. In particular
102 you can set the maximum allowed memory with the <em>-Xmx...</em>
103 JVM argument. <br /> <em>-Xmx</em> should be immediately followed
104 (no space or equals) by the maximum amount of memory specified in
105 bytes, or in kilobytes, megabytes or gigabytes by following the
106 number with a "k", "m" or "g" respectively. <br />For example: <pre>
107 -Xmx8g</pre>Jalview binaries for Windows and macOS are distributed
108 with their own JVM which you will find in
110 <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
112 .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
113 </ul> For linux and other unixes you will have to install a Java 1.8
114 JRE (we recommend the ones found at <a
115 href="https://adoptopenjdk.net">https://adoptopenjdk.net/</a>) <br />
116 <br /> You will also need to reference the "appdir" release
117 folder with all of the Jalview jar files.
119 <li>On Windows this will be <pre>\PATH_TO_JALVIEW\release</pre>
121 <li>On macOS it will be <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
122 and on linux or unix <pre>/PATH_TO_JALVIEW/release</pre>
124 </ul> Assuming the <em>java</em> (or <em>java.exe</em> on Windows)
125 commands are available to you, you can run, e.g. <pre>
126 java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
127 </pre> Or on Windows <pre>
128 java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
129 </pre> <em>Note:</em> for this to work the classpath argument wildcard <strong>must</strong> be simply
130 a '*' and not '*.jar'. <br /> <br />
131 You can also add other <a href="features/commandline.html">Jalview
132 command line arguments</a> as above after the <em>jalview.bin.Jalview</em>
133 class name, but <strong>you cannot use <em>jvl</em> files
134 </strong> if launching Jalview in this way.</li>