source: BOL/LMDZ_Setup/README0_HowTo @ 5444

===================================================================
LMDZ_Setup is a software suite for installing LMDZ and automatically
automatically run a number of configurations.
Authors: Frédéric Hourdin, Adriana Sima, Amaury Baral, Laurent Fairhead (and the LMDZ team)

Last modification : 2024/12/19
===================================================================

Complementary information and FAQ (in French) :
https://docs.google.com/document/d/1OLZG6e-86NiXuv5-aALxKIh-QPkp4BdCwWtiBFot-6c


===================================================================
0. Target platforms
===================================================================
Default gfortran/bash installation on local computers.
Specific installation on certain computing centers:
   spirit: IPSL cluster
   adastra: Cines supercomputer
   jean-zay: idris supercomputer
   irene: TGCC supercomputer WORK TO BE DONE
Machine configuration dependency is managed by lmdz_env.sh


===================================================================
I. What this working environment does and does not
===================================================================

This tutorial can only be used on jean-zay computer at idris so far.
    However, extension to ciclad or irene will be done soon.

It proposes a light automatic setup of LMDZ long chained climate simulations
   including installation of the model itself.

It consists in running LMDZ coupled to Orchidee for land surface (optional)
   but with imposed sea surface temperature.

The basic default configuration makes use of the IPSL-CM6A grid configuration
   and tuning, and runs a multi annual simulation on "climatological"
   amip sea surface temperature (with a mean annual cycle) using
   a calendar with 360 days.

Optionally : the configuration includes the ability to use interannually
   varying SST and to activate "nudgning" by reanalysis.
   In both cases, the calendar is then a real one.
   When nudging is activated, the simulation must be run on a monthly
   basis, while otherwise, it can be either monthly or yearly.

Since the tutorial automatically generates its own initial files, it
   can be run with zoom configurations by only changing the number
   of grid points ("resol" in main.sh) and the DEF/gcm.def file (see bellow).

Aerosols can be read for the year 2000 (weighted average  over 1999-2001 cf Lurton et al 2020),
  and instantaneous forcing with respect to 1850 can be computed as well.
  NEW (end 2020) :
        tutorial_prod can also run LMDZ coupled with the SPLA model
        (SimPLe Aerosol, activated with option aerosols=spla in setup.sh). 
        Emissions of dust and sea salt are then computed interactively.
        2021-05 : tutorial_prod OK, code LMDZ-SPLA OK, 
                regridding SPLA input files : work in progress

A configuration with isotopes is also available since 2023-04.
   
===================================================================
II. Files and scripts
===================================================================
----------------------------------------------------------------
     EXPERT :
     If the login groupe and computing allocation groupe are different :
       choose on which STORE space you work (login vs computing allocation);
       edit lmdz_env.sh, and set "groupe", "SCRATCHD" etc. accordingly.
     If you want to install the package in a dedicated folder instead of the root of $STORE:
       set STORED=$STORE/your_folder in lmdz_env.sh 
----------------------------------------------------------------

main.sh : a script written to pass options to the main script setup.sh

setup.sh : sets up one (series of) simulation(s) by editing the "job" script_SIMU
    When run with -init 1 options, creates INIT and LIMIT directories
    Run ./setup.sh -h   for options
    RECOMMENDATION: do not run it directly, but use main.sh to drive it
    
script_SIMU : script that is the basis for the job to run the simulations
    Automatically edited by setup.sh

reb.sh : to rebuild splitted outputfiles (parallelism with IOISPL)
    automatically run by script_SIMU

era2gcm_tuto.sh : to interpolate reanalysis onto the GCM grid, for nudging.
   To be run manually after the first use of main.sh

era2gcm_uv10m.nc : for option "aerosols=spla" only : 
     to interpolate reanalysis 10m-winds onto the GCM grid, for sea-salt (and dust) emissions.
        To be run manually after the first use of main.sh.

season.sh : computing seasonal means and daily time series

interp_aerosols.sh : interpolating aerosols on the GCM grid.
    Automatically run by setup.sh

post_season.sh : post processing a series of simulations with season.sh

test_ERAfiles_JeanZay.sh : script to test the availability of ERA* files sur Jean-Zay
    In case of nudging, one may use it before running era2gcm.sh                

DEF: .def files for simulations
   Some of them are changed by setup.sh or script_SIMU depending on chosen options
   Some others need to be chosen and customized BEFORE RUNNING the scripts (main.sh or setup.sh):
     DEF/config.def (versions *.def_* available): output files, frequencies, levels (see lines phys_out_file*)
     DEF/gcm.def (versions *.def_* available): grid (and grid-related) parameters
     DEF/guide.def : nudging parameters 

============================================================
III. Repatriation of input data
============================================================

Installation requires downloading data from
from http://http://lmdz.lmd.jussieu.fr/pub/3DInputData
Repatriation is managed by a series of functions found in
lmdz_env.sh: wget_pub cp_from_pub ln_from_pub get_input_files

In my opinion, LMDZ_Setup's approach to data management is to be able to perform a complete
installation on any account on any machine, by distributing data from wget http://lmdz....
In the new version, you don't duplicate any of the fields you download, and you only download them once to an account.
This is very small compared to the amount of data generated.
So I think we're very parsimonious in our use of IT resources.
Of course, this has to do with the fact that we don't manage a lot of different configurations in terms of boundary conditions, forcing, etc.
But that's where libiGCM comes in.


============================================================
IV. Known problems
============================================================

Running zoomed or coarse grid simulations
    May cause problems with routing and aerosols
    Suggesting to run without aerosols, aerosols="n", in this case


============================================================
V. Updates (reverse chronological order)
============================================================

2024-12 (FH) : retravail de l'accès au données sur http://lmdz...

2024-11 : Travail de portage multi-machine par Amaury Barral.
          Précédemment sur jean-zay uniquement.
          Porté sur adastra et machines locales.

2023-07 (AS-FH-LF) : mise sous svn du repertoire TEST_PROD, renommé en "LMDZ_config"

2023-06 (AS) : Ajout de l'option "veget=7994", pour ORCHIDEE trunk correspondant à la config libIGCM LMDZOR_6.4work 
        Le routage (méthode = simple) est désactivé par défaut ; 
        il peut être activé comme décrit dans la section "ORCHIDEE-routage". 
        Le routage n’a pas été testé avec zoom.

2023-05 (AS) : optimisation du functionnement de l'option isotopes : tout géré par phys=lmdiso

2023-04 (S Nguyen) : introducing the option of running with isotopes)
        
2021-10 (AS): introducing the option of using the new snow scheme INLANDSIS (setup.sh)
        Option not active yet, E Vignon will take care of that.

2020 (AS): introducing the possibility to run with SPLA aerosol model 

24/03/2020 (FH): corrections for use with AMIP SSTs and monthly freq

============================================================
VI. TBD
============================================================
See documentation (link of the shared google doc in the beginning of this Readme)


Notes concernant Orchidee
-------------------------

Plusieurs versions disponibles via la clé veget
veget=CMIP6 : version CMIP6
veget=XXX   : XXX numéro de relase svn d'orchidee
    XXX+:1

On rapatrie automatiquement des champs nécessaires pour les dernières versions d'orchidee
PFTmap_IPCC_2000.nc cartepente2d_15min.nc routing.nc routing_simple.nc lai2D.nc \
alb_bg_modisopt_2D_ESA_v2.nc reftemp.nc \
soils_param.nc woodharvest_2000.nc PFTmap_15PFT.v1_2000.nc soil_bulk_and_ph.nc  \

Les deriners fichiers sont nécessaires seulement
ndep_nhx.nc ndep_noy.nc nfert_cropland.nc nfert_pasture.nc nmanure_cropland.nc nmanure_pasture.nc bnf.nc" ;;



Notes concernant la confiugration SPLA
--------------------------------------
Pour l'instant on copie là-dedans de chez Binta les fichiers a la res zoomNaf;
plus tard on y recupererea des fichiers a haute resolution reguliere depuis http:/LMDZ,
a regrider ensuite par un script interp_fichiers_spla.sh (comme pour aerosols="clim")
Les fichiers (regrides, sauf SOILSPEC.data utilise tel quel) seront mis dans $MAINDIR/INPUT_SPLA (equivalent de INPUT_DUST)
The Path below is for JEANZAY. See with the team how to adapt to your cluster.

#for file in donnees_lisa.nc SOILSPEC.data                                    \ # For Chimere dust emissions
#     cly.dat $( for i in $(seq 1 12 ) ; do echo dust$i.nc ; done ) wth.dat   \ # For Inca dust emissions
#     carbon_emissions.nc sulphur_emissions_antro.nc sulphur_emissions_nat.nc \ # For non dust emissions

#Cas particulier des fichiers mensuels dust.nc :A DECIDER :
#C'est entre le cas des aerosols.clim= 1 seul fichier, annuel,
# et le cas des vents guidage, pré-interpolés avec era2gcm pour toute la periode, dans MAINDIR/GUIDE.
# On pourrait (a)demander de precalculer dust.nc aussi, dans MAINDIR/INPUT_SPLA - avec un script à adapter de Jeronimo. Rien a mettre dans SPLA_Init alors.
# Ou (b) fournir dans SPLA_Init les 12 mois d'un dust.nc climato (an 2006 pour nous ici) à la res EC, et faire juste le regrid vers MAINDIR/INPUT_SPLA

A la fin on doit avoir dans SPLA_Init les fichiers initiaux dans INITIAL plus les repertoires PERIOD00MM contenant dust.nc
Cela doit se retrouver dans script_SIMU qui les copie dans le repertoire de run sur $SCRATCH