<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>
- Jalview sometimes runs out of memory. This is because of the way
- that Java runs on a computer - what is actually run is a program
- called a virtual machine (the JVM) which executes the java
- 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> The way
- you increase the memory settings for the JVM depends on which
- installation of Jalview you use:
+ <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">Web Start Version</font></em>
- <p>
- JavaWS sets the JVM parameters through special tags in the JNLP
- file. You can obtain a JNLP file with modified memory settings
- from our service with the following link (replace 2G with
- desired memory in G or M):<br /> <a
- href="http://www.jalview.org/services/launchApp?jvm-max-heap=2G">http://www.jalview.org/services/launchApp?jvm-max-heap=2G</a>
- </p>
- <p>
- Alternatively, if you want to create your own JNLP file then
- please download the latest JNLP file from <a
- href="http://www.jalview.org/webstart/jalview.jnlp">http://www.jalview.org/webstart/jalview.jnlp</a>
- and modify the max-heap-size parameter for the j2se tag in the
- <resources> element. e.g.
- <pre>
-<j2se version="1.7+" initial-heap-size="500M" max-heap-size="1000M"/>
-</pre> In both cases, you should save your new jnlp file somewhere and then
- either point your web browser at the file's url, launch it from
- your file browser, or from a terminal window run javaws (located
- in your Java installation's bin directory) with the file location
- as its argument. The file's url is something like :<br> <pre>
-file://<full path to file>
-</pre> If Jalview doesn't start up, see <a href="#memsetting">below</a>.
- You'll have to edit the above settings in the JNLP file using a
- text editor, save it, and try starting Jalview with it once more.
- </p></li>
- <li><em><font size="3">Install Anywhere version</font></em>
- <p>You need to change the InstallAnywhere configuration
- settings for the application. These are found in different
- places depending upon which operating system you have :
+ <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 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
+ 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"><a name="jar">Command line arguments when using the executable jar (jalview-all.jar)</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),
+ then you can set the <em>jvmmempc</em> and <em>jvmmemmax</em> values using application command line arguments <em>-jvmmempc=N</em>
+ and <em>-jvmmemmax=M</em> respectively, 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/><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>Unix/Windows</em>
- <p>Take a look inside the Jalview program installation
- directory (this might be in C:\Program Files\Jalview on
- windows). You should find a file called 'Jalview.lax' in it
- - make a backup, and then add the following lines to the end
- of the original file :
- <pre>
-lax.nl.java.option.java.heap.size.max=1000m
-lax.nl.java.option.java.heap.size.initial=500m
-</pre> Case and (lack of) spaces are important here! Do not add any spaces
- after the m in each line, and do not put any spaces before
- 'lax'.<br> Also there MUST be a carriage return after the
- final line.
- <p></p></li>
- <li><em>Mac OSX</em>
- <p>
- The lines you need to change are in the <em>Info.plist</em>
- file inside the <em>Jalview.app/Contents</em> directory
- (which is where the installAnywhere installation was made) :
-
-
- <pre>
-<key&ht;VMOptions</key&ht;
-<array>
-! <string>-Xms2M</string>
-! <string>-Xmx64M</string>
-</array>
-</pre>Exchange the above two string tags for : <pre>
-<string>-Xms500M</string>
-<string>-Xmx1000M</string>
-</pre>
- <p></p></li>
- </ul>
- <li><font size="3"><em>In all cases</em></font><br> Save
- the file and try to start Jalview in the normal way. If it doesn't
- start, see below...</li>
+ <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>
- <p>
- <em>Please Note:</em> We do modify the default memory settings in
- Jalview from time to time, so you may find different numbers to
- those shown in the examples above.
- </p>
- <font size="3"><em>Jalview doesn't start... What do the
- memory settings mean ?<a name="memsetting"></a>
- </em></font>
- <p>The 1000m value corresponds to the maximum number of megabytes
- of space that java objects can occupy. The 500m is the initial heap
- size that java will run in - increasing this can speed up memory
- allocation if you know you will need 500 meg of memory to begin with
- (ie it should speed up loading large alignments).</p>
- <p>If, after setting the initial and maximum heap size to some
- large value, you cannot actually start Jalview, then the max and
- initial sizes are too big for your machine (there seems to be a
- physical limit related to physical RAM - email the usual address to
- enlighten us if you know better!). Our experiments found 1000m to be
- the biggest setting that could be used on a 1GB machine. Just try
- reducing the sizes until Jalview starts up properly!</p>
- <p>
- We increased the default memory in Jalview 2.10.5 to 1G. To launch
- Jalview with the pre 2.10.5 default memory allocation, use the <a
- href="http://www.jalview.org/webstart/jalview_256MB.jnlp">Jalview
- 256MB JNLP</a>.
- </p>
- <p> </p>
</body>
</html>
git://source.jalview.org / jalview.git / blobdiff