• Product manuals

Browse the manual

• Introduction
  • Deployment strategies
  • Java
  • System requirements
• Installation of Workbenches
  • Getting Workbench installers
  • What a Workbench installer does when launched
  • Installation modes - console and silent
  • Uninstalling a Workbench
• Licenses
  • Connecting to a CLC Network License Manager from Workbenches
• Workbench plugins
• Workflows
• Connecting to a CLC Server
• Security policies
• Storing and backing up data
  • Default Workbench data storage
  • Temporary data
  • Backup of Workbench information
  • Disk space requirements
• System resources
  • Setting the amount of memory available for the JVM
  • Setting the number of cores to use
• Overview - where do we put things?
  • Per-computer Workbench information
  • Per-user Workbench information

Setting the amount of memory available for the JVM

The Workbench Java Virtual Machine (JVM) needs to know how much memory it can use. The default value is 50% of the computer's RAM or 50GB, whichever is smaller. This is determined during Workbench installation. We recommend sticking with the default value for reasons described later in this chapter. However, it can be changed.

If you plan install Workbenches on multiple machines using an image, then either all the target computers should have the same amount of RAM, or the memory value specified should be set to 50% of the RAM on the computer with the smallest amount of memory.

Changing the memory setting for the Workbench JVM
The memory limit is configured in a property file by giving a numeric value and unit after the setting -Xmx. For example, this could look like:

-Xmx8000m

with 8000m indicating that the maximum amount of memory the Workbench java process is allowed to use is 8000Mb.

If a new memory limit is configured, it will be applied the next time the Workbench is started up.

The location of the relevant property file depends on the operating system being used:

Windows and Linux

The property file is called <workbenchname>.vmoptions, so for a CLC Main Workbench installation, this would be clcmainwb.vmoptions. It is found under the installation area of the Workbench. For example, on Windows, this would be a location like:
C:\Program Files\CLC Main Workbench 8\clcmainwb.vmoptions. Edit the -Xmx setting in this file.

macOS

The property file is called vmoptions.txt and can be found in the application bundle. Edit the -Xmx setting in this file.

To find this file in the application bundle, open a Finder window and navigate to the Workbench application. Right click on it, or click on it while holding the Ctrl key down (Ctrl + click), and choose "Show Package Contents" from the menu that appears. The vmoptions.txt is within the Contents folder^9.1.

If you prefer this sort of information to be configured within the Info.plist file, also available under the Contents folder. This can be done using the following steps:

1. Add the following line into the Info.plist file, under the 'VMOptionArray' section: -Xmx4100m, adjusting the numeric value to the amount of memory you want.
2. Remove the -Xmx setting from within the vmoptions.txt. If this is not done, this "-Xmx" value will overwrite the setting in the Info.plist. file.

Default memory setting recommendations explained

We suggest an upper limit of 50GB for the memory allocation because there are generally limited gains if the value is increased beyond this, and this limit helps ensure that the JVM does not spend too much time running garbage collection (GC) processes.

The GC is a memory handling subsystem of the JVM that scans through the currently used heap and frees up memory by removing contents no longer in use. The larger the maximum heap, which is what this memory setting is affecting, the longer each check through the heap will take. The JVM has to suspend all other activities while running the GC. These suspensions are normally on the scale of milliseconds to a few seconds, and in this range, they are generally not noticeable. In combination with the GC subystem of the JVM, the CLC Workbenches and Servers use a sophisticated caching system, moving unneeded data out of memory and into temporary disk storage. The result of this caching system means that there will not be any noticeable performance improvement with a Java heap space larger than 50GB, while GC pauses may become more noticeable.

The suggestion to limit memory use to a maximum of 50% of the physical RAM is made because most CLC Workbenches and CLC Servers have some optimized external binaries responsible for compute-heavy tasks such as read mapping and de novo assembly. These external binaries are not affected by the maximum heap space limit. They request memory from the OS, just like any other executable. Thus, the suggested 50% limit for the heap space setting for the Java Virtual Machine (JVM) is to try to ensure that the machine will have sufficient free memory to run the external binaries.

---

Footnotes

... folder^9.1

For releases before CLC Genomics Workbench 8.0, Biomedical Genomics Workbench 2.1 and CLC Main Workbench 7.6, the -Xmx setting for macOS was in the Info.plist file, which is also under the Contents folder.

---