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>
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
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→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
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.
67 <li><em><font size="3">JVL file</font></em>
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
74 Replace the value with the percentage of memory you wish to allocate to Jalview.
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.
80 In Linux or other unix variants you can launch Jalview on the command line and provide your JVL file as an argument with
82 /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl
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.
89 /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa
91 alternatively, you can use the standard Jalview command line arguments with or without the jvl file (first), e.g.
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
98 You can use command line arguments to control memory settings in Windows and macOS too:
100 In Windows you must use, e.g.
102 \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl -open %HOMEPATH%\myalignment.fa
104 and in macOS you can use the macOS <em>open</em> command like this:
106 open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa
108 (put all the Jalview arguments <em>after</em> the --args parameter).
114 <li><em><font size="3">Directly opening Jalview with a JVM</font></em>
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.
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.
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.
129 Jalview binaries for Windows and macOS are distributed with their own JVM which you will find in
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>
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>)
137 You will also need to reference the "appdir" release folder with all of the Jalview jar files.
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>
144 <pre>/PATH_TO_JALVIEW/release</pre>
147 Assuming the <em>java</em> (or <em>java.exe</em> on Windows) commands are available to you, you can run, e.g.
149 java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
153 java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
155 <em>Note</em> that the classpath argument wildcard must be simply a '*' and not '*.jar'. This is a limitation of Java.
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).