texample-component.txt - pism - [fork] customized build of PISM, the parallel ice sheet model (tillflux branch)
 (HTM) git clone git://src.adamsgaard.dk/pism
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) LICENSE
       ---
       texample-component.txt (2413B)
       ---
            1 .. include:: ../global.txt
            2 
            3 .. default-role:: literal
            4 
            5 .. _sec-writing-pism-components:
            6 
            7 Adding a new PISM component
            8 ===========================
            9 
           10 This section describes the implementation of a simple ocean model component.
           11 
           12 Most of PISM's sub-models are derived from the abstract class `Component`. This class
           13 contains data members used in most sub-models and defines a common interface.
           14 
           15 Each sub-model has to be able to do the following.
           16 
           17 #. Initialize using an input file.
           18 
           19    This can be trickier than you would think, especially when implementing a
           20    *time-stepping* model.
           21 
           22    As mentioned elsewhere in this manual, PISM supports two kinds of initialization:
           23 
           24    #. Re-starting from the model state saved by PISM.
           25    #. Initializing from a possibly incomplete model state using heuristics to replace
           26       missing data. (This is what we call "bootstrapping".)
           27 
           28    In both cases the user can choose to read a part of the model state from a different
           29    file, interpolating from a different grid if necessary (this is what we call
           30    "regridding").
           31 
           32    All components need to support both kinds of initialization as well as regridding.
           33 
           34    .. note::
           35 
           36       When the grid chosen for a given simulation matches the one in the input file
           37       *re-starting* using the command-line option `-i input.nc` has to produce a model
           38       state equivalent to the one obtained using *bootstrapping* followed by *regridding*:
           39       `-i input.nc -bootstrap -regrid_file input.nc`.
           40 
           41    Getting initialization right is especially challenging in sub-models using time steps
           42    different from PISM's mass-continuity time step. See `pism::earth::LingleClark` for an
           43    example of a model like this.
           44 
           45    Each new component should have a regression test ensuring that it can be stopped and
           46    re-started without affecting results. Add an initialization method setting the state of
           47    the model using provided `IceModelVec` instances: this makes writing such test much
           48    easier.
           49 
           50 #. Save its model state to an output file.
           51 
           52    To avoid a performance penalty when saving to a NetCDF-3 file this is performed in two
           53    steps:
           54 
           55    #. Define NetCDF variables, creating the file structure.
           56    #. Write data to the file.
           57 
           58 #. Time-stepping sub-models need to provide the maximum allowable time step length at a
           59    given model time.
           60 
           61 #. Provide lists of spatially-variable and scalar (time-series) diagnostics.
           62 
           63 FIXME: add more content.