README.md

   1 \page rm General Project Information
   2 # Modeling Framework: Flexible Modeling System (FMS)
   3
   4 Today’s climate models simulate highly complex systems. In response to
   5 increasingly complex models, the climate community has developed tools and
   6 methodologies to facilitate the modeling process and many common tasks (e.g.,
   7 calendar management, grid generation, I/O). Such frameworks come with a number
   8 of advantages, including decreased model development time and increased
   9 compatibility of interfaces.
  10
  11 The Flexible Modeling System (FMS) is a software environment that supports the
  12 efficient development, construction, execution, and scientific interpretation of
  13 atmospheric, oceanic, and climate system models. This framework allows
  14 algorithms to be expressed on a variety of high-end computing architectures
  15 using common and easy-to-use expressions of the underlying platforms, spanning
  16 distributed and shared memory, as well as high-performance architectures.
  17 Scientific groups at GFDL can develop new physics and new algorithms
  18 concurrently, and coordinate periodically through this framework.
  19
  20 ![FMS Framework](docs/images/FMS.gif)
  21
  22 Modeling frameworks for the construction of coupled models, made from
  23 independent model components, are now prevalent across this field. FMS was one
  24 of the first frameworks to be developed — since the advent of the Cray T3E in
  25 1998 — and is still in use and under development today, using new architectures
  26 and new algorithms.
  27
  28 ## What is FMS
  29
  30 The Flexible Modeling System (FMS) is a software framework for supporting the
  31 efficient development, construction, execution, and scientific interpretation of
  32 atmospheric, oceanic, and climate system models.  FMS consists of the
  33 following:
  34
  35 1. A software infrastructure for constructing and running atmospheric, oceanic,
  36 and climate system models. This infrastructure includes software to handle
  37 parallelization, input and output, data exchange between various model grids,
  38 orchestration of the time stepping, makefiles, and simple sample run scripts.
  39 This infrastructure should largely insulate FMS users from machine-specific
  40 details.
  41 2. A standardization of the interfaces between various component models
  42 including software for standardizing, coordinating, and improving diagnostic
  43 calculations of FMS-based models, and input data preparation for such models.
  44 Common preprocessing and post-processing software are included to the extent
  45 that the needed functionality cannot be adequately provided by available
  46 third-party software.
  47 3. Contributed component models that are subjected to a rigorous software
  48 quality review and improvement process. The development and initial testing of
  49 these component models is largely a scientific question, and would not fall
  50 under FMS. The quality review and improvement process includes consideration of
  51 (A) compliance with FMS interface and documentation standards to ensure
  52 portability and inter-operability, (B) understandability (clarity and
  53 consistency of documentation, comments, interfaces, and code), and (C) general
  54 computational efficiency without algorithmic changes.
  55 4. A standardized technique for version control and dissemination of the
  56 software and documentation.
  57
  58 FMS does not include the determination of model configurations, parameter
  59 settings, or the choice amongst various options. These decisions require
  60 scientific research. Similarly, the development of new component models is a
  61 scientific concern that is outside of the direct purview of FMS. Nonetheless,
  62 infrastructural changes to enable such developments are within the scope of FMS.
  63 The collaborative software review process of contributed models is therefore an
  64 essential facet of FMS.
  65
  66 ## Dependencies and installation
  67
  68 The following external libraries are required when building libFMS
  69
  70 * NetCDF C and Fortran (77/90) headers and libraries
  71 * Fortran 2003 standard compiler
  72 * Fortran compiler that supports Cray Pointer
  73 * MPI C and Fortran headers and libraries (optional)
  74 * Libyaml header and libraries (optional)
  75 * Linux or Unix style system
  76
  77 Please see the [Build and Installation page](http://noaa-gfdl.github.io/FMS/build.html)
  78 for more information on building with each build system.
  79
  80 ## Compiler Support
  81
  82 For most production environments and large scale regression testing, FMS is currently compiled with the
  83 Intel classic compiler (ifort) but will be transitioning to the llvm-based ifx intel compiler when it is
  84 available for production.
  85
  86 Below shows the status of our compiler support for various compilers and versions. Testing was done on
  87 CentOS 8, with additional testing using a larger cray SLES system. MPICH is used as the MPI library
  88 except for the intel compilers, which use intel's mpi library.
  89 Compilers used in our Github continuous integration testing are in bold.
  90
  91 |Compiler                | Version |Builds Successfully        | Unit Testing        |
  92 |------------------------|---------|---------------------------|---------------------|
  93 |**intel classic(ifort)**| 2021.6.0| yes                       | passes              |
  94 |**GNU (gfortran)**      | 9.3.0   | yes                       | passes              |
  95 |intel oneapi (ifx)      | 2021.6.0| yes                       | passes              |
  96 |GNU (gfortran)          | 11.2.0  | yes                       | passes              |
  97 |HP/Cray (cce)           | 9.1.1   | yes                       | not passing         |
  98 |Nvidia/PGI(nvfortran)   | 22.9    | no                        | not passing         |
  99 |AMD (aocc)              | 3.2.0   | no(compiles,fails to link)| not passing         |
 100
 101 ## Documentation
 102
 103 Source code documentation for the FMS code base is available at http://noaa-gfdl.github.io/FMS.
 104 The documentation is generated by doxygen and updated upon releases, and a copy of the site
 105 can be obtained through the `gh-pages` branch or generated manually with
 106 `./configure --enable-docs && make -C docs`. For more information on documentating the code
 107 with doxygen please see the
 108 [documentation style guide](http://noaa-gfdl.github.io/FMS/md_docs_doxygenGuide.html).
 109
 110 # Disclaimer
 111
 112 The United States Department of Commerce (DOC) GitHub project code is provided
 113 on an 'as is' basis and the user assumes responsibility for its use. DOC has
 114 relinquished control of the information and no longer has responsibility to
 115 protect the integrity, confidentiality, or availability of the information. Any
 116 claims against the Department of Commerce stemming from the use of its GitHub
 117 project will be governed by all applicable Federal law. Any reference to
 118 specific commercial products, processes, or services by service mark,
 119 trademark, manufacturer, or otherwise, does not constitute or imply their
 120 endorsement, recommendation or favoring by the Department of Commerce. The
 121 Department of Commerce seal and logo, or the seal and logo of a DOC bureau,
 122 shall not be used in any manner to imply endorsement of any commercial product
 123 or activity by DOC or the United States Government.
 124
 125 This project code is made available through GitHub but is managed by NOAA-GFDL
 126 at https://gitlab.gfdl.noaa.gov.