<strong>Memory Usage Settings for Jalview</strong>
</center>
</h2>
+ <p>When launched as an Application, Jalview will automatically
+ configure the amount of memory allocated to the program to be 90% of
+ physical memory, or 32GB - which ever is smaller.</p>
<p>
- When launched as an Application, Jalview automatically tries to
- maximise the amount of memory allocated to it (default settings are
- to try and use up to 90% of physical memory available to it).
- Sometimes it may require more memory, or if you are working in a
- shared memory environment you may want to limit the maximum amount
- of memory that it might use.
- This has to be set at the time Jalview is launched because of the way
- that Java runs on a computer - what is actually run is a program called
- a Java virtual machine (a JVM) which executes the java program instructions.
- The JVM has limits on the memory that can be allocated to the java program - and
- you might need to increase them if you are working with particularly
- large datasets.<br> If Jalview has not explicitly told you that
- it has run out of memory, then a common sign is that a function that
- normally works seems to have no effect when working with a larger
- set of sequences (this might include open dialog boxes for saving
- PNG files, or when interpreting the result of a web service
- calculation).
+ This behaviour might not be ideal if you are working on a machine
+ that runs other memory intensive processes, and (<em>since
+ Jalview 2.11.2</em>) can be changed via the <a
+ ref="preferences.html#startup">Startup Preferences</a> panel.
+ </p>
+ <p>
+ <em>Signs that Jalview is Running out of Memory</em><br /> If
+ Jalview has not explicitly told you that it has run out of memory,
+ then a common sign is that a function that normally works seems to
+ have no effect when working with a larger set of sequences (this
+ might include open dialog boxes for saving PNG files, or when
+ interpreting the result of a web service calculation).
</p>
<p>
<em>Jalview Memory Usage Monitor</em>: If you are concerned about
window's background.
</p>
<p>
- <em>Increasing the memory available to Jalview</em><br/>
- 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.
- 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.
+ <em>Increasing the memory available to Jalview</em><br /> The
+ amount of memory allocated is defined wheb Jalview is launched
+ because of the way that Java runs on a computer - what is actually
+ run is a program called a Java virtual machine (a JVM) which
+ executes the java program instructions. The JVM has limits on the
+ memory that can be allocated to the java program - and it is often
+ necessary to adjust them if you are working with particularly large
+ datasets, or need to make room for other processes on the machine.<br />
+ <br />Jalview 2.11 includes a launcher that automatically
+ 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:
</p>
<ul>
- <li><em><font size="3">JVL file</font></em>
- <p>
- The easiest way to launch Jalview with a different percentage of physical memory available is to
- create a text file with extension <em>.jvl</em> and with content that contains the line
- <pre>
- jalview.jvmmempc=50
- </pre>
- Replace the value with the percentage of memory you wish to allocate to Jalview.
- </p>
- <p>
- 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.
- </p>
- <p>
- In Linux or other unix variants you can launch Jalview on the command line and provide your JVL file as an argument with
- <pre>
- /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl
- </pre>
-
- </p>
- <p>
- 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.
- <pre>
- /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa
- </pre>
- alternatively, you can use the standard Jalview command line arguments with or without the jvl file (first), e.g.
- <pre>
- /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>
- </p>
-
- <p>
- You can use command line arguments to control memory settings in Windows and macOS too:
- <br/>
- In Windows you must use, e.g.
- <pre>
- \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl -open %HOMEPATH%\myalignment.fa
- </pre>
- and in macOS you can use the macOS <em>open</em> command like this:
- <pre>
- open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa
- </pre>
- (put all the Jalview arguments <em>after</em> the --args parameter).
-
- </p>
+ <li><em><font size="3">Jalview's Startup
+ Preferences panel</font></em> <br /> The easiest way to launch Jalview
+ with a different percentage of physical memory available is to
+ adjust your user preferences via the <a
+ ref="preferences.html#startup">Startup Preferences</a> panel.</li>
+ <li><em><font size="3">JVL file</font></em> <br />Another way
+ to adjust launch settings is with a text file with extension <em>.jvl</em>
+ and a single line to specify the percentage of memory you wish
+ Jalview to request: <pre>
+ jalview.jvmmempc=50</pre> 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. <br /> <br /> In
+ Linux or other unix variants you can launch Jalview on the command
+ line and provide your JVL file as an argument with <pre>
+ /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl</pre> 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. <pre>
+ /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa</pre>
+ Alternatively, you can use the standard Jalview command line
+ arguments with or without the jvl file (first), e.g. <pre>
+ /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>
+ You can use command line arguments to control memory settings in
+ Windows and macOS too: <br /> In Windows you must use, e.g. <pre>
+ \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>
+ open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa</pre><em>(put
+ all the Jalview arguments <em>after</em> the --args parameter)
+ </em><br />
+ <br /></li>
+ <li><em><font size="3">Maximum memory limit</em><br/>
+ Since 2.11.1.0, Jalview's configuration includes a 'maximum memory limit':
+ <pre>jalview.jvmmemmax = 32G</pre>
+ 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.
+ <br/><br/>
</li>
-
-
- <li><em><font size="3">Directly opening Jalview with a JVM</font></em>
- <p>
- Launching Jalview directly with a JVM is entirely possible, but is not recommended as automatic updates and some other default settings will not operate.
- </p>
- <p>
- However by launching Jalview in this way you have full access to the Java command line arguments.
- In particular you can set the maximum allowed memory with the <em>-Xmx...</em> JVM argument.
- <br/>
- <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,
- or in kilobytes, megabytes or gigabytes by following the number with a "k", "m" or "g" respectively. e.g.
- <pre>
- -Xmx8g
- </pre>
- </p>
- <p>
- Jalview binaries for Windows and macOS are distributed with their own JVM which you will find in
+ <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/>
+ 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,
+ then you can set the <em>jvmmempc</em> and <em>jvmmemmax</em> values using application command line arguments <em>-jvmmempc=PERCENT</em>
+ 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.
+ <pre>java -jar jalview-all-2.11.1.0-j1.8.jar -jvmmempc=50 -jvmmemmax=20g</pre>
+ (this example will launch Jalview with a maximum heap size of the smaller of 20GB or 50% of physical memory detected).
+ <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.
+ <br/><br/>
+ </li>
+ <li><em><font size="3"><a name="jvm"/>Directly opening Jalview
+ with a JVM</font></em> <br /> Launching Jalview directly with a JVM is
+ entirely possible, but is not recommended for regular interactive
+ use because it bypasses Jalview's launcher which also handles
+ automatic updates and configuration of other aspects of Jalview
+ operation. <br /> However by launching Jalview in this way you
+ have full access to the Java command line arguments. In particular
+ you can set the maximum allowed memory with the <em>-Xmx...</em>
+ JVM argument. <br /> <em>-Xmx</em> should be immediately followed
+ (no space or equals) by the maximum amount of memory specified in
+ bytes, or in kilobytes, megabytes or gigabytes by following the
+ number with a "k", "m" or "g" respectively. <br />For example: <pre>
+ -Xmx8g</pre>Jalview binaries for Windows and macOS are distributed
+ with their own JVM which you will find in
<ul>
- <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
- <li><em>macOS:</em> .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
- </ul>
- 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>)
- </p>
- <p>
- You will also need to reference the "appdir" release folder with all of the Jalview jar files.
- <br/>
- On Windows this will be
- <pre>\PATH_TO_JALVIEW\release</pre>
- whereas on macOS it will be
- <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
- and on linux or unix
- <pre>/PATH_TO_JALVIEW/release</pre>
- </p>
- <p>
- Assuming the <em>java</em> (or <em>java.exe</em> on Windows) commands are available to you, you can run, e.g.
- <pre>
+ <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
+ <li><em>macOS:</em>
+ .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
+ </ul> 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>) <br />
+ <br /> You will also need to reference the "appdir" release
+ folder with all of the Jalview jar files.
+ <ul>
+ <li>On Windows this will be <pre>\PATH_TO_JALVIEW\release</pre>
+ </li>
+ <li>On macOS it will be <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
+ and on linux or unix <pre>/PATH_TO_JALVIEW/release</pre>
+ </li>
+ </ul> Assuming the <em>java</em> (or <em>java.exe</em> on Windows)
+ commands are available to you, you can run, e.g. <pre>
java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
- </pre>
- or on Windows
- <pre>
+ </pre> Or on Windows <pre>
java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
- </pre>
- <em>Note</em> that the classpath argument wildcard must be simply a '*' and not '*.jar'. This is a limitation of Java.
- </p>
- <p>
- 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).
- </li>
-
-
+ </pre> <em>Note:</em> for this to work the classpath argument wildcard <strong>must</strong> be simply
+ a '*' and not '*.jar'. <br /> <br />
+ You can also add other <a href="features/commandline.html">Jalview
+ command line arguments</a> as above after the <em>jalview.bin.Jalview</em>
+ class name, but <strong>you cannot use <em>jvl</em> files
+ </strong> if launching Jalview in this way.</li>
</ul>
-
</body>
</html>