These instructions assume the machine you're using has already installed all the necessary software such as fortran compilers, MPI libraries, netcdf libraries, pnetcdf libraries, etc. See Configuration Management for a list of necessary software to build/run ACME.
Installing on a supported cluster.
If you intend to do E3SM development, you should instead follow steps 1-12 in the Development Getting Started Guide and return to step 7 here.
These steps assume you are a member of the E3SM project. Check the Configuration Management page to see if your machine is supported.
- Sign up for a free account at http://github.com
Email James Foucar (jgfouca@sandia.gov) and ask to be added to the E3SM private organization on github. Include your Confluence account name so he can verify you're a member of ACME.
Log on to the platform on which you want to run E3SM.
- Install an ssh key from that platform to your github account. See these instructions and note you can skip step 2 if you already have an ssh key on your machine.
- Clone the repository to your local account with: git clone --recursive git@github.com:E3SM-Project/E3SM.git This will create a directory called "E3SM" with the code.
- cd to the E3SM directory.
- OPTIONAL When running with an MPAS component: Currently (until a better solution is found), it's useful to go into the components/mpas-source/src/core_ocean directory and run the two scripts get_cvmix.sh and get_BGC.sh to download those libraries so they are later replicated by the case creation process below. It's not required, but will bypass some credential entry during later builds.
- You are now ready to create a case, build and run following the CIME quick guide. By default, you will be running the latest version of "master".
Installing on an un-supported cluster.
Follow steps 1-6 above. If you want to make it supported, treat the steps as code development (done on a branch) following the Development Getting Started Guide. You first have to tell the CIME case control system about your machine. Complete instructions are in CIME Porting Guide and summarized here.
- Add your machine to <E3SM>/cime/config/e3sm/machines/config_machines.xml where <E3SM> refers to the repository root.
- The easiest approach is probably to copy the configuration for some other machine and then replace all the values
- Choose a directory to serve as the inputdata store called DIN_LOC_ROOT in config_machines.xml. Ideally, this should be readable by all E3SM developers on your platform.
- Most of the values should be obvious. You can look at the "userdefined" block to see which items are required and to see documentation on each item.
- Add compiler-specific information for each compiler supported by your machine to <E3SM>/cime/config/e3sm/machines/config_compilers.xml
- Here, for each compiler you want to support, you'll need to create a block <compiler COMPILER="<toolset>" MACH="<machine>">
- This block will inherit the properties of the primary block for that toolset and allow you to add/override values for your machine.
- The most common thing you'll need to do is add link flags with the ADD_SLIBS item.
- You may also need to define NETCDF_PATH and PNETCDF_PATH
- Add batch settings for your machine by editing <E3SM>/cime/config/e3sm/machines/config_machines.xml
- Machines with similar batch systems should serve a good example of what to add.
- If you need a batch system that doesn't exit or special settings, you may have to edit <E3SM>/cime/config/e3sm/machines/config_batch.xml
- You may need to add a machine specific section in config_batch.xml that inherits from the global section for a specified batch system (e.g., pbs).
- In certain special cases, you may wish to add/edit <E3SM>/cime/config/e3sm/machines/Depends.<platform>.<compiler> to tweak compilation options for specific files.
- Verify the install is working by building and running a simple X case.
- <E3SM>/cime/scripts/create_newcase --case <yourcasename> --compset X --res f19_g16 --mach <yourmachine>
- If the X case works, try more complex cases.
- <E3SM>/cime/scripts/create_newcase --case <yourcasename> --compset I1850CLM45CN --res f09_g16 --mach <yourmachine>
- <E3SM>/cime/scripts/create_newcase --case <yourcasename> --compset FC5 --res ne30_ne30 --mach <yourmachine>
- If you have more then one compiler, add -compiler <compiler> to the above.
- The above should run for 5 days successfully.