<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. You may wish to change this behaviour -
+ particularly if you are working on a machine that runs other memory
+ intensive processes.
<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).
+ <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 looks like
- <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 files as arguments in the command line, 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>
-
-
- </p>
- </li>
-
-
- <li><em><font size="3"></font></em>
- <p>
- </p>
- </li>
-
-
-
-
- <li><em><font size="3"></font></em>
- <p>
- </p>
- </li>
-
-
-
-
- <li><em><font size="3"></font></em>
- <p>
- </p>
- </li>
-
-
-
-
- <li><em><font size="3"></font></em>
- <p>
- </p>
+ <li><em><font size="3">JVL file</font></em> <br /> 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 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"></font></em>
- <p>
- </p>
+ <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>) <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>
+ java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
+ </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>