How to get started using ORCHESTRA for speciation calculations

Hans Meeussen, 2 July 2009

This tutorial shows how to download and install ORCHESTRA and how to run a basic example from the web.

1) Download a Java virtual machine

First of all ORCHESTRA is written in Java. For users this means in that ORCHESTRA can be used on a wide range of operating systems,

but also that you need a (recent) Java virtual machine (bit of software) to be able to run it..

(Java virtual machines are available for o.a. UNIX, LINUX, Mac OSX, MS Windows, Solaris.)

If your machine does not have a (recent) Java virtual machine, a free version can be downloaded from SUN Microsystems.

2) Download the ORCHESTRA program executable.

The next thing you need is the ORCHESTRA executable program,

which can be downloaded from:

Save this file to any chosen location on your system.

Note that with some operating systems you need to right click this link to download the file.

Furthermore, make sure that your operating system does not rename this .jar file to a .txt file.

3) Start ORCHESTRA by (double) clicking the Orchestra2008.jar file.

Once this file is saved to your local machine it will usually be possible to start ORCHESTRA by simply (double) clicking it.

If this does not work this probably has something to do with binding files with .jar extension to the Java virtual machine.

Under MS Windows, this can be fixed as follows.

In the Folder Options go to the JAR extension, and then to the “Advanced” button.

Next, click edit and, and fill in the path to the Java executable (javaw.exe), which should look something like:

"C:\Program Files\Java\jre1.7.0\bin\javaw.exe" -jar "%1" %*

Adding the parameter “-Xmx512m” will give Java more available memory, which is necessary for running larger systems.

"C:\Program Files\Java\jre1.7.0\bin\javaw.exe" -jar -Xmx512m "%1" %*

(The default amount of Java memory depends on the actual machine, and can be too small to run larger systems)

Double clicking the orchestra2008.jar file should now start up Orchestra in interactive mode, which looks as follows:


Instead of double clicking the orchestra2008.jar file it is also possible to start orchestra from the command line:

java -Xmx512 -jar orchestra2008.jar

4) Open existing input file or directory.

We are now ready to open an existing input file as starting point.

ORCHESTRA uses sets of text files as input, which can either be placed in a folder, or packed in a zip file.

ORCHESTRA can open these zip files also directly from a URL.

First we will show how to open a .zip input file from the web.

Under the file tab choose the option open remote file, and choose the first example:

After a few seconds, depending on the bandwidth of your web connection, ORCHESTRA refreshes its appearance and a number of tabs appear on the right.

The first tab shows a text file with documentation.

The chemistry tab contains the GUI editor for the graphical system. This is the place where we can define the substances and reactions that we would like to include in the calculations. This very simple system contains just carbonate, water and protons. It uses a fixed (log) activity of water and protons (pH), and a given total concentration of carbonate per liter.

Under the reactions tab we can find (and select) which reactions are taken into account.

(In this case we do not want to consider gaseous CO2 .)

Clicking change View switches between text and graphical editor of the chemistry file.

Under the input tab we can edit the input file. We can provide a number of data points here, or use variables in a Sweep ( kind of loop).

In this case we would like to do the equilibrium calculations for a range of pH values.

So, say 20 calculations, with pH starting from 2 up to 12.

Note that values provided her overwrite the default pH value given under the chemistry tab.

4) Start the calculations by clicking the Run tab.

The calculations are started by clicking the Run tab. This system runs very quickly so

if noting seems to happen, your calculations might actually have finished.

This can be checked in the output file.

5) Analyse the output by copy and paste to spreadsheet.

The ORCHESTRA output (in this case concentrations of individual carbonate species) can simply be transferred to a spreadsheet, and then used to make graphs.

6) Change input and run again.

If we look at the output file we can see that the first calculation was done at pH 7, and furthermore that the distribution of calculated pH values is not very nice.

By adapting the input file so it uses Default: rather than Data: for the pH variable, line is not used as input data point, but only to define the pH variable as input parameter with default value.

This value is subsequently overwritten by the Sweep loop that follows. If we would like a calculation at every pH from 2 to 12, 11 calculations are required.

So changing this in the Sweep definition:

Results in the following output: