# ROMS simulation settings (compile-time)
While most settings in ROMS are controlled at runtime via a namelist file (see corresponding doc page), CPP macros are used to include or exclude large blocks of code at compile time, effectively acting as switches for features of the model. These are controlled in the `cppdefs.opt` (enabled with `#define <CPPKEY>` or disabled with `#undef <CPPKEY>`), which should be placed alongside the `Makefile` in the directory where the ROMS executable is being compiled.

An example of this file is provided at `$ROMS_ROOT/src/cppdefs.opt`.

This page contains a description of all the settings in the `cppdefs.opt` file. Each section of the file gets a section of the page below including a table of switches described in that section. For each switch, the table indicates whether it is enabledd or disabledd in the default configuration.

### `MODEL SETUP OPTIONS`

These switches control fundamental aspects of the model setup, including the equation of state, dimensionality, and core physical processes.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `EXACT_RESTARTS` | Attempt to do an exact restart using the initial conditions | enabled | Requires two time records in the init file; will return a warning but not crash the model if two records are not available. Only known to work with double-precision output. |
| `NONLIN_EOS` | Use Jackett and McDougall (1995) nonlinear equation of state | enabled | |
| `SALINITY` | Use salinity as a thermodynamic variable | enabled | |
| `SOLVE3D` | Solve the governing equations in three dimensions | enabled | We have never tested what happens if this is undefined |
| `SPLIT_EOS` | Use an equation of state that ensures that monotonically increasing density is equivalent to stable stratification | enabled | |
| `TIDES` | Apply tidal forcing | enabled | |
| `UV_ADV` | Use advection in horizontal momentum equations | enabled | |
| `UV_COR` | Use Coriolis term in horizontal momentum equations | enabled | |
| `ADV_ISONEUTRAL` | Rotate the advection and diffusion operators so they are oriented in the isoneutral direction | disabled | |
| `ALLOW_SINGLE_BLOCK_MODE` | Switch to allow mixed [tiled + single-block] execution in OpenMP | disabled | Useful for debugging purposes only. Normally should be kept undefined. |
| `CONST_TRACERS` | Keep tracer values constant in time and space | disabled | At each timestep the tracer tendencies will be calculated, but in the end it will just keep the value it had at the previous timestep |
| `DIAGNOSTICS` | enabled the calculation and writing of "diagnostics" (term-by-term momentum and tracer budgets) | disabled | Options are set in `diagnostics.opt` |
| `DIAGNOSTICS_NHMG` | enabled the calculation and writing of "diagnostics" for the nonhydrostatic vertical velocity equation | disabled | |
| `NHMG` | Use non-hydrostatic momentum equations | disabled | Solves prognostically for the vertical velocity. Approximately doubles the cost of the model. WARNING: Presently untested and unmaintained by [C]Worthy. May break important features like exact restarts, and may require extra inputs to work successfully (unknown). |
| `NHMGDIAG` | Write momentum equation diagnostics for non-hydrostatic mode | disabled | |
| `PRINT_HOSTNAME` | During initialization print information about the HPC cluster and MPI setup | disabled | |
| `PRINT_TILE_RANGES` | Make each MPI rank print the size of its local subdomain | disabled | |
| `CDR_FORCING` | enabled special forcing for marine CO2 removal | disabled | Required inputs and fields are specified in `cdr_frc.opt`. |
| `UPSCALING` | Save advective tendencies at lateral boundaries for use in upscaling applications | disabled | Meant to be used in child domains when forcing will be subsequently applied to parent domains. Only saves ALK and DIC perturbations. Requires `MARBL` and `MARBL_DIAGS` to be enabledd. |

### `GRID OPTIONS`

These switches control the configuration of the model grid, including geometry, masking, and boundary treatment.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `CURVGRID` | Use an orthogonal curvilinear grid | enabled | Makes slight adjustments to the velocity tendencies due to spatial changes in dx and dy |
| `MASKING` | Use land masks for tracer and velocity points to set values to zero | enabled | It is recommended that this flag is always enabledd |
| `SPHERICAL` | Use a spherical geometry in the grid setup | enabled | The model will look for coordinates based on latitude and longitude instead of distance |
| `SPONGE` | Increase viscosity and diffusivity for momentum and tracers near the lateral boundaries | enabled | The magnitude is set under the header `v_sponge` in the runtime `.in` file |
| `ANA_GRID` | Analytically prescribe the grid | disabled | Hardcoded in `analytical.F` |
| `EW_PERIODIC` | Make the domain periodic in the east-west direction | disabled | This has not been tested or used, so it is unclear whether it would induce conflicts with more recent code |
| `NON_TRADITIONAL` | Use horizontal components of Coriolis force | disabled | Presently only affects density calculation (possibly incomplete implementation?) |
| `NS_PERIODIC` | Make the domain periodic in the north-south direction | disabled | This has not been tested or used, so it is unclear whether it would induce conflicts with more recent code |

### `ATMOSPHERIC FORCING`

These switches control the application of atmospheric forcing to the model surface.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `BULK_FRC` | Use the bulk forcing module for atmospheric forcing | enabled | ROMS will use flux forcing if this CPP key is not set and the `ANA_` keys are not present |
| `ANA_SMFLUX` | Analytically prescribe surface momentum flux (with flux forcing) | disabled | Hardcoded in `analytical.F` |
| `ANA_SRFLUX` | Analytically prescribe surface shortwave radiative flux (with flux forcing) | disabled | Hardcoded in `analytical.F` |
| `ANA_SSFLUX` | Analytically prescribe surface salinity flux (with flux forcing) | disabled | Hardcoded in `analytical.F` |
| `ANA_STFLUX` | Analytically prescribe surface heat flux (with flux forcing) | disabled | Hardcoded in `analytical.F` |
| `DIURNAL_SRFLUX` | Modulate daily-averaged shortwave radiation to simulate a diurnal cycle | disabled | This seems to be an artifact from a time before hourly swrad was available. Likely obsolete for this reason. |
| `QCORRECTION` | Apply restoring to sea surface temperature | disabled | |
| `SFLX_CORR` | Apply restoring to sea surface salinity | disabled | |
| `TAU_CORRECTION` | Apply a correction to the wind stress to bring it closer to observations | disabled | Only used in conjunction with the `BULK_FRC` module. Requires additional fields in the input file. |

### `NUMERICAL ALGORITHMS`

These switches control the numerical schemes used by the model for advection.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `AKIMA` | Use the fourth-order Akima scheme for horizontal advection | disabled | Overrides the default 3rd-order upstream advection |
| `AKIMA_V` | Use the fourth-order Akima scheme for vertical advection | disabled | Overrides the default piecewise parabolic reconstruction |

### `BOUNDARY CONDITIONS`

These switches control the configuration of the open boundaries, including which sides are open and which schemes are used to apply forcing and allow waves to exit.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `M2_FRC_BRY` | Apply barotropic (2D) momentum forcing at the open boundaries | enabled | Can be combined with other keys (`M2NUDGING`, `OBC_M2SPECIFIED`) to have different effects. Requires inputs for `ubar` and `vbar`. |
| `M3_FRC_BRY` | Apply baroclinic (3D) momentum forcing at the open boundaries | enabled | Can be combined with other keys (`SPONGE_TUNE`, `OBC_M3SPECIFIED`) to have different effects. Requires inputs for `u` and `v` (and `w`, if non-hydrostatic). |
| `OBC_EAST` | Use an open boundary on the "east" side of the domain | enabled | "East" in this context refers to MPI nodes with i-rank = `NP_XI-1` |
| `OBC_M2FLATHER` | Use the Flather scheme for the 2D dynamical fields at open boundaries | enabled | |
| `OBC_M3ORLANSKI` | Use the Orlanski scheme for the 3D dynamical fields at open boundaries | enabled | Designed to allow waves to exit the domain with minimal reflection |
| `OBC_NORTH` | Use an open boundary on the "north" side of the domain | enabled | "North" in this context refers to MPI nodes with j-rank = `NP_ETA-1` |
| `OBC_SOUTH` | Use an open boundary on the "south" side of the domain | enabled | "South" in this context refers to MPI nodes with j-rank = 0 |
| `OBC_TORLANSKI` | Use the Orlanski scheme for the thermodynamical fields at open boundaries | enabled | Designed to allow waves to exit the domain with minimal reflection |
| `OBC_WEST` | Use an open boundary on the "west" side of the domain | enabled | "West" in this context refers to MPI nodes with i-rank = 0 |
| `T_FRC_BRY` | Apply tracer forcing at the open boundaries | enabled | Requires inputs for each thermodynamic and biogeochemical tracer. |
| `Z_FRC_BRY` | Apply SSH forcing at the open boundaries | enabled | Requires inputs for SSH. |
| `ANA_BRY` | Analytically prescribe the lateral boundary conditions | disabled | Hardcoded in `analytical.F` |
| `OBC_M2ORLANSKI` | Use the Orlanski scheme for the 2D dynamical fields at open boundaries | disabled | Designed to allow waves to exit the domain with minimal reflection |
| `OBC_M3SPECIFIED` | Use "clamped" boundary conditions for the 3D dynamical fields at open boundaries | disabled | |
| `OBC_RAD_NORMAL` | Calculate radiation for the Orlanski scheme using only the normal component of the velocity | disabled | Only has an effect if `OBC_M2ORLANSKI` or `OBC_M3ORLANSKI` is enabledd |
| `OBC_RAD_NPO` | Explicitly set radiation for the Orlanski scheme to be zero for the velocity parallel to the boundary | disabled | Only has an effect if `OBC_RAD_NORMAL` is enabledd |
| `OBC_TSPECIFIED` | Use "clamped" boundary conditions for the thermodynamical fields at open boundaries | disabled | |
| `SPONGE_TUNE` | Add baroclinic pressure fluxes at open boundaries | disabled | Used in the child domain during downscaling of nested simulations. Requires pressure fluxes to be saved in the parent simulation. Use is optional. |

### `MIXING OPTIONS`

These switches control the model's mixing parameterizations, including vertical mixing schemes (KPP and others) and lateral diffusion/viscosity.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `LMD_BKPP` | Use the KPP parameterization (Large et al., 1994) in the bottom boundary layer | enabled | |
| `LMD_KPP` | Use the KPP parameterization (Large et al., 1994) in the surface boundary layer | enabled | |
| `LMD_MIXING` | enabled and compute various parameterizations from Large et al., 1994 (KPP, etc.) | enabled | This is the overarching CPP key for all other `LMD` keys. This needs to be defined in order for KPP and others to be used. |
| `LMD_NONLOCAL` | Compute the non-local term in the KPP parameterization | enabled | Can be used with either/both `LMD_KPP` and `LMD_BKPP` |
| `LMD_RIMIX` | Compute mixing due to breaking internal waves | enabled | Designed only to have an effect where local gradient Richardson number is small |
| `TS_DIF2` | Apply Laplacian diffusion along sigma-surfaces | enabled | Diffusivities are specified under the `tracer_diff2` header in the runtime `.in` file |
| `UV_VIS2` | Apply Laplacian viscosity along sigma-surfaces | enabled | Viscosities are specified under the `lateral_visc` header in the runtime `.in` file |
| `LMD_DDMIX` | Compute double-diffusive mixing (Large et al., 1994) | disabled | |
| `ANA_VMIX` | Analytically prescribe vertical mixing coefficient | disabled | Hardcoded in `analytical.F` |
| `EASTERN_WALL` | Treat the eastern boundary as if it is a "wall" in the calculation of the biharmonic viscosity | disabled | Only affects how the biharm viscosity is computed; has no other effect |
| `MERGE_OVERLAP` | If surface and bottom boundary layers overlap, set them both to be the entire depth of the water column | disabled | Unclear whether this is needed for physical or numerical reasons; disabledd by default |
| `MY25_MIXING` | Mellor-Yamada second-order vertical mixing scheme | disabled | |
| `NORTHERN_WALL` | Treat the northern boundary as if it is a "wall" in the calculation of the biharmonic viscosity | disabled | Only affects how the biharm viscosity is computed; has no other effect |
| `SOUTHERN_WALL` | Treat the southern boundary as if it is a "wall" in the calculation of the biharmonic viscosity | disabled | Only affects how the biharm viscosity is computed; has no other effect |
| `TS_DIF4` | Apply biharmonic diffusion along sigma-surfaces | disabled | Currently not fully implemented (do not use) |
| `WESTERN_WALL` | Treat the western boundary as if it is a "wall" in the calculation of the biharmonic viscosity | disabled | Only affects how the biharm viscosity is computed; has no other effect |

### `BIOGEOCHEMICAL OPTIONS`

These switches control the biogeochemical (BGC) model. Two BGC models are available — MARBL and BEC — though they cannot be used simultaneously.

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `MARBL` | Use the MARBL biogeochemical library | enabled | Cannot be used simultaneously with `BIOLOGY_BEC2` |
| `MARBL_DIAGS` | enabled the writing of diagnostics and other variables from the MARBL biogeochemical library | enabled | Specific variables can be requested in the runtime `marbl_diagnostic_output_list` file |
| `NHY_FORCING` | Use ammonia atmospheric forcing | enabled | |
| `NOX_FORCING` | Use nitrogen oxide atmospheric forcing | enabled | |
| `PCO2AIR_FORCING` | Use atmospheric forcing for CO2 | enabled | |
| `BIOLOGY_BEC2` | enabled BEC biogeochemical model | disabled | Only associated with BEC |
| `BEC2_DIAG` | enabled BEC diagnostics | disabled | Only associated with BEC |
| `DAILYPAR_BEC` | Use the daily averaged photosynthetically available radiation instead of instantaneous | disabled | Only works with BEC, and only with `BULK_FRC` enabledd |
| `BIO_1ST_USTREAM_TEST` | Use a 1st-order advection scheme only for BGC tracers | disabled | Likely for testing purposes only |
| `BBL` | Use a bottom boundary layer formulation in updating sediment thickness | disabled | Only used in the "sediment" module associated with BEC |
| `NO3_RESTORE` | Restore to specified concentration of nitrate | disabled | Only works with BEC2. May require an input file (unknown) |
| `Ncycle_SY` | Nitrogen Cycle with NO2, N2O and N2 tracers | disabled | Only works with BEC2 |
| `TDEP_REMIN` | Apply temperature dependency for particulate remineralization | disabled | Only used in the BEC2 biogeochemical module |

### `MISCELLANEOUS`

| Switch | Description | Default | Usage notes |
|--------|-------------|---------|-------------|
| `ANA_INITIAL` | Analytically prescribe the initial conditions | disabled | Hardcoded in `analytical.F` |
| `ANA_PIPES` | Analytically prescribe pipe forcing | disabled | Hardcoded in `ana_grid.h` |