======================= Repository Descriptions ======================= | The MPAS project contains several repositories. Some of the repositories are private for development efforts while some are public for users and releases. These repositories are described below. | | Main Development/Release ======================== The main MPAS repositories are described in this section. Users interested in implementing a new feature only need to interest themselves in the "MPAS-Release" section below. | MPAS ---- *Private repository* The `main MPAS development repository `_ is where the majority of MPAS development occurs. Instructions on using it to add a feature are in the "Forks" section in `Development <./development.html>`_. This is a private repository for development efforts. | MPAS-Legacy ----------- *Private repository* The `MPAS-Legacy repository `_ provides a linear history of the previous SVN repository's *trunk/mpas* directory. It is provided only for debugging purposes and no development should/will be carried out using it. | MPAS-Release ------------ *Public repository* Users should refer to the `main MPAS release repository `_ for bug fixes, issues, and major releases for MPAS. Users who wish to implement a new feature, and have that feature merged into the MPAS repository should follow the instructions on code requirements and repository layout as an MPAS developer would. Forks should be made of this release repository for this type of development rather than the MPAS developer repository. New features will undergo a code review before any merge onto the release repository. | Layouts ------- The MPAS, MPAS-Release, and MPAS-Legacy repositories are all laid out as follows. .. code-block:: | - Makefile \ - src | - driver | - registry | - framework | - operators | - external | - inc | - core_* \ - Makefile | Although there are more files/directories than are listed, these are the relevant directories for source code modifications, with their descriptions below. | .. container:: row m-0 p-0 .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: src .. container:: card-body-def A directory containing all source code related to MPAS - whether or not it is shared | Shared parts of MPAS belong in either of the following directories: .. container:: row m-0 p-0 .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: registry .. container:: card-body-def The registry contains the parsing code for **Registry**, which is used for easy modification of variables within a specific MPAS core. Each core has its own *Registry.xml* file which defines a list of dimensions, namelist options, variables, and other information specific to that core. During compilation, the registry parser (*parse*) is built. This parser then parses the *Registry.xml* file and generates some Fortran code, which is stored in *src/inc*. It is then included at various places within *framework* to define all of the necessary things. The code generated from *registry* defines the domain structure for a core, and routines associated with building the domain. Domains are discussed in `Development Guidelines <./dev_guidelines.html>`_. .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: driver .. container:: card-body-def A directory containing general code for building the MPAS executable, and the general structure of an MPAS executable .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: external .. container:: card-body-def A directory containing code to MPAS, that is used within MPAS, i.e. ESMF time keeping routines .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: framework .. container:: card-body-def A directory containing shared code related to the framework of MPAS - this includes the I/O layer, communication routines, and definitions of the data types .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: operators .. container:: card-body-def A directory containing shared code used for computing specific quantities on an MPAS grid. This includes radial basis function interpolation .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: inc .. container:: card-body-def An empty staging directory that *registry* fills at compile time | Non-shared parts of MPAS belong under the remaining directories. As an example, the core *sw* directory represents the shallow water dynamic core within the MPAS framework. Other directories named *core* are either dynamical cores, or parts of other dynamical cores. Most developers will only work under their specific core directory, and should not modify code in another core without permission. | | MPAS-Testing ============ *Private repository* The `MPAS-Testing repository `_ contains software to setup and run MPAS test cases. | Layout ------ The MPAS-Testing repository is laid out as follows. .. code-block:: MPAS-Testing | -- sw (test cases for Shallow Water core) | -- ocean (test cases for Ocean core) | -- atmosphere (test cases for Non-hydrostatic Atmospheric core) \ -- shared (test cases for shared parts of MPAS) | | MPAS-Documents ============== *Private repository* The `MPAS-Documents repository `_ contains all MPAS-related documents. This includes design documents, users guides, developers guides, etc. | Layout ------ The MPAS-Documents repository is laid out as follows. .. code-block:: MPAS-Documents | -- design_documents | | -- shared (design documents for project in shared directory) | | -- sw (design documents for Shallow Water core) | | -- ocean (design documents for Ocean core) | | -- atmosphere (design documents for Non-hydrostatic Atmosphere core) | -- users_guide | | -- shared (shared parts of the users guide) | | -- sw (Shallow Water-specific parts of the users guide) | | -- ocean (Ocean-specific parts of the users guide) | | -- atmosphere (Non-hydrostatic Atmosphere- specific parts of the users guide) \ -- developers_guide (this document) | | MPAS-Tools ========== *Private repository* The `MPAS-Tools repository `_ contains all MPAS related tools | Layout ------ The layout of the MPAS-Tools repository is as follows: .. code-block:: MPAS-Tools | -- analysis (all tools related to analysis) | -- grid_gen (all tools related to grid generation) | -- python_scripts (all general purpose python scripts) \ -- visualization (all visualization tools) | To promote reuse of previously developed tools, tools are not stored in core specific directories. Developers are encouraged to browse other tools to determine if a feature is implemented elsewhere. | | MPAS-Data ========= *Public repository* The `MPAS-Data repository `_ contains data required to run specific MPAS models. This data does not include input files related to specific runs, it is intended to house general data that does not change between runs. | Layout ------ The layout of the MPAS-Data repository is as follows: .. code-block:: MPAS-Data | -- framework (data required for parts of framework) | -- operators (data required for parts of operators) \ -- core_* (Data required for specific cores) | | | | |