# excalibur v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`excalibur` is a tool designed to **co-locate and compute the difference** between height measurement points (time, longitude, latitude, value) and simulation data. It is particularly useful for comparing observational data (e.g., from GPS or altimetry) with model outputs.

> **Note:** Options `-p`, `-c`, and `-g` are **mandatory** for execution.

---

## Usage

```bash
excalibur [OPTIONS] file -o output_file
```

---

## Options


| Option                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `--help`, `-h`               | Display help and exit.                                                                  |
| `-p <path>`                  | Path to the directory containing simulation output files. **Mandatory.**                |
| `-c <convention>`            | Convention for reading simulation files (e.g., `tugo.state-YYYY.MM.nc`). **Mandatory.** |
| `-g <file>`                  | Path to the vertical reference file (e.g., `ign69_wgs84-1-float.grd`). **Mandatory.**   |
| `-o <file>`                  | Name of the output file.                                                                |
| `-f <format>`                | Format of the output file.                                                              |
| `-s <number>`                | Number of samples to use. **Default:** `30`.                                            |
| \`-d \[true                  | false\]\`                                                                               |
| `--meanlevel-offset <value>` | Value of the mean sea level offset to remove.                                           |
| `--polygon <file>`           | Path to a polygon file to limit the working area.                                       |
| `--altimetry`                | Enable altimetry mode.                                                                  |
| `--reference`                | Enable reference mode. Requires an additional argument for the survey.                  |


---

## Examples

### **Basic Usage**

Compare a trajectory file with simulation data and generate an output file:

```bash
excalibur -p /home/models/simulation/gironde-tugo/run-R15 \
  -c tugo.state-YYYY.MM.nc \
  -g ign69_wgs84-1-float.grd \
  cnav181016_lam1_air_a2.track_fmt_300_lis \
  -o cnav181016-R15_B01_F00-2018-30sec.xyz
```

### **Using a Polygon File**

Limit the working area using a polygon file:

```bash
excalibur -p /home/models/simulation/gironde-tugo/run-R15 \
  -c tugo.state-YYYY.MM.nc \
  -g ign69_wgs84-1-float.grd \
  --polygon seine-string.plg \
  cnav181016_lam1_air_a2.track_fmt_300_lis \
  -o output.xyz
```

### **Adjusting Mean Sea Level Offset**

Remove a mean sea level offset of `0.5` meters:

```bash
excalibur -p /home/models/simulation/gironde-tugo/run-R15 \
  -c tugo.state-YYYY.MM.nc \
  -g ign69_wgs84-1-float.grd \
  --meanlevel-offset 0.5 \
  cnav181016_lam1_air_a2.track_fmt_300_lis \
  -o output.xyz
```

### **Enabling Nudging Diagnostics**

Add nudging diagnostics (RMS and mean) to the output:

```bash
excalibur -p /home/models/simulation/gironde-tugo/run-R15 \
  -c tugo.state-YYYY.MM.nc \
  -g ign69_wgs84-1-float.grd \
  -d true \
  cnav181016_lam1_air_a2.track_fmt_300_lis \
  -o output.xyz
```

### **Using Altimetry Mode**

Enable altimetry mode for specialized processing:

```bash
excalibur -p /home/models/simulation/gironde-tugo/run-R15 \
  -c tugo.state-YYYY.MM.nc \
  -g ign69_wgs84-1-float.grd \
  --altimetry \
  cnav181016_lam1_air_a2.track_fmt_300_lis \
  -o output.xyz
```

### **Using Reference Mode**

Enable reference mode with a survey argument:

```bash
excalibur -p /home/models/simulation/gironde-tugo/run-R15 \
  -c tugo.state-YYYY.MM.nc \
  -g ign69_wgs84-1-float.grd \
  --reference survey_name \
  cnav181016_lam1_air_a2.track_fmt_300_lis \
  -o output.xyz
```

---

## Environment Variables

`excalibur` uses **OpenMP** (version 201511) for parallelization. The following environment variables can be used to control its behavior:


| Variable          | Description                                   |
| ----------------- | --------------------------------------------- |
| `OMP_NUM_THREADS` | Number of threads to use.                     |
| `OMP_SCHEDULE`    | Runtime schedule type and chunk size.         |
| `OMP_DYNAMIC`     | Enable/disable dynamic adjustment of threads. |
| `OMP_NESTED`      | Enable/disable nested parallelism.            |


**Example:**

```bash
OMP_NUM_THREADS=6 excalibur -p /path/to/simulation -c convention.nc -g reference.grd file.track -o output.xyz
```

> **Note:** If running on a machine with high CPU load, limit the number of threads to the number of **free CPUs** to avoid performance degradation.

---

## Notes

1. **Mandatory Options:**
  - `-p`, `-c`, and `-g` **must** be provided for the tool to run.
2. **Input Files:**
  - The trajectory file (e.g., `cnav181016_lam1_air_a2.track_fmt_300_lis`) must contain height measurement points in the format `(time, lon, lat, value)`.
  - Simulation files must follow the convention specified by `-c`.
3. **Output:**
  - The output file (`-o`) will contain the co-located differences between the measurement points and simulation data.
4. **Performance:**
  - For large datasets, consider adjusting `OMP_NUM_THREADS` to optimize performance.
5. **Modes:**
  - `--altimetry` and `--reference` are **mutually exclusive** with the default navigation mode.

---

## See Also

- [OpenMP Documentation](https://www.openmp.org/) (for environment variables and parallelization details)