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

#tech		¨oldJCM4 addJCM5		§<ul>
<li>@startpack
</ul><hr><ul>
<li>@labdoc
<li>@translation
<li>@printing
<li>@data  
<li>@scripting 
</ul><hr><ul>
<li>@struccode
<li>@howfast   
<li>@aboutjava
<li>@writejava
<li>@copyr

</ul>

#comp		¨oldJCM4		§Old JCM4 label, £>jcm, @jcm5_root

#struccode		¨oldJCM4		§JCM code is divided into several java @Packages, each of which contains further subpackages :
<ul>
£*jcm.mod
£*jcm.core
£*jcm.gui
</ul>
The modular structure is intended to make it as easy as possible for other climate modellers to quickly find the scientific code of interest to them (note that a simple @sourceview is provided within the model). 

This structure also makes it easy for anybody to add a new module without thinking about the graphical interface, since the necessary links will automatically be added to the @jcmtree and @menus, and the skeleton of @documentation pages for the module.

However to understand the scientific code it is important to consider part of the jcm.core package, especially <ul>
<li>@qtset (which store state and generate plots)
<li>@param (anything adjustable)
<li>@loop (defining the calculation order)
<li>the concept of @interactions
</ul>
Note also <ul>
<li> @howfast
<li> @aboutjava
<li> @writejava
<li>@copyr
</ul>

#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 (see @dialogue).  Fast calculations are also useful for probabilistic analysis of thousands of variants (see @scripts), in which case typically 1-10 variants can be calculated per second (depending on how much changes). 

Some key features that make this speed possible are:<ul>
<li>Efficient @interactions system.
 The @loop runs only modules which are both <b>needed</b> for visible @plots, and have been <b>changed</b> by @params since the last calculation.
Thus, unnecessary repetition is avoided, especially of slower modules at both the emissions or impacts ends of the cause-effect chain. 

<li>@eigenvec Efficient eigenvector prop/step/ramp functions for the central @udebclimod and @berncarbon

<li>Compressed Data: 
 Historical, Scenario, and Geographic data is compressed using custom methods  appropriate for each type, see @jcm.core.data  

<li>Giving people a tool (model) rather than a product (data) is not only much more flexible, it also keeps the package size  to a minimum. Only historical and scenario input-data is stored, not future projections. 

<li>Flexible @regionsets / resolution / timescale
Sometimes we need data  at a national resolution, but often we only compare large regions or global averages. Rather than using a fixed region structure, JCM adjusts accordingly. The time horizon can also be adjusted (see @model_end_year)

<li>Integrated model and graphics 
 Many "visualisers" written in java simply plot data created using model code in another language (typically fortran),  transferred by intermediate text files.  This is very inefficient:  saving and loading data files (especially across the web) may take longer than the science calculations. In JCM, as the model and graphics are both written in the same language, they can interact much more smoothly and efficiently. 

<li>In its early days java gained a reputation for being slow, but recent advances in the @jvm make it as fast as  languages compiled to native code.
</ul>

#root		¨oldJCM4		§A core class of JCM which examines the contents of the JAR package (JCM5.jar) and creates from this the initial heirachy of @infob starting from @JCM5_root 
(almost the first thing that JCM does on startup)
See also @world, @startJCM

#loop		¨oldJCM4 addJCM5		§A structural component of JCM.
Loop controls the main calculation and plotting sequence:
Loop starts by calling the check-interactions method of @interacob to work out which are both needed and changed. Of these (only), the following methods are called:
<ul>
<li> the precalc method of each £`interacob (mainly used by @params)
<li> the calcstep method for each @module, for each timestep. 
<li> any postcalc methods (for normalising etc.)
<li> the doplot method of each visible @plotlink, to update @plots
</ul>

¤cogs The order of modules depends on the "follows()" methods set in @interactions (check the numbers shown in @interacmap, and  the @fcnormal)

¤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. 

¤cogs For each timestep, all active modules  (both needed and changed) are calculated in turn.  This makes it easy to add both biogeochemical feedbacks (e.g. @clicarbfeedback) and also climate-emissions feedbacks (see @clipolfeedback).

¤cogs Only one loop can run at any time, whilst loop is running other calls will be queued (this may happen, for example, when iterations such as @stabtemp or @optimisation are interrupted by user adjustment of a @param)

#modlist		¨oldlink		§£>loop, @fcnormal

#module		¨oldJCM4 addJCM5		§Modules contain the core scientific calculations of JCM.  They also contain @params, and  @qtsets, which can be shown in @plots

Modules calculation methods are called by @loop in the following sequence:   <ul> <li>precalc(): calculations just before main time loop   
<li>calcstep(): calculate one timestep: most of the work is done here.   <li>postcalc(): calculations after main timeloop (e.g. for normalising etc.)  </ul>
This system allows for feedbacks between modules.  

Changing interactions between modules are essential to the interactivity and speed of JCM, see  @interacmap, @interacob

All modules and all public £`params and £`qtsets which it contains are automatically added to the @jcmtree (by reflection -the java code inspecting itself). Thus, anybody can add a new module  for scientific code without worrying about the graphical interface structure. 

However, some modules may be hidden, due to their @complexity level, or if they contain no @neededparams .

#loaddata		¨oldJCM4 addJCM5		§¤cogs An old JCM4 module to load compressed binary data, whose function is gradually replaced by loading data from text files (see @histdata)

This module fills @qtsets 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		¨delete		§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 options, numerical values, and lists of  choices (or of objects such as regions).  A parameter also stores a default value (used to @reset it), plus  minimum/maximum limits (for values). 

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

¤adju Parameters can be adjusted from the @jcmtree. 
You can tear off subtrees to keep a group or parameters visible.  
¤adju Parameters are also accessible (less conveniently) from a @jcmmenu at the top.
¤adju A few parameters whose units match those of an associated @qtset can be controlled by draggable arrows appearing on a @lineplot (in this case, just open the plot, the parameter will appear if appropriate).
¤adju The @setupmenu provides options to save or reset all parameters

¤cogs Which parameters are visible depends on selected @filters and the chosen @complexity (see @neededparams)

¤cogs @complexity is also applied to individual items in a list parameter

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

¤adju You can get  documentation about individual parameters by selecting the @docview @filter in a @jcmtree, then using the popup links (in most cases it is better to read the @module documentation)

¤adju If you need to adjust many parameters systematically, such as for probabilistic analysis, you may wish to consider @scripts.

%% ¤cogs Parameters may later be extended to associate probability density functions.%%

#iob		¨oldlink		§£>interacob, also @infob

#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		§A class of JCM which contains the initial startup routine ("main")
called when the package is opened.
See also @root, @setup, @topmenus, @splash

#startjcmswing		¨delete		§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		§£>jcm.core.tls
Also a code for the region "East Timor"

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