# grid-archives v3.2.3

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

---

## Description

`grid-archives` converts **TUGOm output** to **simuSWOT-compliant landscape files**. The output grid **must** be specified using **either** the `-z` (zone name) **or** `-g` (grid file) option.

---

## Usage

```bash
grid-archives [OPTIONS]
```

---

## Options


| Option                   | Description                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`           | Display help and exit.                                                                                    |
| `-p <dir>`               | Input directory. **Default:** Current directory (`.`)                                                     |
| `-c <convention>`        | Input file naming convention. **Default:** `analysis.YYYY-MM.nc`                                          |
| `-b <file1> [file2 ...]` | Input topography file(s). Multiple files are allowed, processed in order of priority (highest to lowest). |
| `-z <zone>`              | Output grid zone name. **Mutually exclusive with `-g`**.                                                  |
| `-g <file>`              | Output grid file. **Mutually exclusive with `-z`**.                                                       |
| `-f <file>`              | Flood limits polygon file.                                                                                |
| `-d <date>`              | Working date in the format `YYYY/MM/DD_HH:MN:SS[...]`. **Required.**                                      |
| `-o <dir>`               | Output directory. **Default:** Current directory (`.`)                                                    |


---

## Examples

### **Basic Conversion with Zone Name**

Convert TUGOm output to simuSWOT-compliant files using a predefined zone:

```bash
grid-archives -p /path/to/input -z "Europe" -d 2026/05/22_12:00:00 -o /path/to/output
```

### **Basic Conversion with Grid File**

Convert TUGOm output using a custom grid file:

```bash
grid-archives -p /path/to/input -g /path/to/grid.nc -d 2026/05/22_12:00:00 -o /path/to/output
```

### **Specify Input Convention**

Use a custom naming convention for input files:

```bash
grid-archives -p /path/to/input -c "custom.YYYY-MM-DD.nc" -z "Europe" -d 2026/05/22_12:00:00
```

### **Include Topography Files**

Specify multiple topography files (processed in order of priority):

```bash
grid-archives -p /path/to/input -b topo1.nc topo2.nc -z "Europe" -d 2026/05/22_12:00:00
```

### **Apply Flood Limits**

Use a polygon file to define flood limits:

```bash
grid-archives -p /path/to/input -z "Europe" -f flood_limits.plg -d 2026/05/22_12:00:00
```

### **Full Example**

Combine all options for a complete conversion:

```bash
grid-archives \
  -p /path/to/input \
  -c "custom.YYYY-MM-DD.nc" \
  -b topo1.nc topo2.nc \
  -z "Europe" \
  -f flood_limits.plg \
  -d 2026/05/22_12:00:00 \
  -o /path/to/output
```

---

## Environment Variables

`grid-archives` does not rely on specific environment variables. However, ensure that:

- Input and output directories are **accessible** and **writable**. 
- The system has sufficient **memory** for processing large grid files.

---

## Notes

1. **Grid Specification:**
  - **Either** `-z` (zone name) **or** `-g` (grid file) **must** be provided. Using both will result in an error.
2. **Date Format:**
  - The date **must** be specified using the `-d` option in the format `YYYY/MM/DD_HH:MN:SS[...]`.
3. **Input Files:**
  - The input directory (`-p`) must contain files matching the specified convention (`-c`).
  - If no convention is provided, the default `analysis.YYYY-MM.nc` is used.
4. **Topography Files:**
  - Multiple topography files can be provided using `-b`. They are processed in the order they are listed (highest priority first).
5. **Output:**
  - The output directory (`-o`) will contain the generated `grid-archives-<zone>.nc` file.

---

## See Also

- [TUGOm Documentation](https://www.tugom.org/)
- [simuSWOT Project](https://www.simuswot.org/)