Memory Management

Each application, such as the VO DeskTop, TopCat, Aladin etc. has a default allocation of the memory on your computer. If you try to visualise very many or very large images in Aladin, for example, you may get 'Out of Memory' errors. Ideally this will show up in some friendly way such as a popup window explaining what has gone wrong, but you may just see something like

   java.lang.OutOfMemoryError

possibly accompanied by a long ugly stack trace in the window you started the program from. If you didn't start it from a window, you might not even see the error message, but just notice that things aren't working properly :-(.

The other possibility is that the program may try to use too much memory. Some applications which expect to have large requirements are started up by scripts which allocate, for instance, 512Mbyte by default. If your machine has less physical memory than that, or less free memory because other applications are making heavy use of resources, then you may experience problems - typically disk thrashing and poor responsiveness or performance from the java application and from other programs running on the system. Running top on Unix-like systems and looking at the memory used by the java application can help to diagnose this. Since most desktop and laptop machines these days have quite large amounts of memory available, this problem is not very common except on rather old, or especially heavily loaded machines.

Why?? Java is pretty good at a lot of things, but for reasons too complicated to go into here it is rather primitive about its use of virtual memory. You have to tell each Java application, implicitly or explicitly, how much memory it can use before it starts up; it is not possible to change this allocation while the application is running. If it later turns out to be too little for the application, or too much for the machine, unfortunately there will be trouble.

General Tips

The main tricks to bear in mind are:

1. Try using the defaults

Some of these applications have their own ways of allocating sensible amounts of memory, or simply don't have very large requirements, so it may be that by starting them up and using them in the most straightforward way things will work fine.

2. Look for a memory setting flag on the application

The particular application that you are using may have specific flags or other mechanisms for configuring memory usage. Check the documentation for advice about issues related to memory or large datasets.

However, if neither of those work, you'll have to...

3. Use the -Xmx flag

• Windows users - don't despair! You can increase memory for VODesktop or any other java application in exactly the same way as described here by typing the same commands as shown below in a DOS command prompt window. On opening the command prompt just navigate to the directory on your machine where the jar file is located using cd then type commands as below. Note that you will need to relaunch the application just as on any other platform.

If the default settings doesn't work, you will probably need to change the way that Java starts up, by telling it how much memory it is allowed to use. If you started the application by typing something like

    java -jar appName.jar

then it will have started up with a default amount of memory, typically 64Mbyte. To make it run with, say 256Mbyte, type instead:

    java -Xmx256M -jar appName.jar

or with 512Mbyte, type:

    java -Xmx512M -jar appName.jar

you get the idea.

How much memory should you allocate? Difficult to say, but it should certainly be less than the amount of physical memory available on your machine. Setting it to a higher value than this will not necessarily fail, but performance is likely to be very poor. The default value is probably 64Mbyte, so the best thing is usually to increase this somewhat (double it?) until you reach a setting which allows the application to run without problems. If your problem is that too much memory is being used (a -Xmx flag is already present with a large value) of course you should reduce the existing value.

Points to remember:

1. Make sure to inclue the "M" - invoking java -Xmx256 will attempt to run in 256 bytes of memory, which is unlikely to get very far.
2. Order is important - for instance writing "java -jar appName.jar -Xmx256M" will not work. If the -Xmx flag is directly after the java you'll be OK.
3. The original java command might not have exactly the form above, but as long as it starts "java ..." the same rules will apply.

If you didn't start the application by typing java ..., things are a bit more complicated. Something, somewhere, will have invoked java, and you will have to track it down to add or change the -Xmx flag. There are various possibilities:

Invocation from a script

If you type some command from the command line to start the application which doesn't begin with "java", then it is presumably the name of a script. Work out where the script is (e.g. "which <script-name>") and then do one of the following:

1. modify the script in place by adding a suitable -Xmx flag or changing an existing one (if you have the permissions)
2. take a copy of the script and modify that by adding/changing a suitable -Xmx flag
3. work out what java command the script is invoking, and invoke something similar yourself, either from the command line, or from a script of your own

Point and Click

WebStart (a.k.a. .jnlp file)

It is not very easy to change the memory settings for an application which is started using Sun's WebStart application launcher. If you can modify the .jnlp file, then add the attribute "java-vm-args='-Xmx256M'" (or whatever) to the <j2se> element. If (more likely) you can't, the only thing to do is to ask the website administrator to do the same thing. This is one reason why WebStart, while quite handy for simple things, is not ideal for all purposes.

Advice for specific tools

VO Desktop

TOPCAT and STILTS

TOPCAT and its command-line sister package STILTS are capable of coping with quite large tables (a million rows or so for most purposes), but you sometimes need to alter the defaults to make this work. The -Xmx flag is one option, but others are sometimes more effective, in particular using FITS format for large tables or, if that's not convenient, using the -disk flag. See the Tips for Large Tables section of TOPCAT's manual for more detailed discussion.

Some operations which cannot be performed using TOPCAT because they are too memory hungry can be done using STILTS, since it is capable of streaming data in some cases.

Aladin

There is advice in the Aladin FAQ on this topic.