```
#   *    .          .   +     .    *        .  +      .    .       .       #
#            +         _______  ________  ____    ____      *           +  #
#  +   .        *     |_   __ \|_   __  ||_   \  /   _|          .       * #
#           .     .     | |__) | | |_ \_|  |   \/   |  *        *      .   #
#        .              |  ___/  |  _| _   | |\  /| |      .        .      #
# .  *          *      _| |_    _| |__/ | _| |_\/_| |_                  *  #
#             +       |_____|  |________||_____||_____|   +     .          #
#   .      *          .   *       .   +       *          .        +      . #
```

# PEM (Planetary Evolution Model)

This directory contains the PEM source code, compilation tools, and run workflow assets.

PEM can be compiled for:
- `mars` (active production target)
- `generic` (placeholder only, not ready yet)

## What is in this directory

- `src/common`: shared PEM Fortran sources
- `src/mars`: Mars-specific sources
- `src/generic`: generic-planet sources
- `compile.sh`: one-line shortcut to a default `make_pem_fcm` command
- `make_pem_fcm`: main PEM build driver (FCM)
- `build_pem`: lock-protected FCM launcher (PEM equivalent of LMDZ `build_gcm`)
- `bld.cfg`: FCM build description used by `make_pem_fcm`
- `arch/`: machine/compiler architecture files
- `deftank/`: workflow scripts and run assets (`generic/` and `mars/` templates)
- `toolkit/`: helper scripts for post-processing and workflow support
- `bin/`: generated PEM executables
- `lib/`: build outputs and intermediate files

## Prerequisites

Before compiling PEM, ensure:

1. `fcm` is installed and available in your `PATH`.
2. Architecture files exist for your target (`arch/arch-<name>.fcm` and `arch/arch-<name>.path`, optional `arch-<name>.env`).
3. Dependencies are available and compatible with your architecture:
	 - NetCDF (C and Fortran)
	 - IOIPSL
	 - XIOS (needed for `-io mix` or `-io xios`)
4. `LMDZ.COMMON` is available next to this folder by default:
	 - default expected path: `../LMDZ.COMMON`

## Quick start

### Recommended wrapper

Default wrapper command as currently shipped in `compile.sh` (generic target, `gfortran`, dim `8`, debug mode, full rebuild):

```bash
./compile.sh
```

`compile.sh` is intentionally minimal and forwards extra options to `make_pem_fcm`.

If you want a Mars build directly from the wrapper, override the planet option:

```bash
./compile.sh -p mars
```

Example override (change only the parallel jobs):

```bash
./compile.sh -j 16
```

Equivalent explicit command for the current wrapper default:

```bash
./make_pem_fcm -arch gfortran -p generic -d 8 -j 8 -full -debug pem
```

Typical explicit Mars command:

```bash
./make_pem_fcm -arch gfortran -p mars -d 8 -j 8 -full -debug pem
```

### Direct build with full control

```bash
./make_pem_fcm -arch gfortran -p mars -d 8 -j 8 -full -debug pem
```

## Build options reference

Main options from `make_pem_fcm`:

- `-arch <name>`: required architecture name
- `-p <mars|generic>`: planet source folder (default: `mars`)
- `-d <tag>`: dimension tag used in executable suffix
- `-prod | -dev | -debug`: compilation mode (default: `-prod` in `make_pem_fcm`, `-debug` in `compile.sh`)
- `-io <ioipsl|mix|xios>`: I/O library mode (default: `ioipsl`)
- `-j <n>`: parallel compile jobs
- `-full`: force full rebuild
- `-include <path>`: extra include path
- `-cpp <key>`: extra preprocessor keys
- `-link <flags>`: extra link flags
- `-fcm_path <path>`: explicit path to `fcm`
- `-arch_path <path>`: explicit path to architecture files
- `-lmdz_common_path <path>`: explicit `LMDZ.COMMON` root
- `-clean`: remove this build configuration and exit

Notes:
- The executable name includes the dimension and target, for example `bin/pem_8_mars_seq.e`.
- Build directories are created under `lib/<arch>_<dim>_<planet>_seq` (with `_debug` suffix in debug mode).
- At startup, `make_pem_fcm` checks required files under `../LMDZ.COMMON/libf/misc` (`job.F90`, `program_options.F90`).

## Compilation Tracking

- `make_pem_fcm` generates `tmp_src/misc_required/version_control.F90` during compilation.
- This module provides `print_pgrm_version(user_filename)`.
- Through program options, `--version [file]` writes compilation date/command and VCS information/status.
- The default output file name is `pgrm_version_control.txt`.
- VCS text is sanitized to ASCII-safe content before embedding into generated Fortran source.

## Running PEM workflows

Compilation only produces the PEM executable. For chained PCM/PEM runs, use workflow assets in:

- `deftank/`
- `deftank/mars` (Mars templates)
- `deftank/generic` (generic templates)

If needed, use orbit/startfi helper scripts from:

- `toolkit/`

Main workflow entry point:

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

Important workflow files include:

- `deftank/pem_workflow.sh`
- `deftank/pem_workflow_lib.sh`
- `deftank/pcm_run.job`
- `deftank/pem_run.job`
- `deftank/mars/run_pem.def`
- `deftank/mars/obl_ecc_lsp.asc`
- `toolkit/ini_pem_orbit.sh`
- `toolkit/modify_startfi_orbit.sh`
- `toolkit/modify_startfi_var.sh`

For full workflow details and required input files, see:

- `deftank/README.md`

## Additional documentation

- `doc/README.md` points to the PEM online documentation.
- `changelog.txt` tracks PEM code changes.

## API/source documentation with Doxygen

PEM includes a Fortran-focused Doxygen configuration file at `doc/Doxyfile`.
For repeatable local usage, use the helper script `doc/build_doc.sh`.

Prerequisites:
- `doxygen` (required)
- `graphviz` (optional, for call/dependency graphs)

Default generation from the PEM root (both profiles: `mars` and `generic`):

```bash
./doc/build_doc.sh
```

Alternative commands:

```bash
./doc/build_doc.sh --check-deps
./doc/build_doc.sh --clean
./doc/build_doc.sh --open
./doc/build_doc.sh --profile mars
./doc/build_doc.sh --profile generic
./doc/build_doc.sh --profile all
./doc/build_doc.sh --strict-warnings
./doc/build_doc.sh --warnings-baseline doc/doxygen/warnings-baseline --strict-warnings
./doc/build_doc.sh --update-warnings-baseline
```

Fallback direct Doxygen command:

```bash
doxygen doc/Doxyfile
```

Generated output locations:
- Mars HTML entry point: `doc/doxygen/mars/html/index.html`
- Mars warnings log: `doc/doxygen/mars/warnings.log`
- Generic HTML entry point: `doc/doxygen/generic/html/index.html`
- Generic warnings log: `doc/doxygen/generic/warnings.log`

Selector landing page:
- The Doxygen main page is a short profile selector designed to avoid confusion between profile-specific `index.html` files.

Current baseline scope in `doc/Doxyfile`:
- `src/common`
- `src/mars`

Additional profile scopes via `./doc/build_doc.sh`:
- `--profile generic`: `src/common + src/generic`
- `--profile all`: both generated separately (`mars` and `generic` outputs)

Tip:
- The current code already has structured module headers; adding Doxygen-style comments (`!>`, `!!`) over time will improve parameter and routine-level pages.