generated from MetOs-UiO/sphinx-docs-example
-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit 38dd0c8
Showing
551 changed files
with
154,613 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Sphinx build info version 1 | ||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
config: f4bfcdfaa7a3847ff5f3a6bc8681c486 | ||
tags: d77d1c0d9ca2f4c8421862c7c5a0d620 |
Empty file.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Contribution | ||
|
||
This documentation is not meant to be static and is a collaborative effort of the CTSM-Norway team. If you spot anything wrong or would like to add information to the documentation, please send us a pull request or file an issue in our [repository](https://github.com/MetOs-UiO/CTSM-Norway-Documentation). | ||
|
||
|
||
```{prereq} What do I need to contribute? | ||
1. Basic understanding of Git. | ||
|
||
2. You need to have [Sphinx](http://www.sphinx-doc.org) installed (as | ||
part of your Python environment installation). | ||
|
||
3. You need a [GitHub](https://github.com) account. | ||
``` | ||
|
||
## Locally build this page | ||
Before filling a pull-request you should check that the changes introduced by you still make the site build. Therefor, you should always [build and test locally](https://coderefinery.github.io/sphinx-lesson/contributing-to-a-lesson/#build-and-test-locally) before you ask for a pull request. | ||
|
||
### Usage | ||
|
||
How to automatically update the documentation locally during development: | ||
``` | ||
$[~/PROJECT_ROOT] sphinx-autobuild content/ _build | ||
``` | ||
|
||
The static webpage is hosted on Github and automatically builded with GitHub-Actions by pushing changes from the `main` to the `gh-pages` branch. The built web-page is displayed as the stuff build on the `gh-pages` branch. This process is automatic. A guide to the principles can be found [here](https://pythonrepo.com/repo/executablebooks-sphinx-autobuild-python-documentation). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Tips for developing CTSM | ||
|
||
## Local development with Docker | ||
Put in and improve the documentation from [this](https://github.com/sunnivin/docker-local-build-run-CTSM) repo. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,161 @@ | ||
# Get CTSM | ||
Dependent on what you want to do you might want to use different strategies for starting your CTSM work at the right place. | ||
|
||
```{keypoints} Path variables | ||
Throughout all this documentation we define some path variables: | ||
- `HOME`; your home directory on the computer you are currently working on (remote or local). Typically predefined on a Unix system. | ||
- `CTSM_ROOT`; the top folder or wherever you cloned CTSM | ||
``` | ||
|
||
|
||
## Supported machines | ||
This tutorial assumes that you are logged into one of the clusters of Sigma2. (See [here](https://metos-uio.github.io/CTSM-Norway-Documentation/prerequisite/#needed-accesses) for how to get cluster access). | ||
|
||
Currently (April 2023), we support machine configurations for: | ||
- saga (sigma2, Norway) | ||
- fram (sigma2, Norway) | ||
- betzy (sigma2, Norway) | ||
|
||
If your machine is not on the list and you would like us to support it, | ||
please contact us. | ||
|
||
## How to get CTSM (for users) | ||
A user is a person that runs CTSM without modifying the source code. To get the FATES EMERALD platform version, CLONE from NordicESM hub | ||
|
||
[~/HOME]$ git clone -b release-clm5.0 https://github.com/NordicESMhub/ctsm.git ${HOME}/ctsm_fates_emerald | ||
|
||
In this example, we are checking out the release-clm5.0 tag and create a | ||
new local branch (recommended). The destination of the `clone` is a | ||
directory (e.g. ctsm\_fates\_emerald) in our home directory. From now on, we will call this directory `CTSM_ROOT`. | ||
|
||
You can export this path as a variable for easier access in your workspace: | ||
|
||
[~/HOME]$ export CTSM_ROOT=${HOME}/ctsm_fates_emerald | ||
|
||
### How to get a specific branch | ||
Change into the created ctsm directory | ||
|
||
[~/HOME]$ cd $CTSM_ROOT | ||
|
||
Check all existing branches | ||
|
||
[~/CTSM_ROOT]$ git branch --all | ||
|
||
To check out the FATES EMERALD platform (in this example release 2.0.1) | ||
into a new local branch (e.g. new\_branch\_name) | ||
|
||
[~/CTSM_ROOT]$ git checkout release-emerald-platform2.0.1 -b new_branch_name | ||
|
||
For later reference, it is useful to choose new\_branch\_name according | ||
to function and include the version and your username, e.g. | ||
username\_release-emerald-platform2.0.1. | ||
|
||
Some components of CTSM are maintained and developed independently of the main model. We call these externals. | ||
To fetch the proper externals (CIME, FATES, etc.) run the below command from the main CTSM directory. | ||
|
||
[~/CTSM_ROOT]$ ./manage_externals/checkout_externals | ||
|
||
All should be set by this and you should be able to create your first case. | ||
|
||
|
||
## How to get CTSM (for developers) | ||
A developer is someone that wishes to change the source code of CTSM. | ||
Depending on which project you wish to contribute to you might want to | ||
start your development from different versions of CTSM. For the | ||
CLM-Norway team we have mainly two starting points: | ||
|
||
- The [NordicESM-hub](https://github.com/NordicESMhub/ctsm) (note | ||
that this is a project for developers in the Nordics) | ||
- The latest version of the original | ||
[CTSM](https://github.com/ESCOMP/CTSM) (this is the original | ||
version of CTSM developed by NCAR) | ||
|
||
### From the [NordicESM-hub](https://github.com/NordicESMhub/ctsm) | ||
|
||
Follow the steps [above](https://metos-uio.github.io/CTSM-Norway-Documentation/get/#how-to-get-ctsm-for-users), but `checkout` the fates\_emerald\_api instead | ||
|
||
[~/CTSM_ROOT]$ git checkout fates_emerald_api -b new_branch_name | ||
|
||
For later reference, it is useful to choose new\_branch\_name according | ||
to function and include the version and your username, e.g. | ||
username\_fates\_emerald\_api. After checking out the externals, change | ||
to cime directory and create your own branch to record all your changes | ||
|
||
[~/CTSM_ROOT]$ cd cime | ||
[~/CTSM_ROOT/cime]$ git checkout -b username_cime | ||
|
||
Change to fates directory and create your own branch to record all your | ||
changes | ||
|
||
[~/CTSM_ROOT/cime]$ cd ../src/fates | ||
[~/CTSM_ROOT/fates]$ git checkout -b username_fates | ||
|
||
If you do not create your own branch for `cime` and `fates`, running | ||
`./manage_externals/checkout_externals` will overwrite your | ||
previous `cime` and `fates`. You should now be ready to create your | ||
first case. | ||
|
||
### From the latest version of [CTSM](https://github.com/ESCOMP/CTSM) | ||
Start from your home folder and clone CTSM from ESCOMP | ||
|
||
[~/HOME]$ git clone --origin escomp https://github.com/ESCOMP/CTSM.git CTSM | ||
|
||
Change into the new directory | ||
|
||
[~/HOME]$ cd CTSM | ||
|
||
Create a local branch | ||
|
||
[~/CTSM_ROOT]$ git checkout master -b my_branch_name | ||
|
||
For later reference, it is useful to choose `my_branch_name` according | ||
to function and include the version and your username. | ||
|
||
To fetch the proper externals (CIME, FATES, etc.) run | ||
|
||
[~/CTSM_ROOT]$ ./manage_externals/checkout_externals | ||
|
||
#### Porting of cime | ||
|
||
Now you need to add machine specifics for the Norwegian clusters. This | ||
can be done in two ways (check the | ||
[original](https://esmci.github.io/cime/versions/master/html/users_guide/porting-cime.html#steps-for-porting) | ||
documentation for a detailed explanation): | ||
|
||
|
||
##### 1) Create a .cime folder (not recommended right now) | ||
|
||
You can create a **.cime** folder with the machine configurations under your home directory. | ||
|
||
Clone [this](https://github.com/MetOs-UiO/dotcime) repository and | ||
consult the `README.md` file for the details when making a new | ||
case. | ||
|
||
|
||
##### 2) Checkout ccs_config_noresm from NorESMhub | ||
|
||
This is useful for anything based on CTSM(>dev120) or relies on cmeps>=0.14.13 (you can check this in Externals.cfg or by going to /component/cmeps and doing `git describe`). | ||
``` {keypoints} Important | ||
You should get rid of your `.cime` folder. Since it will take priority over machine configs at ccs_config. | ||
``` | ||
|
||
This config is kept currently up-to-date to make it possible to run on betzy, fram and saga. | ||
In your CTSM clone (assuming it is your fork that is cloned and you want to update it), navigate to ccs_config and check what remotes do you have there: | ||
|
||
[~/CTSM_ROOT]$ cd $CTSM_ROOT/ccs_config | ||
[~/CTSM_ROOT/ccs_config]$ git remote -v | ||
|
||
This will give you something like: | ||
|
||
origin https://github.com/ESMCI/ccs_config_cesm.git (fetch) | ||
origin https://github.com/ESMCI/ccs_config_cesm.git (push) | ||
|
||
You can add a new remote and fetch: | ||
|
||
[~/CTSM_ROOT/ccs_config]$ git remote add noresm https://github.com/NorESMhub/ccs_config_noresm.git | ||
[~/CTSM_ROOT/ccs_config]$ git fetch --all | ||
|
||
Now, you can checkout a specific tag: | ||
|
||
[~/CTSM_ROOT/ccs_config]$ git checkout ccs_config_noresm0.0.3 | ||
Usually, you can just check out the last tag that was posted on NorESMhub/ccs_config_noresm. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
CTSM-Norway | ||
========================= | ||
|
||
The documentation on this webpage is made to help users of the clusters offered by `Sigma2 <https://www.sigma2.no/>`__ to run and contribute to the development of the `Community Terrestrial Systems Model (CTSM) <https://github.com/ESCOMP/CTSM>`__. | ||
|
||
Our mission is not to duplicate the information you can find in CTSM's `documentation <https://escomp.github.io/ctsm-docs/versions/master/html/index.html>`__, | ||
and NorESM's `documentation <https://noresm-docs.readthedocs.io/en/latest/configurations/clm.html>`__, but rather offer some up-to-date guidelines of best practices for running and developing CTSM and CTSM-FATES with examples that are specific for the Norwegian cluster. | ||
|
||
|
||
|
||
.. Note :: | ||
This documentation is not meant to be static and is a collaborative effort of the total team. | ||
If you spot anything wrong or would like to add information to the documentation, | ||
please check out our `contribution guide <https://metos-uio.github.io/CTSM-Norway-Documentation/contribution/#contribution>`__ and send us a pull request or file an | ||
issue in `our <https://github.com/MetOs-UiO/CTSM-Norway-Documentation/issues>`_ repository. | ||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: Prerequisite | ||
|
||
prerequisite.md | ||
|
||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: Content | ||
|
||
quick-start.md | ||
quick-start-single-point.md | ||
get.md | ||
run.md | ||
spinup.md | ||
wrf-ctsm.md | ||
develop.md | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: Reference | ||
|
||
license | ||
contribution |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
# Credit | ||
The documentation on this webpage is made to help users of the clusters offered by [Sigma2](https://www.sigma2.no/) to run and contribute to the development of the [Community Terrestrial Systems Model (CTSM)](https://github.com/ESCOMP/CTSM). | ||
|
||
|
||
## Content | ||
The information you can find here is maintained by CTSM-Norway-Team and is maintained as a collective effort. | ||
|
||
The people that have contributed to the content of this webpage are (listed in alphabetical order): | ||
|
||
[![](./img/profile_pictures/octocat.png)](https://github.com/ecaas) Elin Ristorp Aas | ||
|
||
[![](./img/profile_pictures/kjetilaas.png)](https://github.com/kjetilaas) Kjetil Schanke Aas | ||
|
||
[![](./img/profile_pictures/mvdebolskiy.png)](https://github.com/mvdebolskiy) Matvey Debolskiy | ||
|
||
[![](./img/profile_pictures/ziu1986.png)](https://github.com/ziu1986) Stefanie Falk | ||
|
||
[![](./img/profile_pictures/annefou.png)](https://github.com/annefou) Anne Fouilloux | ||
|
||
[![](./img/profile_pictures/octocat.png)](https://github.com/emiliano-gelati) Emiliano Gelati | ||
|
||
[![](./img/profile_pictures/sunnivin.png)](https://github.com/sunnivin) Sunniva Indrehus | ||
|
||
[![](./img/profile_pictures/lasseke.png)](https://github.com/lasseke) Lasse Keetz | ||
|
||
[![](./img/profile_pictures/octocat.png)](https://github.com/mariuslam) Marius Lambert | ||
|
||
[![](./img/profile_pictures/octocat.png)](https://github.com/gunnartl) Gunnar Thorsen Liahjell | ||
|
||
[![](./img/profile_pictures/irismuz.png)](https://github.com/irismuz) Iris Mužić | ||
|
||
[![](./img/profile_pictures/devarajun.png)](https://github.com/devarajun) Devaraju Narayanappa | ||
|
||
[![](./img/profile_pictures/octocat.png)](https://github.com/huitang-earth) Hui Tang | ||
|
||
[![](./img/profile_pictures/yelizy.png)](https://github.com/yelizy) Yeliz Yilmaz | ||
|
||
|
||
## Template | ||
|
||
This webpage is adapted to CTSM-Norway's needs from the sphinx-lesson maintained and developed by [CodeRefinery](https://coderefinery.org/), and is Copyright (c) CodeRefinery and, is distributed under the following [license](https://creativecommons.org/licenses/by/4.0/). | ||
|
||
The website [template](https://github.com/coderefinery/documentation) is maintained by [CodeRefinery](https://coderefinery.org/) | ||
and rendered with [sphinx-lesson: structured lessons with Sphinx](https://coderefinery.github.io/sphinx-lesson/). | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
# Prerequisites | ||
This page is where you should start. You will have problems with following the steps in the documentation if some of these concepts are unfamiliar to you or you haven't been granted all the needed access. | ||
|
||
|
||
## Technical concepts | ||
CTSM is a big code written in modern Fortran. This requires its users to have high technical competence. | ||
|
||
### Git | ||
To start working with CTSM you need some basic understanding of the version control system `git` and the web interface `GitHub`. | ||
```{discussion} Not familiar with git? | ||
We recommend you to take a look at CodeRefinery's [Git intro](https://coderefinery.github.io/git-intro/), [Git collaborative](https://coderefinery.github.io/git-collaborative/), and [GitHub](https://coderefinery.github.io/github-without-command-line/) lessons before you start working with CTSM. | ||
``` | ||
|
||
### The Unix shell | ||
To start working with CTSM you need some basic understanding of how to work with the terminal. You also recommend you to set up [ssh-keys](https://documentation.sigma2.no/getting_started/create_ssh_keys.html) for login. | ||
```{discussion} Not familiar with a terminal? | ||
We recommend taking a look at Software Carpentry's [unix shell](https://swcarpentry.github.io/shell-novice/) episode. | ||
``` | ||
|
||
## Needed accesses | ||
This section is a guide to the setup and use of CTSM on the Norwegian clusters | ||
run by Sigma2. | ||
|
||
### The Sigma2-clusters | ||
To get access to these you need to create an account by | ||
filling out [this](https://www.metacenter.no/user/application/form/notur/) form. You will | ||
need a project code that you can ask your project manager( ie. | ||
supervisor) for. Once this form is filled out the project manager and | ||
sigma2 will need to approve the application. This will take some days, | ||
and you\'re good to go. | ||
|
||
```{discussion} First time on a HPC-cluster? | ||
If this is your first time using a remote HPC-system, or you want to | ||
know more about Sigma2\'s set up this | ||
[tutorial](https://sabryr.github.io/hpc-intro/12-cluster/index.html) is | ||
a great place to start. | ||
``` | ||
|
||
### Input data folders | ||
All the runs of CTSM require certain input data for forcing data, grids, etc. Usually, these files are downloaded automatically from [NCAR's service](https://escomp.github.io/CESM/release-cesm2/downloading_cesm.html#downloading-input-data), but be aware of the size of the files! | ||
|
||
To avoid duplication of input files in the order of TB the users and developers of NorESM, CTSM, and other related climate models in Norway share disk space on the clusters. To get access to this folder you need to ask about the permission of the group owner. | ||
|
Oops, something went wrong.