# Comodo-Admittance Documentation

## Description

Expands the spectrum of a set of atlases using the **admittance method**. The provided list of waves (at least 3) includes both the waves you already have and the waves you want to generate. Missing atlases are created with their constants interpolated or extrapolated using the admittance method. If only waves are provided, the coefficients are printed.

> **Tip:** For better results, use `comodo-detidor` with a complete list of waves.

> **⚠️ Important Warnings:**
>
> - The admittance method may be less reliable in non-linear and mixed semidiurnal zones. Use at your own risk.
> - Input waves must be the strongest in their category. Only the following waves are allowed as input: `M2`, `K2`, `N2`, `K1`, `O1`, `Q1`, `Mf`, `Mm`, and `Mtm`.
> - **Do not include `S2`** in the wave list unless you are fully aware of the risks, as it has a strong radiative component.
> - Combination examples: `K1+O1=M2`, `K1+P1=S2`, and `M1+O1=N2`. See `showarg --combinations` for more details.

---

## Usage

```bash
comodo-admittance [OPTIONS] wave1 wave2 wave3 [wave4 ...]
```

---

## Options


| Option                | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| `-h, --help`          | Display this help message and exit.                                                             |
| `-a <file>`           | Specify the atlas file name convention. See [Convention](#convention3) for details.              |
| `-m <file>`           | Specify the mesh file. Only used for unstructured grids.                                        |
| `-v <var1> <var2>`    | Provide two variable names for amplitude and phase, respectively.                               |
| `-d <discretisation>` | Specify the discretisation (e.g., `LGP2`). If unspecified, a structured grid is assumed.        |
| `-p <prefix>`         | Prefix for forcing admittance of the last wave. **Note:** Not available for unstructured grids. |
| `--keep-average`      | **Note:** Only available for unstructured grids.                                                |


---

(convention3)=
## Convention

The following placeholders are used in file names:

- `"WAVE"`: Replaced by the uppercase name of the wave (e.g., `M2`).
- `"wave"`: Replaced by the lowercase name of the wave (e.g., `m2`).
- `"Wave"`: Replaced by the name of the wave with only the first letter uppercase (e.g., `M2`).

> **Note:** If the file exists without any replacements, no replacement is made.


---

## Wave List

The input waves must be the strongest in their category. Allowed waves:

- `M2`, `K2`, `N2` (semidiurnal)
- `K1`, `O1`, `Q1` (diurnal)
- `Mf`, `Mm`, `Mtm` (long-term)

> **⚠️ Warning:** Avoid using `S2` unless you are aware of the risks.

---

## Examples

### Example 1: Print Coefficients

Print the coefficients for waves `M2`, `K1`, and `O1`:

```bash
comodo-admittance M2 K1 O1
```

### Example 2: Generate Atlases

Generate atlases for waves `M2`, `K1`, `O1`, and `N2` using a structured grid:

```bash
comodo-admittance -a "atlas_{WAVE}.nc" -v amplitude phase M2 K1 O1 N2
```

### Example 3: Unstructured Grid

Generate atlases for waves `M2`, `K1`, and `O1` using an unstructured grid:

```bash
comodo-admittance -a "atlas_{wave}.nc" -m mesh.nc -d LGP2 -v amplitude phase M2 K1 O1
```

### Example 4: Force Admittance for Last Wave

Force admittance for the last wave (`N2`) with a prefix:

```bash
comodo-admittance -a "atlas_{WAVE}.nc" -p forced_ -v amplitude phase M2 K1 O1 N2
```

---

## Environment Variables

No environment variables are explicitly documented for this tool.

---

## Notes

- The admittance method may not be reliable in highly non-linear or mixed semidiurnal zones.
- Always ensure you have read the help message and understand the risks.
- The tool prints a warning message to `stderr` and `stdout` (if redirected) to ensure awareness of the risks.

---

## See Also

- [`comodo-detidor`](https://example.com/comodo-detidor) (recommended for better results)
- [`showarg --combinations`](https://example.com/showarg) (for wave combination details)