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¶

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:

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:

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:

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:

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:

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:

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:

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¶

Mandatory Options:

-p, -c, and -g must be provided for the tool to run.

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.

Output:

The output file (-o) will contain the co-located differences between the measurement points and simulation data.

Performance:

For large datasets, consider adjusting OMP_NUM_THREADS to optimize performance.

Modes:

--altimetry and --reference are mutually exclusive with the default navigation mode.