Memory Settings

Memory Usage Settings for Jalview

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.

This behaviour might not be ideal if you are working on a machine that runs other memory intensive processes, and (since Jalview 2.11.2) can be changed via the Startup Preferences panel.

Signs that Jalview is Running out of Memory
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).

Jalview Memory Usage Monitor: If you are concerned about memory, or think that things might be behaving strangely because of a shortage of memory, then you can check this by enabling the memory usage monitor. This is done by selecting the Tools→Show Memory Usage option. Once enabled, the memory usage monitor displays the currently available memory, the total memory, and the percentage free at the bottom left hand side of the Jalview Desktop window's background.

Increasing the memory available to Jalview
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.

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:

Jalview's Startup Preferences panel
The easiest way to launch Jalview with a different percentage of physical memory available is to adjust your user preferences via the Startup Preferences panel.
jalview command line launch
When starting Jalview from a command line launch you can use the memory setting arguments --jvmmemmax=MAXMEMORY and --jvmmempc=PERCENT. MAXMEMORY should be an integer optionally followed by one of k, m, g, t. PERCENT should be an integer between 1 and 100.
JVL file
Another way to adjust launch settings is with a text file with extension .jvl and a single line to specify the percentage of memory you wish Jalview to request:
```
      jalview.jvmmempc=50
```
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.

In Linux or other unix variants you can launch Jalview on the command line and provide your JVL file as an argument with
```
      /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl
```
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 jvl file first, e.g.
```
      /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa
```
Alternatively, you can use the standard Jalview command line arguments with or without the jvl file (first), e.g.
```
       /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
```
You can use command line arguments to control memory settings in Windows and macOS too:
In Windows you must use, e.g.
```
      \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl --open %HOMEPATH%\myalignment.fa
```
In macOS you can use the macOS open command like this:
```
      open /Applications/Jalview.app --args ~/mymemorysetting.jvl --open ~/myalignment.fa
```
(put all the Jalview arguments after the --args parameter)
Maximum memory limit
Since 2.11.1.0, Jalview's configuration includes a 'maximum memory limit':
```
jalview.jvmmemmax = 32G
```
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.

Command line arguments when using the executable jar (jalview-all.jar) or jalview.bin.Launcher
If you are using the Jalview standalone executable jar (usually named jalview-all-....jar with a Jalview and Java version designation) or using jalview.bin.Launcher to start Jalview, then you can set the jvmmempc and jvmmemmax values using application command line arguments --jvmmempc=PERCENT and --jvmmemmax=MAXMEMORY respectively. PERCENT 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.

java -jar jalview-all-2.11.1.0-j1.8.jar --jvmmempc=50 --jvmmemmax=20g

(this example will launch Jalview with a maximum heap size of the smaller of 20GB or 50% of physical memory detected).
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.

Directly opening Jalview with a JVM
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.
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 -Xmx... JVM argument.
-Xmx 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.
For example:

      -Xmx8g

Jalview binaries for Windows and macOS are distributed with their own JVM which you will find in

Windows: .../Jalview/jre/bin/java.exe
macOS: .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java

For linux and other unixes you will have to install a Java 1.8 JRE (we recommend the ones found at https://adoptopenjdk.net/)

You will also need to reference the "appdir" release folder with all of the Jalview jar files.

On Windows this will be
```
\PATH_TO_JALVIEW\release
```

On macOS it will be

/Applications/Jalview.app/Contents/Resources/app/release

and on linux or unix

/PATH_TO_JALVIEW/release

Assuming the java (or java.exe on Windows) commands are available to you, you can run, e.g.

      java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview

Or on Windows

      java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview

Note: for this to work the classpath argument wildcard must be simply a '*' and not '*.jar'.

You can also add other Jalview command line arguments as above after the jalview.bin.Jalview class name, but you cannot use jvl files if launching Jalview in this way.