Introduction to CISM code base

From Interactive System for Ice sheet Simulation
Jump to: navigation, search

CISM coding style

CISM is written almost entirely in Fortran 90 and makes extensive use of "modules" in an attempt to parcel off related pieces of the code and box them up into relatively self contained units. Larger pieces of code are then constructed by accessing the relevant parts of different modules (variables, subroutines, functions, etc.) through the "use" statement.

Newer parts of CISM attempt to follow the general coding style used in most other components of the Community Earth System Model (see the talks and exercises on Thursday for more discussion). In general, there are three parts to any procedure that one might want to implement or add to the code:

  1. an initialization step
    1. allocate arrays, variables
    2. define constants
    3. read input
    4. anything else that only needs to be done once, at the start of the procedure
  2. a call to a "driver" subroutine
    1. pass relevant arguments from the main code to the procedure
    2. do the procedure
    3. pass the results back out to the main code
  3. a finalization step
    1. de-allocate arrays, variables
    2. write output

In the third exercise you will work through a detailed example that should give you a better feel for this process.

To give you a very generic feel for which modules control the important parts of the code, refer to the following list.

example-drivers/simple_glide/src/ simple_glide.F90 - high level time stepping driver subroutine; contains primarily calls to driver subroutines in glide.F90
:
libglide/ glide_types.F90 - general model data structure and default settings for run time parameter settings
libglide/ glide_setup.F90 - configuration file parser
libglide/ glide.F90 - module containing most high level calls to subroutines dealing with glacier thermodynamics (heat, momentum, and mass conservation)
:
libglide/ glide_temp.F90 - module containing most driver and work subroutines dealing with heat balance calculation
:
libglide/ isostasy.F90 - module containing most driver and work subroutines dealing with isostasy calculation
:
libglide/ glam.F90 - module containing high level driver subroutines for HO momentum balance and thickness evolution using incremental remapping
libglide/ fo_upwind_advect.F90 - module containing high level driver subroutines for HO momentum balance and thickness evolution using first-order upwinding
libglide/ glide_velo_higher.F90 - module containing driver subroutines for HO momentum balance calculations
libglide/ glam_strs2.F90 - module containing work subroutines for HO momentum balance calculation
libglide/ remap_glamutils.F90 - module containing driver subroutines for thickness evolution using incremental remapping
:
libglimmer/ glimmer_physcon.F90 - physical constants  (e.g. flow law rate factor, power-law exponent)
libglimmer/ glimmer_paramets.F90 - other model parameters, such as scales for non-dimensionalization

Flow diagram I

Conceptual description of code linkages necessary to build the executable file simple_glide. Black ".F90" text denotes actual file names (most live in the libglide/ subdirectory) where various subroutines live (shown in red) and where calls to other subroutines (shown in green) are made. Arrows denote dependency on subroutines in other modules, which are generally accessed through the Fortran "use" statement. For example, simple_glide.F90 contains a call to evolve the temperature. The subroutine being called lives in glide.F90. In turn, that subroutine makes a call out to a driver subroutine that lives in glide_temp.F90, which may have further dependencies in other modules (indicated by the "..."). A similar figure with specific subroutine calls can be found here.

Simple glide flow generic.png

Flow diagram II

Conceptual description of code linkages necessary to build the executable file simple_glide. This version follows that given above but uses the actual subroutine names (for example, glide_tstep_p1 deals with temperature evolution, glide_tstep_p2 deals with the momentum balance and thickness evolution, and glide_tstep_p3 deals with the isostasy calculation). Black ".F90" text denotes actual file names (most live in the libglide/ subdirectory) where various subroutines live (shown in red) and where calls to other subroutines (shown in green) are made. Arrows denote dependency on subroutines in other modules, which are generally accessed through the Fortran "use" statement. For example, simple_glide.F90 contains a call to glide_tstep_p1, which lives in glide.F90. In turn, glide_tstep_p1 makes a call out to glide_temp_driver, which lives in glide_temp.F90. In turn, the subroutine glide_temp_driver may have further dependencies in other modules (indicated by the "...").

Simple glide flow specific.png