# PEM Deftank Workflow

This folder contains workflow templates and helper scripts used to run chained PCM/PEM simulations.

Online PEM documentation:
https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/PEM_(Planetary_Evolution_Model)

## Scope

- Build instructions for PEM itself are maintained in `../README.md`.
- This README covers runtime workflow setup from `pem_workflow.sh`.

## 1. Build prerequisites

Compile PEM from the `PEM` root folder using the current build driver:

```bash
./make_pem_fcm -arch <arch_name> -p mars -d <dim_tag> -j 8 -full -debug pem
```

Compile PCM separately from `LMDZ.COMMON` with options compatible with your workflow setup, including XIOS outputs required by chained runs.

Notes:
- Executable names are configured in `pcm_run.job` and `pem_run.job` (`pcm_exe`, `pem_exe`).
- Adapt architecture, dimensions, and execution mode to your machine.

## 2. Working directory requirements

Run the chained workflow in a simulation directory containing:

Mandatory workflow scripts:
- `pem_workflow.sh`
- `pem_workflow_lib.sh`
- `pcm_run.job`
- `pem_run.job`

Mandatory PCM/PEM configuration files checked by `check_workflow()`:
- `run_pcm.def`
- `run_pem.def`
- `callphys.def`
- `z2sig.def`
- `traceur.def`

Mandatory XIOS files checked by `check_workflow()`:
- `iodef.xml`
- `context_lmdz_physics.xml`
- `field_def_physics_mars.xml`
- `file_def_physics_mars.xml`

Mandatory or expected restart inputs:
- `startfi.nc` (required by yearly-run consistency checks)
- one of `start.nc` or `start1D.txt` for PCM initial state
- optional `startevo.nc` for PEM restart

Orbital file:
- `obl_ecc_lsp.asc` is recommended (workflow warns if missing).
- A template is provided in `mars/obl_ecc_lsp.asc`.

Environment command requirement:
- `ncdump`

## 3. Quick start

From your simulation directory:

```bash
./pem_workflow.sh
```

To resume from a previous successful run:

```bash
./pem_workflow.sh re
```

The internal argument `new` is used by the workflow itself between submitted cycles and is not the normal manual entrypoint.

## 4. Configure execution mode

Edit `pem_workflow.sh` before launching:

- `n_planetary_years` or `n_earth_years`
- `planetary_year_days`
- `n_pcm_runs_ini` (must be >= 2)
- `n_pcm_runs` (must be >= 2)
- `exec_mode`

Execution modes:
- `exec_mode=0`: run job scripts directly in-process.
- `exec_mode!=0`: submit jobs through detected scheduler.

Scheduler detection in `pem_workflow_lib.sh` currently supports:
- SLURM (`squeue`, `sbatch`, `scancel`)
- PBS/TORQUE (`qstat`, `qsub`, `qdel`)

## 5. Adapt job templates to your machine

Both `pcm_run.job` and `pem_run.job` include machine-specific examples and must be adjusted:

- scheduler headers (`#SBATCH` or PBS directives)
- path to source architecture environment (`source .../arch.env`)
- executable names (`pcm_exe`, `pem_exe`)
- launch command (`exec_cmd` in `pcm_run.job`)
- optional PEM argument (`pem_arg`, for example `--auto-exit` in submitted-job mode)

## 6. Outputs produced by the chained workflow

Main status and log files:
- `pem_workflow.log`
- `pem_workflow.sts`
- `kill_pem_workflow.sh` (generated in submitted-job mode)

Run logs:
- `logs/run_pcm<N>.log`
- `logs/run_pem<N>.log`

Restart snapshots in `starts/`:
- PCM: `restartfi<N>.nc`, `restart<N>.nc` or `restart1D<N>.txt`
- PEM: `restartevo<N>.nc`, `restartfi_postpem<N>.nc`, and optional post-PEM atmospheric restart variants

Diagnostics in `diags/`:
- PCM: `diagfi<N>.nc`, `diagsoil<N>.nc`, `stats<N>.nc`
- XIOS for PEM coupling: `xoutdaily4pem<N>.nc`, `xoutyearly4pem<N>.nc`
- PEM: `diagevo<N>.nc`, `diagevo_soil<N>.nc`

## 7. Provided template files in this folder

- `pem_workflow.sh`: main orchestration script.
- `pem_workflow_lib.sh`: workflow checks, scheduler handling, submission and resume helpers.
- `pcm_run.job`: template for one PCM run.
- `pem_run.job`: template for one PEM run.
- `clean.sh`: reset run-folder artifacts after a workflow.
- `mars/run_pem.def`: Mars PEM default template.
- `mars/obl_ecc_lsp.asc`: Mars orbital data used by orbit helpers.
- `mars/obl_ecc_lsp_future.asc`: alternate orbital dataset.
- `generic/run_pem.def`: generic PEM template.

Orbit and startfi helper scripts plus post-processing tools are maintained in `../toolkit`.