Annotation of /MITgcm_contrib/high_res_cube/matlab-topology-generator/README

Matlab code to generate topology description for MITgcm cs6 conventions.

o To run start matlab and execute script driver.m
o To set sizes edit lines in driver.m
    Settings nr, ng, nb are index space sizes for cube grid. These are the
    number of points normal to the red, green and blue circumferences
    of a cube. Note - nr, ng and nb do not have to equal, however the
    current physical grid generation software assumes they
    are equal.
    Settings tnx and tny are the tile sizes ( these correspond to 
    snx and sny in SIZE.h ). tnx and tny must subdivide nr, ng and nb
    exactly.
    The product nsx*npx from SIZE.h needs to equal the number of 
    tiles created by driver.m

The key output from this code is a Fortran header file W2_EXCH2_TOPOLOGY.h
and one or more Fotran files called e2setup*.F. These are written
by exch2_setup_cs6_print.m. The header file contains the declarations
of the arrays used to describe the index space topology of the cube domain.
The e2setp*.F files contain the code to initialize these arrays. 
Two output options ( variable outmode ) are available in 
exch2_setup_cs6_print.m. One produces a single file e2setup.F with a driver 
routine that calls a setup routine for each tile. For large numbers of tiles 
this file can be huge and can cause some Fortran compilers (g77 certainly) to 
allocate ridiculous amounts of memory to parse this file. An alternate output 
mode produces one file for each tile initialization routine and one file 
"e2setup.F" for the driver.  This mode is kinder to the compiler but creates a 
visually annoying large number of source files (one for each tile).


File list
driver.m                                                :: Controls the topology generation
exch2_setup_cs6_domains.m                               :: Defines the cube faces (aka domains)
exch2_setup_cs6_get_external_neighbor_index_ranges.m    :: Figures out the index remapping operators
                                                        :: and index ranges for halo's between cube faces.
exch2_setup_cs6_get_external_neighbor_tiles.m           :: Figures out neighbor between domains for each tile.
exch2_setup_cs6_get_internal_neighbor_index_ranges.m    :: Figures out the index remapping operators
                                                        :: and index ranges for halo's within a cube face.
exch2_setup_cs6_get_internal_neighbor_tiles.m           :: Figures out neighbors with a domain for each tile.
exch2_setup_cs6_get_neighbor_domains.m                  :: Defines connectivity between domains.
exch2_setup_cs6_plot.m                                  :: Plots the tiles using the conventional cube
                                                        :: domain layout.
exch2_setup_cs6_print.m                                 :: Writes the Fortran code that defines the topology 
                                                        :: and that is linked with the model run.
exch2_setup_cs6_tiles.m                                 :: Builds lists of each tile and its location within
                                                        :: a domain and within the global index space.
1	cnh	1.1	Matlab code to generate topology description for MITgcm cs6 conventions.
2
3			o To run start matlab and execute script driver.m
4			o To set sizes edit lines in driver.m
5			Settings nr, ng, nb are index space sizes for cube grid. These are the
6			number of points normal to the red, green and blue circumferences
7			of a cube. Note - nr, ng and nb do not have to equal, however the
8			current physical grid generation software assumes they
9			are equal.
10			Settings tnx and tny are the tile sizes ( these correspond to
11			snx and sny in SIZE.h ). tnx and tny must subdivide nr, ng and nb
12			exactly.
13			The product nsx*npx from SIZE.h needs to equal the number of
14			tiles created by driver.m
15
16			The key output from this code is a Fortran header file W2_EXCH2_TOPOLOGY.h
17			and one or more Fotran files called e2setup*.F. These are written
18			by exch2_setup_cs6_print.m. The header file contains the declarations
19			of the arrays used to describe the index space topology of the cube domain.
20			The e2setp*.F files contain the code to initialize these arrays.
21			Two output options ( variable outmode ) are available in
22			exch2_setup_cs6_print.m. One produces a single file e2setup.F with a driver
23			routine that calls a setup routine for each tile. For large numbers of tiles
24			this file can be huge and can cause some Fortran compilers (g77 certainly) to
25			allocate ridiculous amounts of memory to parse this file. An alternate output
26			mode produces one file for each tile initialization routine and one file
27			"e2setup.F" for the driver. This mode is kinder to the compiler but creates a
28			visually annoying large number of source files (one for each tile).
29
30
31			File list
32			driver.m :: Controls the topology generation
33			exch2_setup_cs6_domains.m :: Defines the cube faces (aka domains)
34			exch2_setup_cs6_get_external_neighbor_index_ranges.m :: Figures out the index remapping operators
35			:: and index ranges for halo's between cube faces.
36			exch2_setup_cs6_get_external_neighbor_tiles.m :: Figures out neighbor between domains for each tile.
37			exch2_setup_cs6_get_internal_neighbor_index_ranges.m :: Figures out the index remapping operators
38			:: and index ranges for halo's within a cube face.
39			exch2_setup_cs6_get_internal_neighbor_tiles.m :: Figures out neighbors with a domain for each tile.
40			exch2_setup_cs6_get_neighbor_domains.m :: Defines connectivity between domains.
41			exch2_setup_cs6_plot.m :: Plots the tiles using the conventional cube
42			:: domain layout.
43			exch2_setup_cs6_print.m :: Writes the Fortran code that defines the topology
44			:: and that is linked with the model run.
45			exch2_setup_cs6_tiles.m :: Builds lists of each tile and its location within
46			:: a domain and within the global index space.