Some of the subdirectories in the ACME E3SM code contain code that was brought in from another repository. List them all.
Terms
- external any subdirectory in ACME E3SM whose entire content is from another repository
- upstream master the repository everyone is sending their changes to. Only one so that everyone pulling from the same source is working with all the same changes. The source of an external.
Methods for including externals
- submodule a link that points to another git repository. See Sharing External Code using Git Submodules . Submodules require an extra step after cloning to get the code.
- recursive submodule: a submodule that is inside another submodule.
- subtree a set of files and commits from another git repo, brought in to your repo so that it looks like original content. See Sharing External Code using Git Subtree. Subtrees are included in ACME when you "git clone".monorepo adding multiple projects, related or not, in the same repo. Code is included when you clone ACME
- monorepo the entire repo is added once (usally with subtree) and developed within E3SM. Might maintain a separate build/test system.
- buildtime the repo is checked out to the $CIME_OUTPUT_ROOT/$CASE/bld when compiling a case for the first time. Code does not exist in ACME E3SM repo.
Rules for adding externals
- Group leads must approve adding a new external. The group needing the external can decide on the method of inclusion. A POC for the upstream master must be identified and the SE IG group leads notified.
- The upstream master for the external must be build-able and testable on its own.
- For submodules, the linked repo must be readable by all ACME E3SM developers. If the upstream master can not be made readable, a fork must be maintained in ACMEE3SM-Climate Project github and ACME E3SM then links to that fork.
Development in externals
In general, there are several ways to develop with external code in ACME
- strict 1-way: all development is merged to the upstream master first and flows down to ACMEE3SM. No exceptions.
- mostly 1-way: prefer strict 1-way but some exceptions can be made for emergency fixes
- 2-way: developers can make changes in ACME E3SM or the upstream master. POC keeps them in sync.
More specific instructions for externals are below. NOTE: a commit should never mix external and non-external code.
Table of Externals currently in ACME
| Name | Subdirectory in ACME | external method | upstream master | development method | POC | Notes | ||
|---|---|---|---|---|---|---|---|---|
| CIME | cime | subtree | https://github.com/ESMCI/cime | 2-way | ||||
| MCT | cime/externals/MCT | subtree | https://github.com/MCSclimate/MCT | mostly 1-way | usually brought in with CIME | |||
| PIO | cime/externals/pio* | subtree | https://github.com/NCAR/ParallelIO | mostly 1-way | usually brought in with CIME | |||
| MPAS-OceanSCORPIO | components/mpas-o/model externals/scorpio externals/scorpio_classic | submodule | https://github.com/MPAS-Dev/MPAS forked to https://github.com/ACME-Climate/MPAS /E3SM-Project/scorpio | strict 1-way | Jayesh Krishna | E3SM uses this and ignores cime/externals/pio | ||
| Kokkos | externals/kokkos | submodule | git@github.com:E3SM-Project/kokkos.git branch e3sm/kokkos | strict 1-way | Mark PetersenJames Foucar | |||
| MPAS-Land IceSource | components/mpasli/modelmpas-source | submodule | https://github.com/MPAS-Dev/MPAS forked tohttps://github.com/ACME-Climate/MPAS-Model | strict 1-way | MPAS-Ocean, Seaice and land ice all use code from here. | |||
| RRTMGP | components/cam/src/physics/rrtmgp/external | submodule | git@github.com:RobertPincus/rte-rrtmgp.git branch develop | strict 1-way | Matt Hoffman | MPAS-Sea IceBen Hillman | ||
| COSP2 | components/mpas-cice/model/cam/src/physics/cosp2/external | submodule | https git@github.com:CFMIP/ /github.com/MPAS-Dev/MPAS forked toCOSPv2.0.git branch CESM_v2.1.4 | strict 1-way | ||||
| MPP | components/clm/src/external_models/mpp | submodule | https://github.com/ACMEMPP-ClimateLSM/MPASMPP branch cicealm/develop | strict 1-way | Adrian TurnerGautam Bisht | |||
| FATES | components/clm/src/external_models/fates | submodule | forked to https://github.com/ACME-Climate/fates | strict 1-way | ||||
| MPPSBETr | components/clm/src/external_models/mppsbetr | submodule | https://githubgit@github.com/ACME-Climate/mpp branch alm/develop:BeTR-biogeochemistry-modeling/sbetr.git | strict 1-way | Gautam Bisht | |||
| CVMix | NA | buildtimecomponents/mpas-source/src/core_ocean/cvmix | rescursive submodule | https://github.com/CVMix/CVMix-src | strict 1-way | ? | After case.build, can be found in$EXEROOT/ocn/sourceJon Wolfe | used to be not in-source and fetched at build time. |
| ocean BGC | components/mpas-source/src/core_ocean/.cvmix_allocean BGC | NA | buildtimerecursive submodule | https://github.com/ACMEE3SM-ClimateProject/Ocean-BGC | strict 1-way | ? | After case.build, can be found in $EXEROOT/ocn/source/core_ocean/.BGC_all |
...
| Jon Wolfe | used to be not in-source and fetched at build time. |
Externals planned for E3SM
| Name | Subdirectory in ACME | external method | upstream master | development method | POC | Notes | ||||
|---|---|---|---|---|---|---|---|---|---|---|
| CICE column physics | TBD | TBD | ? | ? | ? | sBeTR for land model | components/clm/src/external_models/sbetr | submodulehttps://github.com/ACME-Climate/sbetr | ||
| strict 1-way | Gautam Bisht | GCAM | TBD | submodule? | https://github.com/JGCRI/gcam-core | strict 1-way | Katherine Calvin (Unlicensed) |
Specific external development instructions
CIME:
Code location: ACME E3SM/cime
Any code development in ACMEE3SM/cime/config/acme can be committed directly to ACME E3SM through the normal PR process.
Code development in other parts of CIME should be committed first with a PR in https://github.com/ESMCI/cime. It will be then brought to ACME E3SM by a subtree merge as in Maintaining the CIME subtree in ACME.ACME staff can report any bugs in CIME at https://github.com/ACME-Climate/ACME/issues. SE/CPL staff may open a companion report at
Report issues about the Case Control System, driver or coupler directly to https://github.com/ESMCI/cime/issues. ACME cime bugs which have been fixed in ESMCI and are waiting a subtree merge will have the github label "Fixed in ESMCI" attached to them.
...
. config file issues can be reported to E3SM gitub.