Next: 3.5 To commit or Up: 3. Source package Previous: 3.3 The concept of

Subsections

3.4 Versioning

During the TM meetings it was sometimes stated that TM5 lacks a proper versioning. There are no well defined 'frozen' versions with known behaviour, since some users tend to modify and commit the source almost every week (they sometimes appologize for that, but that does not solve the problem ofcourse). Besides, there is lack of benchmark simulations that could be used to test how changes in the code act on tracer concentrations.

To solve the problems, the TM5 source has been changed at 2006-09-01 to have a better control on different versions.

3.4.1 Cycles, releases, and CVS tags

A TM5 version should be identified by a tag of the form:

The tag contains two fiels, a 'cycle number' and a 'release number'. Conventions:

cycle: A cycle number indicates a major revision of the entire code. A major change in the base is a good candidate for a new cycle number. For example, in the test suite we assigned 'base' to 'cy1' and 'base-beta2' to 'cy2'.
release: A new release number is assigned in case of major bug fixes, for example if wind speed is computed in rad/s instead of m/s.

Between two releases, smaller cosmetic changes might have been commit, for example compiler dependent fixes and parallelization improvements.

Tags can be assigned to source files by cvs. It is possible to extract a complete source code from the cvs server using its tag.

3.4.2 Source tree

The source tree of TM5 could look like:

        TM5/
        TM5/README
        TM5/Makefile
        TM5/doc
        TM5/cy1/
                run-tm5
                base/
                     bin/
                     src/
                     rc/
                     idl/
                proj/chem/
                          test/
                               bin/
                               src/
                               rc/
                          aero/
                               bin/
                                :
                           :
        TM5/cy2
                run-tm5
                base/
                     src/
                      :
                proj/chem/
                          ipcc/
                               bin/
                               src/
                          strat/
                           :
                      :

Main differences the old tree are:

Each 'cycle' has its own directory in the root of the tree.
Each 'cycle' contains a 'base' directory; the former 'proj/base-beta2' is now simply 'cy2/base' .
A sample rcfile should be in 'base/rc' for the simple test version; for a benchmark, it should be in 'chem/radon/rc' for example.

In practice, where you did before:

home > cd TM5 home/TM5 > ./run-tm5 tm5.rc

you now have to change to the correct cycle directory first:

home > cd TM5/cy1 home/TM5/cy1 > ./run-tm5 tm5.rc

3.4.3 Where is what ?

Where have the old sources ended up in the new tree ?

        old                                cycle 1                         cycle 2                         cycle 3
        -------------------------          ----------------------------    ----------------------------    ----------------------------
        base                          ->   cy1/base
        proj/chem/aero                ->   cy1/proj/chem/aero
        proj/chem/cbm4                ->   cy1/proj/chem/cbm4  
        proj/chem/cbm4/enkf_base      ->   cy1/proj/chem/cbm4/enkf_base
        proj/chem/enkf_base           ->   cy1/proj/chem/enkf_base
        proj/chem/eud                 ->   cy1/proj/chem/eud
        proj/chem/ipcc                ->   cy1/proj/chem/ipcc
        proj/chem/test                ->   cy1/proj/chem/test
        proj/chem/var4d               ->   cy1/proj/chem/var4d

        proj/base-beta2               ->                                   cy2/base                     
        proj/advect/secmom            ->                                   cy2/proj/advect/secmom            
        proj/chem/cbm4-beta           ->                                   cy2/proj/chem/cbm4
        proj/chem/co2                 ->                                   cy2/proj/chem/co2                 
        proj/chem/enkf_basebeta2      ->                                   cy2/proj/chem/enkf_base           
        proj/chem/ipcc-beta2          ->                                   cy2/proj/chem/ipcc                
        proj/chem/noaa_gmd            ->                                   cy2/proj/chem/noaa_gmd            
        proj/chem/strat               ->                                   cy2/proj/chem/strat               
        proj/chem/tc                  ->                                   cy2/proj/chem/tc                  
        proj/chem/tc/enkf_basebeta2   ->                                   cy2/proj/chem/tc/enkf_base        

        proj/base-beta3               ->                                                                   cy3/base
        proj/chem/one                 ->                                                                   cy3/proj/chem/one

        proj/levels/ozone44           ->                                   cy2/proj/levels/ozone44         
        proj/levels/ml60              ->                                   cy2/proj/levels/ml60            cy3/proj/levels/ml60
        proj/levels/ml91              ->                                   cy2/proj/levels/ml91            cy3/proj/levels/ml91
        proj/levels/ml91/tropo34      ->                                   cy2/proj/levels/ml91/tropo34    cy3/proj/levels/ml91/tropo34
        proj/levels/nc28              ->                                   cy2/proj/levels/nc28            
        proj/levels/nc64              ->                                   cy2/proj/levels/nc64            
        
        proj/grid/eur                 ->                                   cy2/proj/grid/eur               cy3/proj/grid/eur
        proj/grid/glb3x2              ->                                   cy2/proj/grid/glb3x2            cy3/proj/grid/glb3x2
        proj/grid/glb6x4              ->                                   cy2/proj/grid/glb6x4            cy3/proj/grid/glb6x4
        proj/grid/nam                 ->                                   cy2/proj/grid/nam

The following projects are depricated and therefore not transfered to the new tree:

        proj/TMkit
        proj/newbase
        proj/base-beta
        proj/base-alfa1
        proj/levels/all60

3.4.4 Old tree

The old source tree has been saved on the cvs server as 'TM5-oldtree'.

If necessary for re-run or historical surveys, checkout by:

cvs -d :ext:yourname@docex.knmi.nl:/cvs/TM checkout TM5-oldtree

3.4.5 How to change from old to new tree ?

The best way to change from working with the old tree to working with the new tree is:

First save your old version:
```
        mv TM5 TM5-my-old-stuff
```

Checkout the new tree:

        cvs -d :ext:yourname@docex.knmi.nl:/cvs/TM checkout TM5

Change to your favorite cycle:
```
        cd TM5/cy2
```

Copy your own stuff from the old tree:

        cp -r ../../TM5-my-old-stuff/proj/mystuff proj/
        cp ../../TM5-my-old-stuff/tm5-mystuff.rc .

Start the model as usual:
```
        ./run-tm5 tm5-mystuff.rc
```
Inspect the error messages and solve the problems ...

3.4.6 Checkout by release tag or date

To checkout the source of of cycle given a release tag, use:

cvs -d :ext:yourname@docex.knmi.nl:/cvs/TM checkout -r 'cy1r1' TM5/cy1

Release tags are assigned to all files in a cy? directory by:

cvs tag -R 'cy1r1' *

The idea is that only people who now what they are doing, and are capable of updating the documentation, assign new tags ...

To checkout a model version as it was storred on the cvs server on a certain date, use:

cvs -d :ext:yourname@codex.knmi.nl:/cvs/TM checkout -D 2005-01-01 TM5

3.4.7 Benchmarks

The following benckmarks are proposed:

name purpose

base 5 tracers filled with 1..5; test parallelization

chem/radon Rn222 and Pb210 to test transport

chem/aero tropospheric chemistry, zooming over europe

chem/ozone stratospheric ozone parameterized with Cariolle scheme

Each cycle contains its own benchmark chemistries.

An rcfile to run the benchmark should be provided as 'chem/radon/rc/tm5.rc' for example.

Next: 3.5 To commit or Up: 3. Source package Previous: 3.3 The concept of

Created at IMAU on Tue Mar 3 05:00:05 CET 2009 by a slave chained in the basement

name	purpose
base	5 tracers filled with 1..5; test parallelization
chem/radon	Rn222 and Pb210 to test transport
chem/aero	tropospheric chemistry, zooming over europe
chem/ozone	stratospheric ozone parameterized with Cariolle scheme