##
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. You may wish to change this behaviour - particularly if you are working on a machine that runs other memory intensive processes.

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:

- JVL file
  The easiest way to launch Jalview with a different percentage of physical memory available is to create 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.