This is part of the labels / documentation for <a href='http://jcm.chooseclimate.org'>Java Climate Model</a><hr/>

#tech		¨oldJCM4 addJCM5		§Note this is old documentation from JCM4, to be updated

@copyr
@printing
@download
@labdoc
@scripting 
  @startjcm
 @aboutjava
@struccode
@howfast    <li>Note also <a href="../struc/javaproblem.html" target="_new">problems with java</a>

#comp		¨oldJCM4 addJCM5		§For the current structure see 
@jcm
@jcm.core
@jcm.gui
@jcm.tls 

Below are links to old JCM4 documentation, to be updated.

<nobr>¤gui @gui </nobr>
<nobr> ¤tool @tls </nobr>
<nobr>¤root @root </nobr>
  <hr>
  See also @struccode,
¤mod @mod,
¤pan @pan

#struccode		¨oldJCM4		§JCM code is divided into several java Packages:
  <table border=1><tr><td colspan=3 align=center><b>jcm/</b> <i>@root</i>
 (iob param loop mainapp) </td></tr>
  <tr><td align=center><b>jcm/mod</b> <i>@mod</i></td><td align=center><b>jcm/gui</b> <i>@gui</i></td><td align=center><b>jcm/tls</b> <i>@tls </i></td></tr>
  <tr><td>climate calculations</td><td>layout, plots, controls, events</td><td> files, labels, scripts, webdoc</td></tr>
  <tr><td colspan=3 align=center><b>jcm/pan</b> <i>@pan</i>
fill plots with module data, connect parameters with controls</td></tr></table>
  Most components descend from the same @iob, which provides the link between them. This also holds flags specifying what needs to be recalculated (a key element of JCM's efficiency -see @howfast). The calculation itself is handled by @loop.

  @mod and @tls are entirely independent of the graphical interface, and may be compiled and run without the gui and pan packages being present.
  This independence may be useful for batch calculations which loop through the model many times without plotting graphics at every step, for example for probability analysis or optimisation problems. In this case, a text instruction script with file input/output could be used to control the model.

  @gui include general panels and graphs, menus, buttons, draggable controls, pop-up labels, also  the layout manager, event handler, etc. These do not refer to specific @mod so they might be reused for other applications

  Calculations in @mod are combined with graphics plotting routines in @gui to make the visible @pan.
  Each adjustable control combines both a @param (usually defined in a module) and a @popob (part of the graphical interface).

  <hr>
  Note: JCM documentation has the same structure as the model. Each page has a link to the source code and also to the page about  the java class which it <i>extends</i>.
  If @helpmode is selected,  clicking on any part of the model interface will summon the relevant documentation.
  <hr>(See also @aboutjava)
  ---- ===All code in one file=== This may be useful for printing.<li><a href="../code/jcmcodeall.txt" target="new">jcmcodeall.txt</a> (500K!)
  If you want to study the code, you should download the package<li>see @download
  ---- ===makedata=== need to add links here

#howfast		¨oldJCM4		§A great effort has been made, to keep JCM very efficient and compact,
  both considering users with slower computers and web connections,
  and because the instant "mechanical" response to adjustments helps to demonstrate cause-effect interactions. 

Some key features that make this possible are described by the links below.

<li>@eigenvec

Efficient eigenvector prop/step/ramp functions for the core carbon and climate models

<li>@iob

Interaction between Modules and Panels
  Only run modules / panels which are both <b>needed</b> for screen output, and have been <b>changed</b> by the user since the last calculation.

<li>@loaddata

Historical / Scenario / Climate-pattern data is compressed to one-byte per number, thus minimising download time.

  ---- ===Model and graphics in one tool===
  There are many "visualisers" written in java,
  which simply plot data created using model code in another language (typically fortran),
  transferred by intermediate text files.
  This is intrinsically very inefficient:
  saving and loading data files may take longer than the science calculations,
  especially if working across the web.

  Whereas in JCM, the model and graphics are both written in the same language,
  and so interact much more smoothly and efficiently.
  Moreover, by giving people the tool (the model) rather than the product (the data),
  the scope is much wider, and the package size is kept to a minimum.

#root		¨oldJCM4		§Core java classes binding JCM together and handling interactions   <li>see also @struccode
  ---- === Core building blocks===
  @iob
@mainapp
@loop
@param
  ---- === JCM Startup ===
  @openapp
@startup
@startjcm
@testmod

#loop		¨oldJCM4 addJCM5		§Loop controls the main calculation / drawing loop.
  It calls methods of every @interacob, in several stages (precalc, calc, postcalc, plot, postplot etc) to enable feedbacks between iobs.

Before running the loop, modloop also calls the checkinteractions method of @interacob and thus work out which modules are both needed and changed. See also @interacob.

For every timestep, all science modules that are both needed and changed are calculated, in an order dependent on @interactions.  This makes it easy to add both biogeochemical feedbacks (for example the effect of temperature on @carbonatechemistry) and also climate-emissions feedbacks (see @stabilisation).

 The graphical components (linked by @plotlink) are updated after the model calculations. 

%%¤adju Enabling the @loopinfo parameter will provide extra information in @sysout about which iobs were calculated and how many milliseconds were spent on each one. %%

#modlist		¨oldJCM4 addJCM5		§This is old JCM4 page, which should be replaced by a dynamically generated page, as in JCM5 the module order can change, depending on @interactions

The current order is:   <li>@loaddata<li> =&gt @sres<li> =&gt @kyoto<li> =&gt @mitigation<li> =&gt @people<li> =&gt @regshares<li> =&gt @carboncycle<li> =&gt @oghga<li> =&gt @radfor<li> =&gt @heatflux<li> =&gt @sealevel<li> =&gt @bord<li> =&gt @regcli<li> =&gt @costs<li> =&gt @responsibility

#module		¨oldJCM4 addJCM5		§Modules contain the core scientific calculations of JCM.  They also contain adjustable @param, and also  @qtset for plotting graphs.

Modules calculation methods are called by @loop in the following sequence:   <ul> <li>precalc(): calculations just before main time loop   <li>calcstep(step): calculate one timestep: most of the work is done here.   <li>postcalc(): calculations after main timeloop (e.g. for normalising etc.)
</ul>
 
 See also @interacmap, @interacob

Old labels:
@aboutmodules, @modlist

#loaddata		¨oldJCM4 addJCM5		§¤cogs This is an old JCM4 module, whose function is gradually replaced by loading data from text files

This module fills arrays of historical data (historical emissions, concentrations, temperatures) and predefined future scenarios (see @aboutsres).

The original data is found in the java files  <ul>
<li><a target='data' href='../makedata/histdata.java'>histdata</a>Historical emissions, concentrations and temperatures.  <li><a target='data' href='../makedata/histresp.java'>histresp</a> Historical regional emissions data used for the @responsibility calculations (UNFCCC assessment of Brazilian proposal)   <li><a target='data' href='../makedata/sresdata.java'>sresdata</a> Future SRES scenarios (global emissions and IPCC predictions)  <li><a target='data' href='../makedata/sresreg.java'>sresreg</a> Future SRES scenarios (regional socioeconomic data)

</ul>
 This data  is compressed by the routines in <a href='../makedata/savedata.java'>savedata</a>, to make the binary file jcm/data/data.dat For each sequence of data, the maximum and minumum and range are found. Each data item is then converted to one byte, by subtracting the minimum, dividing by the range, and multiplying by 256. So the precision is 0.4% of the range, or one pixel of a typical plot.

When the model starts up, "loaddata" simply loads and uncompresses this datafile into specific modules.

 See also @histemitobserv and @rftemp

#aboutmodules		¨oldJCM4		§Modules contain the core scientific calculations of JCM.  They are owners of most adjustable @param, and also arrays of output data which may be referenced by visible graphs.

Modules may use @tls and @root but do not refer to @gui or @pan (¤cogs see @struccode)

#parallelworld		¨fut		§Currently JCM has only one copy of each of the @mod , because the @modlist effectively makes them all 'static'.
  %%¤cogs Note: 'static' has a specific meaning in java -see Sun's Java Tutorial (link from @aboutjava). %%
  This makes it easy for modules to interact with each other (see @iob, @flowchart), however it is restrictive if we wish to compare different scenarios or different implementations of climatic components. So it is proposed that modules should no longer be static, instead  referring to each other via a root 'world' object, of which there may be more than one instance. For efficiency different 'worlds' could share certain modules: for example, the same emissions scenario combined with different climate modules, or vice versa (although in such cases  careful consideration of feedback effects would be needed).

Note that it is already possible to have multiple copies of each panel, with different layout options (see @jcmpanel). This was slightly easier to implement because there are no direct interactions between panels.

#mathcurve		¨oldJCM4 addJCM5		§This class simply contains mathematical formuale to generate various kinds of curves for @stabilisation and @optimisation . The curves are mainly variants of the Padé formulae used for the original IPCC 'S' scenarios (Enting et al 1994).

#param		¨oldJCM4 addJCM5		§Adjustable Parameters are central to the concept of JCM
There are several types: true / false, numerical values, menu of strings or other objects (e.g. regions). 
A parameter also stores a default value, plus limits for numerical values. 

Most parameters belong to a @module whose code defines its effect on the model. Others are used by @jcm.gui

Parameters can be adjusted from the @treeMaker, from which you can tear off subtrees to keep a group or parameters visible. 
They are also accessible from a top menu, but this is less convenient)
If the option @filterenabled is enabled, you will only see parameters relevent to currently visible plots

Changing a parameter triggers the whole model to recalculate as needed (see @loop, @interactions)

If @helpmode is selected, you can get documentation about any parameter by clicking on it in the @treeMaker

If you need to adjust many parameters systematically, such as for probabilistic analysis, you may wish to consider @scripting.
 ¤cogs Parameters may later be extended to associate probability density functions.

#iob		¨oldJCM4		§Iob (Interaction Object) handles the interactions between JCM components (see also @flowchart, @struccode)
  Iob is the java superclass of all @mod, @pan, @param and @gui (menus, options and controls).
  Each iob stores a list of all the other iobs which are it affects, or is affected by. These interactions are declared in the individual modules and panels.
  This enables panels to interact with modules, via controls and parameters, without the module code making any reference to the graphical interface. Thus, the science and graphics components can be developed independently, yet they can still interact seamlessly.

  Each iob also stores flags, to say whether it is needed (for visible output) or has been changed, due to adjustments by the user.
  If an iob is needed, all those which it is affected by must also be needed. If an iob has changed, all those which it affects must also be changed. When one iob changes or becomes needed, a recursive loop checks through all the iobs, to set these flags accordingly.

  Only those iobs which are both needed and changed are run during the main @loop calculations. This makes a key contribution to the speed and efficiency of JCM. You can observe that the model responds faster when you adjust controls affecting only the end of cause-effect sequence (e.g. climate model parameters, with feedbacks disabled). The response is also faster if you view less plots (e.g. if only regional emissions are visible, the carbon-climate modules are not run).

  Each iob also has an "owner" which contains methods specifying effects of adjustment (used by @param and @popob).
  Each iob also has a unique name (see @names) and contains methods to also provide textual information, for documentation, scripting or debugging (see @labdoc, @scripting).

#testmod		¨oldJCM4		§A simple applet which uses jcm/mod to calculate the sealevel rise, without any reference to the graphical interface (it should still work if jcm/gui and jcm/pan are not compiled)

#startjcm		¨oldJCM4		§You don't need a web browser to run JCM, but you do need a "java virtual machine" (JVM) installed on your computer (see @jvm)
  Most operating systems have a JVM already installed. Recent versions of MS Windows already include a very fast JVM which can be opened using "wjview.exe" (although microsoft doesn't advertise this any more).
  However to use some newer features in JCM (such as image capture) you will need the latest JVM from Sun (java.sun.com).

If you installed a recent version of Sun's JVM you may find that clicking on the jcm.jar file in the JCM root directory is sufficient to open the model.

If not you need the following commands, which could be run from the command line, or put into a desktop shortcut for convenience:
  <pre>  <li><i>Using MS Jview:</i> C: 

 Windows 

 System32 

 wjview.exe /cp %path1% 

 jcm.jar jcm.startjcm %path2%/jcm   <li><i>Or using Sun's JVM:</i> java -cp %path1% 

 jcm.jar jcm.startjcm %path2%/jcm   <li><i>or try: </i>C: 

 java 

 jdk 

 bin 

 java.exe -cp %path1% 

 jcm.jar jcm.startjcm %path2%/jcm
  <i>changing c: 

 ... to wherever java.exe is located on your system </i>
  %path1% and %path2% are variants of the path to the JCM root directory (the directory containing jcm.jar)
  (e.g. on my system:)
  %path1% is c: 

 java 

 jcm
  %path2% is /java/jcm (note initial / replaces c:)
  %path2%/jcm should not be necessary if the command is typed from the same directory as jcm.jar
  </pre>
  @contact me for more information .  <li>Note also @startjcmswing

#startjcmswing		¨oldJCM4		§If you have Java v1.4 you can now use startjcmswing to run JCM standalone, including the html documentation (see @labdoc)
  Just click on jcm.jar from the @download. See @startjcm for more instructions (replacing startjcm with startjcmswing).
  From this, a @notepad can also be used to edit and save the documentation.

#tls		¨oldJCM4		§Tools for handling  labels, scripts and documentation, file input/output, text parsing.
  ---- === Labels /  Documentation / Scripts / Demos===
  @labinf
@autodoc
@sort
@showwebpage
@player
 @recorder

  ---- === General tools===
  @ref
@txt
 @fileio
@sysin 
  <hr>%% ¤cogs (Note: Tools may use @root but do not refer to @gui or science @mod or @pan - see also @struccode)%%

#ref		¨oldJCM4		§This class contains some methods using Java "Reflection" to help parts of JCM find each other (see jdk-api java.lang.reflect).

#openapp		¨oldJCM4		§loads main model, first testing for browser compatability

#startup		¨oldJCM4		§handles startup and reset sequence

#mainapp		¨oldJCM4		§Mainapp extends Applet to provide the interface with the web-browser.

Mainapp handles applet parameters and methods called from javascript, and each @jcmpanel gets its graphics context and events from the underlying Panel.

It also triggers @startup to initialise JCM and @plotlayout to respond to repainting and resizing, although the main drawing routines are called by @loop.

(note: you can use @startjcm to create a mainapp window without any web browser).