Changeset 3861 for trunk/LMDZ.COMMON/libf/evolution/deftank/README

Timestamp:

Jul 21, 2025, 1:55:12 PM (13 days ago)

Author:

jbclement

Message:

PEM:

• Big update of "README" file in the "deftank" folder.
• Renaming the log files "out_run*" into "run.log".
• Merging the folders "out_PCM" and "out_PEM" into "logs" where the log files are gathered with convenient renaming.
• Update of job files.
• More robust tests in "lib_launchPEM.sh".

JBC

File:

• trunk/LMDZ.COMMON/libf/evolution/deftank/README (modified) (6 diffs)

trunk/LMDZ.COMMON/libf/evolution/deftank/README

@@ -9 +9 @@
 
    
-This folder contains all the files needed to run the Planetary Evolution Model (PEM).
+This folder contains all the files needed to run and work with the Planetary Evolution Model (PEM).
 
+Information:
+------------
+For further explanations about the PEM, see following website: https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/PEM_(Planetary_Evolution_Model).
+
+Installation:
+-------------
+The PEM can be downloaded alongside the "LMDZ.COMMON" repository of your trunk. The Fortran code is in the following directory: "trunk/LMDZ.COMMON/libf/evolution/". The two PEM programs are "pem.F90" and "reshape_XIOS_output.F90".
+
+Compilation:
+------------
+To compile the PEM, in "LMDZ.COMMON", do: ./makelmdz_fcm -arch [local] -p [planet] -d [dimensions] -j 8 pem
+Options:
+    1) [local]     : root name of arch files, assuming that they have been set up for your configuration;
+    2) [planet]    : mars to use the planet physics package; 
+    3) [dimensions]: 64x48x54 to define the grid you want to use.
+To run the PEM, you need a dedicated reshaping tool with consistent options. To compile it, in "LMDZ_COMMON", do: ./makelmdz_fcm -arch [local] -p [planet] -d [dimensions] -j 8 reshape_XIOS_output
+To run the PEM, you also need a PCM working with XIOS and consistent options. To compile it, in "LMDZ.COMMON", do for example: ./makelmdz_fcm -arch [local] -p [planet] -parallel mpi_omp -io XIOS -d [dimensions] -j 8 gcm
+After compilation, the executable file can be found in the "bin" sub-directory.
+
+Usage:
+------
+  To run a PEM simulation, do: ./launchPEM.sh [options]
+  Options:
+      1) None: to start a simulation from scratch;
+      2) 're': to relaunch a simulation from a starting point (interactive prompt).
+
+Requirements:
+-------------
+To run the PEM, you need the following files:
+    > your executable files for the PCM, the PEM and the reshaping tool with consistent dimensions;
+    > the xml files for XIOS ("iodef.xml", "context_lmdz_physics.xml", "file_def_physics_mars.xml" and "field_def_physics_mars.xml") which can be found in the PCM deftank folder;
+    > the def files you want to run the PCM ("run.def", "callphys.def", "traceur.def", etc).
+      /!\ Do not forget to rename the PCM "run.def" into "run_PCM.def";
+    > the starting files you want to run the PCM ("startfi.nc", "start.nc"/"start1D.txt"/profiles);
+    > the necessary PEM files ("launchPEM.sh", "lib_launchPEM.sh", "PCMrun.job", "PEMrun.job", "run_PEM.job" and "obl_ecc_lsp.asc";
+    > the optional PEM files "diagpem.def" to define the PEM variables to be ouputted and "startpem.nc" to set the initial state of the PEM.
+
+Outputs:
+--------
+The PEM simulation generates the following files:
+    > the usual outputs of the PCM ("restartfi.nc", "restart.nc", "diagfi.nc", etc);
+    > the XIOS outputs of the PCM, then reshaped ("Xdiurnalave.nc"/"data2reshape*.nc"/"data_PCM_Y*.nc");
+    > the outputs of the chained simulation ("launchPEM.log", "info_PEM.txt" and possibly "kill_launchPEM.sh");
+    > the usual outputs of the PEM ("restartfi.nc", "restart.nc"/"restart1D.txt" and "diagpem.nc").
+During the simulation, the PCM/PEM run files are renamed conveniently and stored in the sub-directories "logs" (log files), "starts" (starting files) and "diags" (diagnostic files).
+If you run a simulation by submitting jobs, the script "kill_launchPEM.sh" is automatically generated. It can be used to kill in the queue of the job scheduler the jobs related to your chained simulation.
+
+Deftank files:
+--------------
 # launchPEM.sh:
   Bash script file to launch the chained simulation of PEM and PCM runs.
   The user has to specify:
-      (i)   n_mars_years, n_earth_years -> the number of Mars/Earth years to be simulated in total;
-      (ii)  nPCM_ini -> the number of initial PCM runs (at least 2);
-      (iii) nPCM -> the number of PCM runs between each PEM run (usually 2);
-      (iv)  counting -> the counting method for the number of years to be simulated (0 = "only PEM runs count"; any other values = "PCM runs are taken into account"). The former option is the PEM default use;
-      (v)   mode -> the launching mode (0 = "processing scripts"; any other values = "submitting jobs"). The former option is usually used to process the script on a local machine while the latter is used to submit jobs on a supercomputer.
+      > n_mars_years, n_earth_years -> the number of Mars/Earth years to be simulated in total (> 0);
+      > nPCM_ini -> the number of initial PCM runs (>= 2);
+      > nPCM -> the number of PCM runs between each PEM run (>= 2, usually 2);
+      > counting -> the counting method for the number of years to be simulated (0 = "only PEM runs count"; any other values = "PCM runs are taken into account"). The former option is the usual one;
+      > mode -> the launching mode (0 = "processing scripts"; any other values = "submitting jobs"). The former option is usually used to process the script on a local machine while the latter is used to submit jobs on a supercomputer with SLURM or PBS/TORQUE.
   The script can take an argument:
-      - If there is no argument, then the script initiates a PEM simulation from scratch.
-      - If the argument is 're', then the script relaunches an existing PEM simulation. It will ask for parameters to know the starting point that you want to. 
-  To submit chained jobs, the script works with the job schedulers SLURM and PBS/TORQUE.
+      1) If there is no argument, then the script initiates a PEM simulation from scratch.
+      2) If the argument is 're', then the script relaunches an existing PEM simulation. It will ask for parameters to know the starting point that you want to.
 
 # liblaunchPEM.sh:
@@ -28 +76 @@
 
 # PCMrun.job:
-  Bash script file to submit a PCM job (with SLURM or PBS/TORQUE). The headers correspond to the ADASTRA supercomputer and should be changed for other machines and job schedulers. In case of "processiong scripts" launching mode, the headers are naturally omitted.
+  Bash script file to submit a PCM job (with SLURM or PBS/TORQUE). The headers correspond to the ADASTRA supercomputer and should be changed for other machines and job schedulers. In case of "processing scripts" launching mode, the headers are naturally omitted.
   The path to source the arch file should be adapted to the machine.
   The name of the PCM executable file should be adapted.
@@ -34 +82 @@
 
 # PEMrun.job:
-  Bash script file to submit PEM job (with SLURM or PBS/TORQUE).The headers correspond to the ADASTRA supercomputer and should be changed for other machines and job schedulers. In case of "processiong scripts" launching mode, the headers are naturally omitted.
+  Bash script file to submit PEM job (with SLURM or PBS/TORQUE).The headers correspond to the ADASTRA supercomputer and should be changed for other machines and job schedulers. In case of "processing scripts" launching mode, the headers are naturally omitted.
   The path to source the arch file should be adapted to the machine.
   The name of the PEM executable file and Reshaping executable file should be adapted.
-  The PEM executable can have an optional argument which should be specified according to the set-up. This the job ID to make the PEM detect the job time limit.
+  The PEM executable can have an optional argument which should be specified according to the set-up. Especially, the value of '--jobid' which is the job ID to make the PEM detect the job time limit.
 
 # run_PEM.def
@@ -47 +95 @@
 
 # modify_startfi_orbit.sh:
-  Bash script file to modify orbital parameters in the file "startfi.nc" (obliquity, eccentricity, Ls perihelion and possibly initial Ls). They should be consistent with Laskar's data in "obl_ecc_lsp.asc" to start a chained simulation at a specific date.
+  Bash script file to modify orbital parameters in the file "startfi.nc". They should be consistent with Laskar's data in "obl_ecc_lsp.asc" at the same date if orbital parameters are meant to vary during the simulation. See also "inipem_orbit.sh".
 
 # modify_startfi_var.sh:
@@ -53 +101 @@
 
 # inipem_orbit.sh:
-  Bash script file to modify the orbital parameters of a file "startfi.nc" according to the date set in the file "run_PEM.def".
+  Bash script file to set the orbital parameters of a file "startfi.nc" from Laskar's data contained in "obl_ecc_lsp.asc" according to the initial date 'year_earth_bp_ini' defined in "run_PEM.def". See also "modify_startfi_orbit.sh".
 
 # concat_diagpem.sh:
@@ -69 +117 @@
 # visu_evol_layering.py:
   Python script file to output the stratification data over time from the "startpem.nc" files.
-
-Note:
-  To run the chained simulation, be careful to have:
-      (i)   the xml files for XIOS. There should be "iodef.xml", "context_lmdz_physics.xml", "file_def_physics_mars.xml" and "field_def_physics_mars.xml" which can be found in the planetary deftank folder;
-      (ii)  the usual def files to run the PCM. "run.def" should be renamed in "run_PCM.def";
-      (iii  the starting files ("startfi.nc" and "start.nc"). The former can be modified by "modify_startfi_orbit.sh";
-      (iv)  some optional files. For example, "diagfi.def" and "diagpem.def".