=====================================================
  Test Framework for gengeo
  Last Updated: 19 Jan 2006
=====================================================

The test suite aims at verifying some gengeo component individually, either automatically or manually.
This to ensure that modifications to the code base does not break any of these components.
Some test might use many component
- might not be testable otherwise
- or to check interactions

We will try to mimic the python automatic testing framework (unit test), with many random cases testing along with known special cases (compare to expected values).
But we'll add some manual (visual) testing as well).

It has to be maintained when gengeo evolves.

We may use this testing suite:
http://sourceforge.net/projects/fortunit

or integrate with python unittest using:
http://cens.ioc.ee/projects/f2py2e/

===== Basic Components =====

For any of the following components we may define many grids for each supported proj (N,S,E,E-rot,L,L-rot) using different mesh and size

Oversampling
- make sure the grid does not shift
  may define many grids for each supported proj: N,S,E,E-rot,L,L-rot
  use different mesh and size

Grid interpolation
- From Lat-Lon (all Source are in Lat-Lon) to N,S,E,E-rot,L,L-rot grids
  may define many grids of different mesh and size for each grid proj
- Check Singularities (Poles, Greenwich, and date-change Line)
- Single points and tiles (as in src2dst)

Grid Intersect
- test simple intersect part and sub-grid part
- Check Singularities (Poles, Greenwich, and date-change Line)

Grid Ratio / Grid dx

Check Aggreg
- srcpoint collect (2 methodes: see src2dst AND src2dst2)
- aggreg ovsamp to simple grid (same proj)
- aggreg mean and indexes (fractions)

===== Test suite =====

The basic components above are not necessarily simple and/or independent from each other. Thus we will try to derive an ordered list of items to be tested from the most basic one to the more complex.

__Program Tree (partial)__

gengeo
    geo_options_get
        geo_echo_help
        read_namelist
            nmlsetdefaultsfn
            nmlvalidatefn
            nmlprintlogical
    geoGenFld
        setovFac
            checkdbres
                map_isgridintersec #check also on reduced (ij0n) grid
                    map_isgridintersec0
                        map_getperimxy -
                        map_getxy #compare ezscint mode to optimezed mode
                            map_getllfxy
                                INT_L1DA1B  #macro
                                rpngrid_rotll_tllfrll
                                llfxy0 -
                                >rpngrid_setGID
                            map_getxyfll
                                INT_FINDX  #macro
                                rpngrid_rotll_rllftll
                                xyfll0 -
                                >rpngrid_setGID
                map_getgridcrop
                    .map_getperimxy - (see above)
                    .map_getxy (see above)
                    map_keepinerpoints2 -
                    map_perim2crop -
                .gridres #if verbose
                gridres_ratio
                    gridres_ratio_limits
                        gridres_pointslist -
                        .map_getxy (see above)
                        GETNBPTS #macro?
                >ospath_filelist
                >rpn_open_list
                >rpngrid_read
                >rpngrid_limits
                >rpn_close
                >rpngrid_free
        oversample
            >rpngrid_free
            >rpngrid_copy_tag
            >rpngrid_alloc
            INT_L1DA1B #macro
            OVMAP_GETXLFIH  #macro
        src2dst_loop
            >ospath_filelist
            .map_isgridintersec (see above)
            map_getgridcrop_multi
                map_gridsplit -
                .map_isgridintersec (see above)
                .map_getgridcrop (see above)
            .gridres_ratio (see above)
            src2dst_nearest
                checkmemalloc -
                .map_getxy (see above)
            src2dst_maxindex
                .checkmemalloc - (see above)
                map_getpts_in_ijtile
                    .map_getperimxy - (see above)
                    .map_getxy (see above)
                    .map_keepinerpoints2 (see above)
                    .map_perim2crop (see above)
            src2dst_collect
                .checkmemalloc - (see above)
                .map_getxy (see above)
            src2dst_missing -
            >rpn_open_list
            >rpngrid_read
            rpn_find #might be important to check if we find them all!!!
            >rpnstdrec_read
            >rpnstdrec_free
            >rpngrid_free
        src2dst2_loop ...
        agg_index ...
        agg_value ...
        agg_value2 ...
        agg_filter ...
        agg_filter2 ...
        >rpnstdrec_free
        >rpnstdrec_new
        >rpnstdrec_setgrid_z
        >rpnstdrec_alloc
        >rpnstdrec_copy_assoc
        >rpnstdrec_copy_tag
        >rpnstdrec_copy
        >convip
    cleanfield
    writeflds
    consisveg1st
    indexofmax
    roughveg
    roughvegflux
    blocage
    roughness3b
    calcindexcover
    >rpn_open
    >rpn_close
    >rpngrid_read
    >rpngrid_write
    >rpnstdrec_new
    >rpnstdrec_setgrid_z
    >rpnstdrec_free

__Reversing the tree__

xyfll0
llfxy0
INT_L1DA1B (INT_I0B)
INT_FINDX (INT_L1D0)
rpngrid_rotll_tllfrll
    map_getllfxy
    map_getxyfll
        map_getxy

*map_getxy*
    src2dst_nearest

*map_getxy*
    src2dst_collect

map_getperimxy
map_keepinerpoints2
map_perim2crop
*map_getxy*
    map_getpts_in_ijtile
        src2dst_maxindex

*map_getperimxy*
*map_getxy*
    map_isgridintersec0
        map_isgridintersec

*map_keepinerpoints2*
*map_perim2crop*
*map_getxy*
*map_getperimxy*
    map_getgridcrop

map_gridsplit
*map_isgridintersec*
*map_getgridcrop*
    map_getgridcrop_multi

INT_L1DA1B
OVMAP_GETXLFIH
    oversample

GETNBPTS
gridres_pointslist
*map_getxy*
    gridres_ratio_limits
        gridres_ratio

*map_isgridintersec*
*map_getgridcrop*
*gridres_ratio*
    checkdbres
        setovFac


1) Basics
INT_L1DA1B
    use INT_I0B
INT_FINDX
    use INT_L1D0
GETNBPTS #defined in mod_gridres)
OVMAP_GETXLFIH

xyfll0
llfxy0
rpngrid_rotll_tllfrll

map_getperimxy
map_keepinerpoints2
map_perim2crop
gridres_pointslist
map_gridsplit
src2dst_missing

2) Step 2
map_getllfxy
map_getxyfll
oversample

3) Step 3
map_getxy

4) step 4
map_isgridintersec0
    use map_isgridintersec
map_getgridcrop
    use map_getgridcrop_multi
        (use map_isgridintersec)
gridres_ratio_limits
    use gridres_ratio
src2dst_nearest
src2dst_collect
src2dst_maxindex
    use map_getpts_in_ijtile

5) Step 5
checkdbres ->  setovFac
src2dst_loop

==== Test Grids ====

Res: 1km, 5km, 20km
Proj: PS, Mercator (L-rot), LaLo
Size: 75x50, 750x500
Locations:
- England: a few grids around 0deg
- Poles (North and south)
- Date Line
- South Africa

==== Test Done ====

1) map_gridres fn

gridres_ratio
    Problems seen.
    List main problems here: [Pending]
    Depends on
    - map_getxy... [need testing]
      A difference is seen in if ezscintonly=.T. or .F. [Need a fix]
    - gridres_pointslist [need testing]
    - GETNBPTS [need testing]
    - ij0n... intersection domain, obtained by 'map_getgridcrop...' [need testing]

gridres
    Problems seen.
    List main problems here: [Pending]
    Depends on
    - map_getxy [see gridres_ratio comments]
    - gridres_pointslist  [see gridres_ratio comments]
    - distll... [need testing]
    - GETNBPTS [see gridres_ratio comments]

Main problems from a 1st look:
    - the ratio must be computed on common sub domain
    - that sub-domain must not cross a border... multi-crop is there for that
    - EZscint et Own s/r for grid mapping does not give same resutls
      is it just a cyclic convention difference
      or is it a bug in one of the 2
    - gridres and ratio at poles (close to) should be checked more carefully
    - ratio based on gridpts dist between cylindrical/azymutal proj are "imprevisible" close to where deformation is max (poles for cylindrical... equator for azymutal)

Must check
    - mapping
    - res & ratio algorythm for poles, equator... (must implement "grade fou")
    - distll

2) modules needed for map_gridres fn

