Java Climate Model JCM

Sorry - this page is out of date!
Since my ex-institute closed JCM SVN server, I haven't yet fixed another.
See issues related to New Version

Java Climate Model - Source Code, JDK, IDE, SVN

Java Climate Model is open source - nothing is hidden.
You are also welcome to contribute to its development (although this is not easy!).

Please see Conditions of Use in the model documentation

Viewing source code from within the model

A simple source-code viewer has been provided within the model interface, to enable users to check some scientific details without opening a complex IDE.
This source code is only available at "expert" complexity level (adjust View=>Complexity=>Expert).
You can then access specific source code files from the model tree (press the java-source filter button), from the menu at the top, or from module documentation pages.

Java Development Kit

To compile JCM code you need a recent Java Development Kit v1.6+, available for free download from www.oracle.com/technetwork/java/index.html
http://www.oracle.com/technetwork/java/index.html also contains a huge amount of documentation about Java - the Java Tutorial is especially recommended
Note: The JDK contains more tools than the JRE (Java Runtime Environment). You only need Java SE (Standard Edition)

note for Apple-Mac users: Macs typically have JDK 1.5 pre-installed. It is possible to compile JCM with this v1.5, if you simply comment out a few inessential methods in java6methods.java. It is recommended to install the more recent JDK v1.6 available from www.apple.com/search/?q=java which runs faster and allows you to experiment with new features, however this is only available for 64bit Intel macs - i.e. those with Core-2 Duo processors,

Netbeans Integrated Development Environment

To investigate the code in detail and to modify it, it is recommended to use an Integrated Development Environment (IDE) such as Netbeans.
(It is also possible to use Eclipse, if you prefer and know this well - but you will have to set up more for yourself).

You can download Netbeans for free from netbeans.org
You can also download and install netbeans and the current JDK together in one bundle

JCM is a Netbeans free-form project. In addition to the source code, the project includes some additional build and properties files necessary to compile the code, integrate the input data and documentation, package the jars, set classpaths etc. All necessary files are available via SVN (see below)

Subversion (SVN) code-sharing system

JCM source code is now available using the Subversion (SVN) code-sharing system. For explanation of the concept see subversion.tigris.org

Subversion is well integrated within recent versions of Netbeans - you don't need to install subversion separately. This makes it easy to interact with the server (update and commit), to keep track of which files have been modified, to compare differences and merge changes.
There is also substantial documentation about Subversion within Netbeans help.

The SVN repository of JCM has been installed on a server in UCL-ASTR https://stratus.astr.ucl.ac.be/usvn/svn/JCM
To view recent changes use https://stratus.astr.ucl.ac.be/viewvc/?root=JCM

An open account with read-only permission lets you download the latest JCM code (checkout and update), modify, compile and run JCM on your own computer, but not to send changes (commit) back to the server.

Steps to get JCM code via Netbeans and SVN

Note: this is really for dedicated experts! First experiment with JCM from the webstart launch page!

Install the JDK (v6+)
Install Netbeans (v6+)
OpenNetbeans, from the top menu Versioning go to > Subversion. If Subversion is not yet installed, it will now install itself
Again from the top menu Versioning go to > Subversion >Checkout, and fill the form:
- Repository URL = https://stratus.astr.ucl.ac.be/usvn/svn/JCM
- User: astr Password: inviteastr
- Certificate : "accept permanently"
- Click "Next"
- Folders to checkout: Browse, select the "trunk" and click "Ok"
- Select the checkbox "skip the directory <...> and checkout only its content"
- Select a local folder where you want to store JCM
- Click "Finish", and when the JCM files have downloaded choose "Open Project"
Use "Clean and Build" ( button with broom and hammer) to compile the code. Folders called build and dist should be created in this process
Et voilà, "ready to use" ! You can now run JCM, either from within netbeans (triangular button), or by double-clicking on JCM.jar within the "dist" folder
Later - use Suversion => Update, and Show-Changes to get new code from the server and compare with your local copy.

Notes about the file structure

Source:Model code is in src/jcm jcm.core = structural components, jcm.gui= graphical user interface, jcm.mod = scientific modules
JCM.jar: Everything within the src folder gets included within JCM.jar package used to run the model.
Project: The files in project and nbproject should give Netbeans enough info to compile JCM - the build mechanism is handled by "ANT"
jcmout: When you run JCM, a folder jcmout will be created, to store setups, labdochanges, saved images etc.
Data: Additional data jar files are needed to run JCM.jar - lucdata.jar is essential (if it can't find this, historical LUC emissions are zero, and the carbon cycle and temperature are obviously wrong). These data don't change often so they are stored in the extrajar folder and recopied to dist after each "clean and build". Smaller data files are found within src/data, and are within JCM.jar.
Todos: Many "todo" files within src/todo as well as code-specific todo notes scattered within the java files. Todo notes are identified by P5, P4, P3, P2, P1 - which indicate priority - use netbeans tasklist to find and sort these (set-up using preferences > misc) .
Labdoc: Changes to labels and documentation are made from within the model using the Edit-Doc menu and a wiki system. These are saved temporarily to labdocchanges, and later exported to labdoc to incorporate in labdoc.jar. Thus, it is possible to add labels and documentation (for example, to translate to another language) without using netbeans or compiling any java.
Ant Tasks: Extra "ANT" tasks - to repackage the data, labdoc and source jars are accessed by right-clicking on the project root (JCM5-svn-trunk) from the project window.

Other Technical Notes

You should be using JDK v6+ (check Java Platform Manager and project properties). It's possible to compile in JDK v5 with minor modifications to code - see notes within java6methods.java.
It is important for the labels/documentation to use UTF-8 text encoding within netbeans and for compilation (beware this is not the default for Netbeans on mac!)
if you wish to keep the link to SVN to receive updates or commit changes, it is very important to use only netbeans to add or delete any folders -
*don't* delete folders in windows explorer / mac finder / a command line (except via svn commands)!

Javadoc

Only a few java classes in jcm.core have been annotated for automatic creation of JavaDoc. This is useful for pop-up info in netbeans. More may be added later but this is a low priority.
The model documentation should be consulted for information about the scientific modules, the model structure, and some of the core building blocks (curves, parameters, modules, model loop and interactions etc.). It is eventually intended to move much of this documentation within the source code, to make it easier to keep up-to-date

Contributing to JCM Development

You are welcome to try contributing to improving JCM - please discuss your ideas with us (see contact info).
You can start by experimenting for yourself, to get an idea of what is involved. Then if you think you have made a significant improvement you may request a user account and a password to contribute to JCM via SVN

Quality control of JCM is very important. The model interactions are complex, and small changes in code easily lead to mysterious bugs.
Therefore we can only give write-access and support to trusted people with some expertise in *both* climate science and java programming.

You should start by modifying your own "branch" (see SVN documentation) , so that experimental modifications don't cause bugs for other users. Robust changes can be merged with the "trunk" later.

Please check your ideas against the existing todos (see above) - we already have many more ideas than we are able to implement, but have already thought about how each may be done.

We only began using SVN with JCM recently, between colleagues within UCL-ASTR who know the model well - some technical difficulties are to be expected for an external user.
If you encounter problems, please contact Ben Matthews (see contact info).
If sufficient people are interested, a forum will be set up later