README

---------------------------------
| MARBL Developers Mailing List |
---------------------------------

You can join the MARBL developers mailing list at

https://groups.google.com/forum/#!forum/marbl-dev

-----------------------
| MARBL Documentation |
-----------------------

MARBL documentation is compiled by sphinx and hosted by readthedocs.io.
It can be found on the web at

https://marbl.readthedocs.io/en/latest/

---------------
| About MARBL |
---------------

The MARine Biogeochemistry Library (MARBL) is organized as follows:

    MARBL
    ├── MARBL_tools                   Python scripts to help GCMs configure MARBL
    ├── autogenerated_src
    ├── docs                          Documentation
    │   └── src                       RestructedText files (converted to HTML via sphinx)
    ├── include                       Subdirectories contain default location for module files
    |   |                             to be included when linking the MARBL library
    |   |                             * subdirectories for each compiler / MPI option
    │   ├── cray
    │   ├── gnu
    │   ├── gnu-mpi
    │   ├── intel
    │   ├── intel-mpi
    │   ├── nag
    │   ├── nag-mpi
    │   ├── pgi
    │   └── pgi-mpi
    ├── lib                           Default location of libmarbl.a (or libmarbl-[compiler].a)
    ├── src                           Source code for MARBL library (Fortran)
    └── tests
        ├── bld_tests                 Test the MARBL build system
        |                             (library build as well as fortran driver executable)
        ├── driver_exe                Default location for marbl.exe (or marbl-mpi.exe)
        ├── driver_src                Fortran source code for the stand-alone driver used
        |                             by the test system (calls into MARBL library)
        ├── input_files               Input files for regression tests
        ├── obj                       Subdirectories contain default location for object files
        |   |                         * subdirectories for each compiler / MPI option, which are
        |   |                           then further divided to separate stand-alone driver objects
        |   |                           from library objects
        │   ├── cray
        │   │   └── driver
        │   ├── gnu
        │   │   └── driver
        │   ├── gnu-mpi
        │   │   └── driver
        │   ├── intel
        │   │   └── driver
        │   ├── intel-mpi
        │   │   └── driver
        │   ├── nag
        │   │   └── driver
        │   ├── nag-mpi
        │   │   └── driver
        │   ├── pgi
        │   │   └── driver
        │   └── pgi-mpi
        │       └── driver
        ├── python_for_tests          Python modules for code that is used by multiple test
        |                             scripts. E.g. routines to parse command line arguments,
        |                             build the library, or load modules on supported machines
        ├── regression_tests          Tests that produce output with various MARBL configurations
        │   |                         so developers can quickly check the effect of new code
        │   ├── gen_input_file        Generate a valid input file
        │   ├── init                  Run initialization
        │   ├── init-twice            Initialize, finalize, and initialize again
        |   |                         * Ensures memory is deallocated correctly in finalize
        │   ├── requested_diags       List all diagnostics being provided by MARBL
        │   ├── requested_forcings    List all forcing fields MARBL requests from GCM
        │   ├── requested_restoring   List all tracers MARBL will apply restoring to
        │   └── requested_tracers     List all tracers MARBL will provide tendencies for
        └── unit_tests                Tests that check the functionality of small pieces of the code
            ├── get_put               Make sure parameters are registered correctly for
            |                         get_setting() and put_setting()
            └── utils_routines        Make sure all tools provided in marbl_utils_mod.F90
                                       what they claim to do (esp. tests edge cases)