How to contribute to the C‐ESM‐EP code (for the CMC group)

1. Become a collaborator of the C-ESM-EP code

==> send your Github username to Jérôme by e-mail (and he will add you as a collaborator)

2. Get the C-ESM-EP code:

Create a working directory on your favorite server (Spirit, LSCE, etc. but not at TGCC) and clone the C-ESM-EP repo:

mkdir C-ESM-EP
cd C-ESM-EP
git clone [email protected]:jservonnat/C-ESM-EP.git git
cd git

Check the current branch you are on:

jservon@spirit1:~/C-ESM-EP/git$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

3. Create a new branch to develop your code:

jservon@spirit1:~/C-ESM-EP/git$ git checkout -b my_developments
Switched to a new branch 'my_developments'
jservon@spirit1:~/C-ESM-EP/git$ git status
On branch my_developments
nothing to commit, working tree clean

4. Develop and test your code...

At that stage, if you use libIGCM for running C-ESM-EP, you will set CesmepCode to the location of your C-ESM-EP code tree, and you can set CesmepComparison either to a path relative to CesmepCode, or to an absolute path to any location.

4.1 Create your own comparison to develop your own atlas (page)

# - Copy standard_comparison and rename it with a name that will make sense in the context of sharing the code with everybody
# --> ex: JD_PISCES_comparison (for the development made by Julie Deshayes on PISCES atlases)
# --> !! avoid 'my_comparison' (or at least add your initials
cp -r standard_comparison JD_PISCES_comparison

4.2 Remove all the directories you don't need in your comparison

4.3 Develop your own atlas "YourAtlas"

a. Create your own YourAtlas directory (see the documentation here). b. Put all your modifications/developments in params_YourAtlas.py and diagnostics_YourAtlas.py in the YourAtlas directory, including the needed:

calias
derive
project
custom_plot_params
custom_obs_dict
etc.

Jérôme and Stéphane will eventually add the relevant parts to the main C-ESM-EP and CliMAF code (calias, derive, etc.).

4.4 Test your code!!

A useful debugging tip: use an interactive python session or a notebook, import CliMAF, and test the code that gives errors.

How to use an interactive python session with CliMAF? First, use source setenv_C-ESM-EP.sh to set your environment to use CliMAF (the same as the one used by the C-ESM-EP):

jservon@spirit1:~/C-ESM-EP/git$ source setenv_C-ESM-EP.sh
Tue 01 Jul 2025 04:53:50 PM CEST
Loading module /net/nfs/tools/Users/SU/modulefiles/jservon/climaf/env20240920_climafV3.1_IPSL12 for CliMAF and C-ESM-EP

Environment settings for C-ESM-EP
---------------------------------
CLIMAF_CACHE = /scratchu/jservon/atlas_explorer
CESMEP_CLIMAF_CACHE =
PYTHONPATH = /home/jservon/C-ESM-EP/git:/home/jservon/C-ESM-EP/git/share/cesmep_modules:/net/nfs/tools/Users/SU/jservon/climaf_installs/V3.1_IPSL12:/home/jservon/C-ESM-EP/20230203/share/cesmep_modules:/home/jservon/RTE_v2/:/home/jservon/RTE_v2//selection_settings::/home/igcmg/prodiguer-client

and open your interactive session using the command climaf:

jservon@spirit1:~/C-ESM-EP/git$ climaf
Python 3.10.15 | packaged by conda-forge | (main, Sep 20 2024, 16:37:05) [GCC 13.3.0]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.27.0 -- An enhanced Interactive Python. Type '?' for help.
python => 3.10.15 | packaged by conda-forge | (main, Sep 20 2024, 16:37:05) [GCC 13.3.0]
---
Required softwares to run CliMAF => you are using the following versions/installations:
CliMAF climaf_version = 3.0
CliMAF install => /net/nfs/tools/Users/SU/jservon/climaf_installs/V3.1_IPSL12
Cache directory set to : /scratchu/jservon/atlas_explorer (use $CLIMAF_CACHE if set)
Cache directory for remote data set to : /scratchu/jservon/atlas_explorer/remote_data (use $CLIMAF_REMOTE_CACHE if set)
warning  : defining curl_tau_atm : command ferret is not executable
warning  : Binary cdftools not found. Some operators won't work
warning  : When defining temp_penalty : duplicate declaration for input #0
warning  : When defining cquantile : duplicate declaration for input #0
warning  : When defining cquantile : duplicate declaration for input #0
Available macros read from ~/.climaf.macros are : []

In [1]:

The other method is to use a notebook. You need to setup your environment before you run the notebook. We use the following lines in the .bashrc to setup the environment:

module use --append /net/nfs/tools/Users/SU/modulefiles/jservon/climaf
env=env20240920_climafV3.1_IPSL12
    
set +x
module purge
module load $env
export PYTHONPATH="/home/jservon/C-ESM-EP/git/share/cesmep_modules:$PYTHONPATH"

subnot() {
  local mem_per_cpu="${1:-9G}"  # Valeur par défaut : 4G si aucun argument n'est fourni
  srun --pty --mem-per-cpu="$mem_per_cpu" --time=360 notebook_${env}
}

And then use the subnot command to launch the notebooks (and follow the usual procedure)!

4.5 Add your comparison to the dev_comparisons directory

mv JD_PISCES_comparison dev_comparisons

5. Add your developments to the branch with git add:

jservon@spirit1:~/C-ESM-EP/git$ git status
On branch my_developments
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	dev_comparisons/JD_PISCES_comparison

nothing added to commit but untracked files present (use "git add" to track)
jservon@spirit1:~/C-ESM-EP/git$ git add dev_comparisons/JD_PISCES_comparison
jservon@spirit1:~/C-ESM-EP/git$ git status
On branch my_developments
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	new file:   dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/diagnostics_Essentials_PISCES.py
	new file:   dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/params_Essentials_PISCES.py
	new file:   dev_comparisons/JD_PISCES_comparison/MainTimeSeries_PISCES/params_MainTimeSeries_PISCES.py
	new file:   dev_comparisons/JD_PISCES_comparison/datasets_setup.py

jservon@spirit1:~/C-ESM-EP/git$ git add dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/diagnostics_Essentials_PISCES.py dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/params_Essentials_PISCES.py dev_comparisons/JD_PISCES_comparison/MainTimeSeries_PISCES/params_MainTimeSeries_PISCES.py dev_comparisons/JD_PISCES_comparison/datasets_setup.py
jservon@spirit1:~/C-ESM-EP/git$
jservon@spirit1:~/C-ESM-EP/git$
jservon@spirit1:~/C-ESM-EP/git$ git status
On branch my_developments
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	new file:   dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/diagnostics_Essentials_PISCES.py
	new file:   dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/params_Essentials_PISCES.py
	new file:   dev_comparisons/JD_PISCES_comparison/MainTimeSeries_PISCES/params_MainTimeSeries_PISCES.py
	new file:   dev_comparisons/JD_PISCES_comparison/datasets_setup.py

6. Commit the changes you added:

jservon@spirit1:~/C-ESM-EP/git$ git commit -am 'JS_PISCES_comparison in dev_comparisons'
[dev_jerome 9b76f9d] Added dev_comparisons directory and started Essentials atlas
 Committer: jerome servonnat <[email protected]>
Your name and email address were configured automatically based
on your username and hostname. Please check that they are accurate.
You can suppress this message by setting them explicitly:

    git config --global user.name "Your Name"
    git config --global user.email [email protected]

After doing this, you may fix the identity used for this commit with:

    git commit --amend --reset-author

 4 files changed, 1385 insertions(+)
 create mode 100755 dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/diagnostics_Essentials_PISCES.py
 create mode 100755 dev_comparisons/JD_PISCES_comparison/Essentials_PISCES/params_Essentials_PISCES.py
 create mode 100755 dev_comparisons/JD_PISCES_comparison/MainTimeSeries_PISCES/params_MainTimeSeries_PISCES.py
 create mode 100644 dev_comparisons/JD_PISCES_comparison/datasets_setup.py

7. Push your branch to the github repo; use a branch name that will be easily identified (here: JD_PISCES_developments)

git push -u origin HEAD:JD_PISCES_developments

If you have a pb like this one:

jservon@spirit1:~/C-ESM-EP/git$ git push -u origin HEAD:JD_PISCES_developments
Username for 'https://github.com': jservonnat
Password for 'https://[email protected]':
remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/jservonnat/C-ESM-EP.git/'

try:

git remote set-url origin [email protected]:jservonnat/C-ESM-EP.git

8. Request for a merge

Go to C-ESM-EP Github > Code > Branches
Select your branch and push the 'pull request' as much as possible => you will be blocked before the merge (only Jérôme can merge).
tell Jérôme that you are ready to merge (provide the branch name)

Well done!

How to contribute to the C‐ESM‐EP code (for the CMC group) - jservonnat/C-ESM-EP GitHub Wiki

1. Become a collaborator of the C-ESM-EP code

2. Get the C-ESM-EP code:

3. Create a new branch to develop your code:

4. Develop and test your code...

4.1 Create your own comparison to develop your own atlas (page)

4.2 Remove all the directories you don't need in your comparison

4.3 Develop your own atlas "YourAtlas"

4.4 Test your code!!

4.5 Add your comparison to the dev_comparisons directory

5. Add your developments to the branch with git add:

6. Commit the changes you added:

7. Push your branch to the github repo; use a branch name that will be easily identified (here: JD_PISCES_developments)

8. Request for a merge

⚠️ GitHub.com Fallback ⚠️

How to contribute to the C‐ESM‐EP code (for the CMC group) - jservonnat/C-ESM-EP GitHub Wiki

1. Become a collaborator of the C-ESM-EP code

2. Get the C-ESM-EP code:

3. Create a new branch to develop your code:

4. Develop and test your code...

4.1 Create your own comparison to develop your own atlas (page)

4.2 Remove all the directories you don't need in your comparison

4.3 Develop your own atlas "YourAtlas"

4.4 Test your code!!

4.5 Add your comparison to the dev_comparisons directory

5. Add your developments to the branch with git add:

6. Commit the changes you added:

7. Push your branch to the github repo; use a branch name that will be easily identified (here: JD_PISCES_developments)

8. Request for a merge

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️