BISICLES documentation

User documentation

There is a modest collection of documentation which aims to show how to build and run BISICLES, and to select run-time options. Most of it will make more sense in the context of the published papers: to begin with we suggest Cornford, Martin et al, The Cryosphere, 9, 1579-1600, 2015 , which describes the steps needed to run realistic problems, tuned to modern satellite and airborne observations.
  1. Building and running BISICLES
    1. Generic instructions
    2. Site specific notes
    3. Common issues
  2. BISICLES executables
    1. driver - used to run ice sheet simulations
    2. solverBenchmark - used to run the ice velocity solver from the main code as a standalone solver
    3. file tools, used to perform miscellaneous actions on BISICLES hdf5 files
    4. cdriver interface, used to control BISICLES from an external C or FORTRAN program
  3. Run-time options. driver, solverBenchmark, and the cdriver interface share many of their run-time options.
    1. Run-time configuration, input, output, and checkpoints
    2. Ice sheet geometry: specifying the initial ice thickness and bedrock elevation, plus boundary conditions for geometry and velocity.
    3. Stresses (in-ice and basal): specifying the stress model components.
    4. Thermodynamics : initial state and evolution of the internal energy density (temperature and water fraction)
    5. Calculation of the ice velocity, includes both forward and inverse problems.
    6. Surface fluxes (accumulation, ablation, energy balance, bedrock uplift)
    7. LevelData interface, used to load meshed data, for example thickness and topography
    8. Python interface, used to compute data 'on the fly' with simple formulae
  4. Example applications
    1. Frank Pattyn's MISMIP3D
    2. A Pine Island Glacier example which uses real topography and thickness data. Includes an example inverse problem which estimate model coefficients to match observed speed
  5. Viewing and analyzing data
    1. Viewing data with visit
    2. Analyzing data with R, MATLAB, Python, etc

Developer documentation

Developer documentation is included with the source distribution, and it makes sense to read Cornford, Martin et al, J. Comp. Phys, 232, 529-549, 2013. Developers will need to be familiar with C++ and Chombo. The code is documented using doxygen: if you have doxygen and graphviz installed it can be generated by running the command 

> cd path-to-bisicles/code
> make doxygen

which will produce html files in path-to-bisicles/code/doc/doxygen/html/index.html. There are also some design document .tex files, in path-to-bisicles/code/doc. Assuming you have latex installed, pdf files can be created by running. 

> cd path-to-bisicles/code
> make doc

There are also some tests that developers need to be aware of:

  • Unit tests: a few tests of individual components.
  • Regression tests: tests of the code as a whole