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

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

#comp		§<nobr>°gui @gui </nobr>
<nobr> °tool @tls </nobr>
<nobr>°root @root </nobr>
  <hr>
  See also @struccode,
°mod @mod,
°pan @pan

#struccode		§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		§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		§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		§Loop controls the main calculation / drawing loop.
  It calls methods of every @iob, 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 @iob and thus work out which modules are both needed and changed. See also @flowchart.

The science modules are always calculated in the same order specified by @modlist, for every timestep (see @time).  This makes it easy to add both biogeochemical feedbacks (for example the effect of temperature on @carbchem) and also climate-emissions feedbacks (see @mitigation module).

 The graphical components are updated after the model calculations, from the back to the front.

²°adju Enabling the loopinfo parameter will provide information (shown in a @notepad or java console) about which iobs were calculated and how many milliseconds were spent on each one. ²

#modlist		§This interface lists all @mod.  It is implemented by all @mod and all @pan, helping them refer to each other. It also defines the sequence for model calculations in @loop.

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

Modlist is implemented by all modules, so they can easily refer to each other. However interface variables are always "static", which means there is only one copy of each module. It is anticipated to replace this with a @parallelworld structure, to allow comparison of different  model setups.

 See also @struccode

#module		§££aboutmodules
  Modules calculation methods are called by @loop in the following sequence:   <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.)
  For each stage, for each timestep, all modules are called in the order specified by  the @modlist interface, which also enables modules to refer to each other easily.
  See also @flowchart, @iob.

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

The original data is found in the java files  <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)

 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		§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		§This class simply contains mathematical formuale to generate various kinds of curves for @stabilisation. It is used by @mitigation module. The curves are mainly variants of the Padé formulae used for the original IPCC 'S' scenarios (Enting et al 1994).

#param		§A parameter contains the setting of each adjustable parameter, as well as its default setting (used to reset the model).

There are several types - true/false, numerical values, choice of strings, choice of iobs.

A parameter has both a  "controller" (a graphical @popob) used to adjust it, and an "owner" (e.g. a science module or layout setting) whose code defines its direct effect.

Changing a parameter triggers the whole model to recalculate as needed. Thus parameters enable interaction between @mod and @gui.

If @helpmode is selected, you can get documentation about any parameter by clicking on its "controller" (arrow, menu or option).

A Parameter can also write html code describing itself and containing burttons/menus/textfields to adjust it, for use within documentation.

You can also adjust any parameter by @scripting, and see all parameter values using @viewparams.

 Parameters may later be extended to associate probability density functions -see @uncertainty.

#iob		§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).

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

#startup		§handles startup and reset sequence

#mainapp		§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).

#testmod		§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		§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		§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		§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		§This class contains some methods using Java "Reflection" to help parts of JCM find each other (see jdk-api java.lang.reflect).