Configuration

Cocoa uses YAML configuration files for simulation setup. This document describes all available configuration options.

Configuration File Structure

A complete configuration file contains the following sections:

mesh:
  # Mesh file and projection settings

simulation:
  # Simulation time control

initial_conditions:
  # Initial state

physics:
  # Physical parameters

numeric:
  # Numerical solver parameters

forcing:
  # Forcing configuration (tides, meteorological, ramp)

output:
  # Output file configuration

diagnostics:
  # Logging and screen output

checkpoint:
  # Checkpoint/restart (optional)

Mesh Section

Specifies the mesh file, coordinate projection, and optional coordinate rotation for global meshes.

mesh:
  filename: "mesh.nc"              # Path to mesh file (required)
  projection:
    type: "EquidistantCylindrical" # Projection type (optional)
    center: [-76.5, 23.2]          # Projection center [lon, lat] (optional)
  rotation:                        # Coordinate rotation (optional)
    enabled: false
    pole_location: [0.0, 0.0]      # [longitude, latitude] of new North Pole

Parameters:

Parameter	Type	Default	Description
`filename`	string	(required)	Path to mesh file (NetCDF UGRID format)
`projection.type`	string	`EquidistantCylindrical`	Coordinate projection type
`projection.center`	[lon, lat]	[0.0, 0.0]	Projection center coordinates

Coordinate Rotation (Global Meshes)

For global ocean models, coordinate rotation moves the computational poles away from the geographic poles to avoid singularities.

mesh:
  rotation:
    enabled: true
    pole_location: [0.0, 0.0]  # [longitude, latitude] of new North Pole

Rotation Parameters:

Parameter	Type	Default	Description
`rotation.enabled`	bool	false	Enable coordinate rotation
`rotation.pole_location`	[lon, lat]	(required)	Geographic coordinates where the new North Pole is located [degrees]

When enabled: true, the pole_location parameter must be specified.

Pole Location Specification:

The pole_location specifies where the geographic North Pole will be relocated to in the rotated coordinate system.

Common choices:

[0.0, 0.0]: North Pole moves to the equator at the prime meridian
[180.0, 0.0]: North Pole moves to the equator at the date line
[-90.0, 0.0]: North Pole moves to the equator in the Atlantic

Example: Rotate pole to equator:

mesh:
  rotation:
    enabled: true
    pole_location: [0.0, 0.0]  # Moves North Pole to equator at prime meridian

Effects of rotation:

Node coordinates are transformed to the rotated frame
Coriolis parameter uses rotated latitude
Tidal potential continues to use geographic latitude
Output velocities are transformed back to geographic (east, north) frame

See Coordinate Rotation in the Theory documentation for details and Global Simulations for a complete guide.

Simulation Section

Controls simulation timing.

simulation:
  start_time: 2025-01-01           # Simulation start time (required)
  end_time: 2025-01-15             # Simulation end time (required)
  time_step: 10s                   # Time step (required), e.g. 10s, 1m, 0.5s

Parameters:

Parameter	Type	Default	Description
`start_time`	datetime	(required)	Simulation start time
`end_time`	datetime	(required)	Simulation end time
`time_step`	duration	`1s`	Computational time step. Accepts a duration string (e.g. `4s`, `1m`) or a bare number of seconds (e.g. `10.0`).

DateTime formats supported:

2025-01-01 (date only, midnight assumed)
2025-01-01T12:00:00 (ISO 8601 format)

Initial Conditions Section

Sets initial state for the simulation.

initial_conditions:
  water_level: 0.0                 # Initial water surface elevation [m]

Parameters:

Parameter	Type	Default	Description
`water_level`	float	0.0	Initial water surface elevation [m]

Physics Section

Physical model parameters.

physics:
  manning_n: 0.025                 # Manning's roughness coefficient (or "mesh")
  tau0: 0.005                      # GWCE weighting parameter (or "mesh")
  cf_lower_limit: 0.001            # Minimum friction coefficient
  internal_tide_friction: 0        # Internal tide friction (0, constant, or "mesh")
  smagorinsky_coefficient: 0.2     # Smagorinsky turbulence coefficient
  min_viscosity: 1.0e-6            # Minimum eddy viscosity [m^2/s]
  h0: 0.1                          # Minimum depth threshold [m]
  velmin: 0.01                     # Minimum wetting velocity [m/s]
  wet_dry_slope_limiter: 1.0e9     # Slope limiter coefficient

Parameters:

Parameter	Type	Default	Description
`manning_n`	float or “mesh”	0.025	Manning’s roughness coefficient for bottom friction
`tau0`	float or “mesh”	0.05	GWCE weighting parameter
`cf_lower_limit`	float	0.001	Lower limit for the computed quadratic friction coefficient
`min_depth_friction`	float	0.1	Minimum total water depth (HBREAK) used in the bottom friction computation [m]
`min_velocity_friction`	float	0.0	Minimum velocity used in the bottom friction computation [m/s]
`internal_tide_friction`	float, “mesh”, or 0	0	Internal tide friction coefficient [1/s]. Set to `0` to disable, a constant value to apply uniformly, or `mesh` to read from the mesh file (see Spatially-Varying Parameters).
`h0`	float	0.1	Minimum depth threshold for wet elements [m]
`velmin`	float	0.01	Minimum velocity for node wetting [m/s]
`smagorinsky_coefficient`	float	0.2	Smagorinsky subgrid turbulence coefficient
`min_viscosity`	float	1.0e-6	Minimum eddy viscosity [m^2/s]
`wind_drag_limit`	float	0.0025	Maximum drag coefficient for wind stress
`surface_directional_roughness`	0 or “mesh”	0	Directional effective roughness lengths for wind reduction. Set to `mesh` to read the 12-directional roughness field from the mesh file, or `0` to disable (see Wind Reduction).
`surface_canopy_coefficient`	float or “mesh”	1.0	Canopy coefficient for wind reduction [0–1]. Set to `mesh` to read per-node values from the mesh file, or `1.0` to disable (identity). See Wind Reduction.
`wet_dry_slope_limiter`	float	1.0e9	Slope limiter coefficient

Spatially-Varying Parameters

The manning_n, tau0, internal_tide_friction, surface_directional_roughness, and surface_canopy_coefficient parameters support spatially-varying values from the mesh file. To enable this, set the parameter value to mesh:

physics:
  manning_n: mesh                         # Read from "mannings_n_at_sea_floor"
  tau0: mesh                              # Read from "primitive_weighting_in_continuity_equation"
  internal_tide_friction: mesh            # Read from "internal_tide_friction"
  surface_directional_roughness: mesh     # Read from "surface_directional_effective_roughness_length"
  surface_canopy_coefficient: mesh        # Read from "surface_canopy_coefficient"

When set to mesh, Cocoa will read the corresponding nodal attribute from the NetCDF mesh file:

Parameter	Mesh Variable Name	Description
`manning_n`	`mannings_n_at_sea_floor`	Manning’s n at each node [s/m^(1/3)]
`tau0`	`primitive_weighting_in_continuity_equation`	GWCE tau0 at each node [1/s]
`internal_tide_friction`	`internal_tide_friction`	Internal tide friction coefficient at each node [1/s]. Supports both scalar (1 value per node, isotropic) and tensor (3 values per node: xx, yy, xy components) storage in the mesh file.
`surface_directional_roughness`	`surface_directional_effective_roughness_length`	Directional land roughness lengths at each node [m]. Stored as a 12-component vector (one per 30-degree directional bin).
`surface_canopy_coefficient`	`surface_canopy_coefficient`	Canopy coefficient at each node [dimensionless, 0–1]. Multiplicative reduction applied to wind velocity under forest canopy.

If the mesh file does not contain the required variable when mesh is specified, Cocoa will report an error and exit.

See Mesh Preparation for details on creating mesh files with nodal attributes.

Wind Reduction

When meteorological forcing is enabled, Cocoa can apply two types of overland wind reduction before computing wind stress:

Directional roughness reduction (surface_directional_roughness: mesh): Reduces wind speed based on the ratio of upwind land surface roughness to marine roughness. Uses 12 directional bins (30-degree spacing) with linear interpolation between bins.
Canopy coefficient (surface_canopy_coefficient: mesh): Applies a simple multiplicative reduction to wind components to represent sheltering by forest canopy. A value of 1.0 means no reduction; 0.0 means complete sheltering.

Both reductions are applied in sequence before the drag law computes wind stress. The processing order within the meteorological forcing kernel is:

Apply directional roughness reduction (if enabled)
Apply canopy coefficient (if enabled)
Apply meteorological ramp
Compute kinematic wind stress from the reduced, ramped wind

Example enabling both wind reduction attributes:

physics:
  surface_directional_roughness: mesh   # 12-directional land roughness
  surface_canopy_coefficient: mesh      # Canopy sheltering factor

Bottom Friction:

The friction coefficient is computed from Manning’s n:

\[C_f = \max\left(\frac{g n^2}{H^{1/3}}, C_{f,min}\right)\]

where \(C_{f,min}\) is cf_lower_limit.

Wetting and Drying Algorithm

The wet/dry algorithm controls how elements transition between wet and dry states.

Minimum Depth Threshold (H0):

The h0 parameter sets the minimum total water depth for a node to be considered wet. When the total depth falls below this threshold, the node transitions to dry. Typical values range from 0.01 to 0.5 meters.

Minimum Wetting Velocity (VELMIN):

The velmin parameter controls the minimum velocity required for water to advance onto a dry node during the wetting process. Lower values allow easier wetting but may cause numerical oscillations. Default is 0.01 m/s.

Slope Limiter (SLIM):

The wet_dry_slope_limiter parameter limits water surface gradients in shallow water to prevent spurious oscillations. The limiter computes a scaling factor \(\alpha\) for the elevation gradient:

\[\alpha = \frac{\text{SLIM} \cdot |\nabla h|}{|\nabla \zeta|}\]

where \(h\) is bathymetric depth and \(\zeta\) is water surface elevation. The gradient is scaled by \(\min(\alpha, 1)\).

Default (1.0e9): Effectively disables limiting
Typical active value (0.0004): Applies gradient limiting in shallow areas

Example enabling slope limiting:

physics:
  h0: 0.1
  velmin: 0.01
  wet_dry_slope_limiter: 0.0004

Numeric Section

Numerical solver parameters.

numeric:
  solver: explicit                       # Solver type (default: explicit)
  gwce_coefficients: [0.0, 1.0, 0.0]     # Temporal weights [a00, b00, c00]
  linear_solver:                          # CG solver settings (consistent only)
    type: belos_cg
    tolerance: 1.0e-5
    max_iterations: 50
    convergence_scaling: norm_of_initial_residual

Parameters:

Parameter	Type	Default	Description
`solver`	string	`explicit`	GWCE solver type (see below)
`gwce_coefficients`	[a00, b00, c00]	[0.0, 1.0, 0.0]	GWCE temporal integration weights

Solver Types:

The solver parameter accepts the following values:

Value	Description
`explicit` or `lumped`	Diagonal mass matrix with direct solve (faster, coefficients set to [0, 1, 0])
`implicit`, `iterative`, or `consistent`	Sparse matrix with iterative CG solver (more accurate, semi-implicit)

When using the explicit/lumped solver, the gwce_coefficients are automatically set to [0, 1, 0] regardless of user specification. For the implicit/consistent solver, typical values are [0.35, 0.30, 0.35].

GWCE Coefficients:

The coefficients control temporal weighting in the GWCE:

a00: Weight for time level n+1
b00: Weight for time level n
c00: Weight for time level n-1

Linear Solver Configuration

The linear_solver subsection controls the iterative Conjugate Gradient solver used by the consistent (implicit) GWCE solver. These settings are ignored when using the explicit/lumped solver.

Parameter	Type	Default	Description
`type`	string	`belos_cg`	CG solver implementation (see below)
`tolerance`	float	1.0e-5	Convergence tolerance for the iterative solver. The solver terminates when the (scaled) residual norm drops below this value.
`max_iterations`	int	50	Maximum number of CG iterations per solve. If the solver does not converge within this limit, it reports unconverged.
`verbosity`	int	0	Solver output verbosity: `0` = silent, `1` = summary, `2` = per-iteration.
`convergence_scaling`	string	`norm_of_initial_residual`	How the residual is scaled when testing convergence (see below)

Solver Implementation Types:

The type parameter selects the CG algorithm variant. All variants solve the same linear system with Jacobi preconditioning; they differ in communication pattern and internal implementation.

Value	Description
`belos_cg`	Standard Belos CG. The most portable and well-tested implementation. Uses classical Belos convergence testing with configurable verbosity output.
`tpetra_cg_pipeline`	Tpetra-native pipelined CG. Overlaps communication with computation by pipelining inner products, which can reduce latency on distributed systems with many MPI ranks.
`tpetra_single_reduce`	Tpetra-native single-reduce CG. Combines two inner products per iteration into a single MPI allreduce, reducing synchronization points. Useful on high-latency interconnects.

For most simulations, the default belos_cg is recommended. The Tpetra-native variants may offer better parallel scalability on large distributed runs but produce identical mathematical results.

Convergence Scaling:

The convergence_scaling parameter determines how the residual norm is normalized when checking the convergence criterion.

Value	Description
`norm_of_initial_residual`	Relative convergence: the solver converges when \(\\|r_k\\| / \\|r_0\\| < \text{tolerance}\). This is the most common choice and makes the tolerance independent of problem scaling.
`norm_of_prec_init_res`	Like `norm_of_initial_residual` but scales by the preconditioned initial residual \(\\|M^{-1} r_0\\|\) instead. This can be useful when the preconditioner significantly changes the residual norm.
`none`	Absolute convergence: the solver converges when \(\\|r_k\\| < \text{tolerance}\). The tolerance must be chosen relative to the expected magnitude of the right-hand side.

Example: Consistent solver with custom linear solver settings:

numeric:
  solver: consistent
  gwce_coefficients: [0.35, 0.30, 0.35]
  linear_solver:
    type: belos_cg
    tolerance: 1.0e-6
    max_iterations: 100
    convergence_scaling: norm_of_initial_residual

Forcing Section

Configures tidal and meteorological forcing, along with the spinup ramp.

Ramp Configuration

forcing:
  ramp:
    enabled: true                  # Enable spinup ramp
    duration: 1d                   # Ramp duration (e.g. 1d, 12h, 2d)

Parameters:

Parameter	Type	Default	Description
`ramp.enabled`	bool	true	Enable hyperbolic tangent spinup ramp
`ramp.duration`	duration	`1d`	Duration of spinup ramp. Accepts a duration string (e.g. `1d`, `12h`) or a bare number of seconds.

By default, the same ramp duration is applied to both tidal and meteorological forcing. To use a different ramp for meteorological forcing, add an optional ramp subsection under forcing.meteorological:

forcing:
  ramp:
    enabled: true
    duration: 5d                    # Tidal ramp duration
  meteorological:
    enabled: true
    format: cf_netcdf
    filename: "met.nc"
    ramp:                           # Optional: overrides forcing.ramp for met
      enabled: true
      duration: 1d                  # Shorter met ramp

When the forcing.meteorological.ramp section is absent, meteorological forcing uses the global forcing.ramp values.

Meteorological Ramp Parameters:

Parameter	Type	Default	Description
`meteorological.ramp.enabled`	bool	(from `ramp.enabled`)	Enable met-specific spinup ramp
`meteorological.ramp.duration`	duration	(from `ramp.duration`)	Met ramp duration. Accepts a duration string or a bare number of seconds.

See Meteorological Ramp for details on the ramp function.

Meteorological Forcing

Configures atmospheric wind and pressure forcing. See Meteorological Forcing for full details on file formats and usage.

forcing:
  meteorological:
    enabled: true
    format: cf_netcdf                    # cf_netcdf, owi_ascii, or owi_netcdf
    filename: "path/to/meteo_data.nc"    # Single file (cf_netcdf, owi_netcdf)

Parameters:

Parameter	Type	Default	Description
`meteorological.enabled`	bool	false	Enable meteorological forcing
`meteorological.format`	string	(required)	File format: `cf_netcdf` (aliases: `cf`, `netcdf`), `owi_ascii` (alias: `owi`), or `owi_netcdf`
`meteorological.filename`	string	(required)	Path to meteorological data file (CF NetCDF or OWI NetCDF)
`meteorological.filenames`	list	(required)	List of pressure/wind file pairs (OWI ASCII only)
`meteorological.drag_law`	string	`garratt`	Wind drag coefficient formulation
`meteorological.pressure_scale`	float	100.0	Scale factor for pressure (default converts hPa to Pa)
`meteorological.wind_scale`	float	1.0	Scale factor for wind velocity

CF NetCDF Variable Names:

When using the cf_netcdf format, you can override the default variable names used to read the meteorological data:

forcing:
  meteorological:
    enabled: true
    format: cf_netcdf
    filename: "met_data.nc"
    variables:
      pressure: "mslp"      # Default: "mslp"
      wind_u: "wind_u"      # Default: "wind_u"
      wind_v: "wind_v"      # Default: "wind_v"
      time: "time"          # Default: "time"
      lon: "lon"            # Default: "lon"
      lat: "lat"            # Default: "lat"

For OWI ASCII format, use filenames with paired pressure/wind files:

forcing:
  meteorological:
    enabled: true
    format: owi_ascii
    filenames:
      - pressure: "basin.pre"
        wind: "basin.wnd"

Flow Boundary Forcing

Configures normal-flow (discharge) boundary conditions driven by per-segment time series.

forcing:
  flow_boundary:
    enabled: true
    ramp:                          # Optional spinup ramp for flow boundaries
      enabled: true
      duration: 1d
    segments:
      - segment_index: 0
        time_series_file: "inflow_0.txt"
      - segment_index: 1
        time_series_file: "inflow_1.txt"

Parameters:

Parameter	Type	Default	Description
`flow_boundary.enabled`	bool	false	Enable flow boundary forcing
`flow_boundary.ramp`	ramp	(from `forcing.ramp`)	Optional spinup ramp applied to flow boundaries. Accepts `enabled` and `duration` (see Duration Syntax).
`flow_boundary.segments`	list	(none)	List of flow boundary segments. Each entry maps a flow boundary to a time series file.

Each segments entry contains:

segment_index: Index of the flow boundary segment in the mesh
time_series_file: Path to the discharge time series file for that segment

Tidal Potential Forcing

The tide potential can be computed using either harmonic constituents or the astronomical method. The type parameter selects the method:

constituent (or harmonic): Uses pre-defined tidal constituents
astronomical (or ephemeris, direct): Computes directly from Moon and Sun positions
auto (default): Selects automatically based on what is configured

Harmonic Constituent Method:

forcing:
  tide:
    potential:
      enabled: true
      type: constituent
      constituents:
        - name: M2
          frequency: 0.000140518902509  # rad/s
          amplitude: 0.242334           # m
          etrf: 0.693                   # Earth tide reduction factor
          nodal_factor: 0.96461         # Nodal modulation
          equilibrium_arg: 315.69       # degrees

Constituent Parameters:

Parameter	Units	Description
`name`	string	Constituent name (Q1, O1, P1, K1, N2, M2, S2, K2, etc.)
`frequency`	rad/s	Angular frequency
`amplitude`	m	Tidal potential constant K
`etrf`		Earth tide reduction factor
`nodal_factor`		Nodal modulation factor f
`equilibrium_arg`	degrees	Equilibrium argument V+u

Astronomical Method:

forcing:
  tide:
    potential:
      enabled: true
      type: astronomical
      astronomical:
        order: 4               # Expansion order: 2=P2, 3=P3, 4=exact
        include_nutation: true  # Include nutation corrections
        k2: 0.302              # Love number (optional)
        h2: 0.609              # Love number (optional)

Astronomical Parameters:

Parameter	Default	Description
`order`	4	Legendre polynomial expansion order. 2 (P2) is standard equilibrium tide; 3 (P3) adds degree-3 corrections; 4 uses full expansion.
`include_nutation`	true	Include nutation corrections in celestial position calculations.
`k2`	0.302	Second-degree Love number for body tide.
`h2`	0.609	Second-degree Love number for vertical displacement.

When using the astronomical method, individual constituent specification is not needed. See Tidal Forcing for details.

Tidal Boundary Forcing

Elevation-specified tidal boundary conditions.

forcing:
  tide:
    boundary:
      enabled: true
      constituents:
        - name: M2
          frequency: 0.000140518902509  # rad/s
          nodal_factor: 0.96461          #
          equilibrium_arg: 315.69        # degrees
          boundary_values:               # Per-node amplitude/phase
            - { amplitude: 0.52, phase: 344.17 }
            - { amplitude: 0.51, phase: 345.15 }
            # ... one entry per open boundary node

Constituent Parameters:

Parameter	Units	Description
`name`	string	Constituent name
`frequency`	rad/s	Angular frequency
`nodal_factor`		Nodal modulation factor
`equilibrium_arg`	degrees	Equilibrium argument
`boundary_values`	list	Per-node amplitude [m] and phase [degrees]

Each boundary_values entry contains:

amplitude: Tidal amplitude in meters
phase: Tidal phase in degrees

Self-Attraction and Loading (SAL)

SAL corrections account for the ocean’s gravitational self-attraction and Earth deformation under tidal loads. SAL data must be pre-computed and embedded in the mesh file (see Tidal Forcing).

forcing:
  tide:
    sal:
      enabled: true
      parameter_source: "auto"    # or "manual"

Parameters:

Parameter	Default	Description
`enabled`	false	Enable SAL forcing
`parameter_source`	“auto”	How to determine constituent parameters. `"auto"` looks up frequencies and nodal factors from the built-in tidal database. `"manual"` uses values provided in the `constituents` list.

In manual mode, provide constituent parameters explicitly:

forcing:
  tide:
    sal:
      enabled: true
      parameter_source: "manual"
      constituents:
        - name: M2
          frequency: 1.405189028e-04   # rad/s
          nodal_factor: 1.026777
          equilibrium_arg: 26.668130   # degrees

Output Section

Controls simulation output. By default the output file is named cocoa_output.nc in the working directory. Use the filename parameter to specify a different name.

output:
  filename: "cocoa_output.nc"      # Output file name (optional, default: cocoa_output.nc)
  step_interval: 1h                # Output every hour (duration or integer step count)
  mode: split                      # "split" (default) or "combined"
  variables:                       # Selectively disable time-series variables
    pressure: false
    wind: false

Parameters:

Parameter	Type	Default	Description
`filename`	string	`cocoa_output.nc`	Output file name (NetCDF format)
`step_interval`	int or duration	100	Interval between output writes. Accepts a plain integer (number of time steps) or a duration string with suffix: `s` (seconds), `m` (minutes), `h` (hours), `d` (days). Fractional values are allowed (e.g., `0.5h`). The duration must be evenly divisible by the simulation time step.
`mode`	string	`split`	Controls where peak variables are written. In `split` mode (default), peak variables are written to a separate file named `<filename>_peak.nc` (e.g., `cocoa_output_peak.nc`). In `combined` mode, peak variables are included in the main output file. See Output Files for details.
`variables`	map	(all enabled)	Selectively disable time-series output variables. List variable names with `false` to disable them. Omitted variables remain enabled. Peak variables are always written and cannot be disabled. Available names: `zeta`, `velocity`, `pressure`, `wind`, `tide_potential`. See Output Files for the full variable reference.

Diagnostics Section

Controls logging and screen output.

diagnostics:
  screen_interval: 2h              # Screen output every 2 hours (duration or integer step count)
  log_file: "simulation.log"       # Structured log file path (optional)

Parameters:

Parameter	Type	Default	Description
`screen_interval`	int or duration	100	Interval between screen output. Accepts a plain integer (number of time steps) or a duration string (e.g., `30m`, `1h`). See Duration Syntax for the full syntax.
`log_file`	string	(none)	Path to log file (JSON structured log format)

Checkpoint Section

Configures checkpoint/restart for long-running simulations. See Checkpoint / Restart for a complete guide.

checkpoint:
  enabled: true
  write_interval: 12h            # Write checkpoint every 12 hours
  file_prefix: "cocoa_checkpoint"  # Prefix for checkpoint files
  restart_file: ""               # Path to checkpoint file to restart from

Parameters:

Parameter	Type	Default	Description
`enabled`	bool	false	Enable the checkpoint/restart system
`write_interval`	int or duration	0	How often to write checkpoints. `0` (the default) writes a single checkpoint at the end of the run; a positive value writes every `N` time steps plus one at the final step. Accepts a plain integer (number of time steps) or a duration string (e.g., `6h`, `1d`). See Duration Syntax for the full syntax.
`file_prefix`	string	`cocoa_checkpoint`	Filename prefix. Each write produces a timestamped file `{prefix}.{simulation_time}.nc` (e.g. `cocoa_checkpoint.20250101T120000.nc`).
`restart_file`	string	(none)	Path to a checkpoint file to restart from. When set, the simulation resumes from the saved state.

Writing checkpoints:

checkpoint:
  enabled: true
  write_interval: 12h
  file_prefix: "cocoa_checkpoint"

Restarting from a checkpoint:

checkpoint:
  enabled: true
  restart_file: "cocoa_checkpoint.20250101T120000.nc"

Complete Example

A complete configuration file for a tidal simulation:

mesh:
  filename: "gulf_mesh.nc"
  projection:
    type: "EquidistantCylindrical"
    center: [-90.0, 25.0]

simulation:
  start_time: 2025-01-01
  end_time: 2025-01-15
  time_step: 10s

initial_conditions:
  water_level: 0.0

physics:
  manning_n: 0.025
  tau0: 0.005
  cf_lower_limit: 0.001

numeric:
  solver: implicit
  gwce_coefficients: [0.35, 0.30, 0.35]
  linear_solver:
    type: belos_cg
    tolerance: 1.0e-5
    max_iterations: 50

forcing:
  ramp:
    enabled: true
    duration: 1d
  tide:
    potential:
      enabled: false
    boundary:
      enabled: true
      constituents:
        - name: M2
          frequency: 1.405189028e-04
          nodal_factor: 0.964
          equilibrium_arg: 23.06
          boundary_values:
            - { amplitude: 0.50, phase: 340.0 }
            - { amplitude: 0.48, phase: 342.0 }
            # ... additional boundary nodes

output:
  filename: "gulf_output.nc"
  step_interval: 10m

diagnostics:
  screen_interval: 1h

Duration Syntax

Time-based fields share a common duration grammar. A duration string consists of a numeric value followed by a unit suffix:

Suffix	Unit	Example
`s`	seconds	`30s` = 30 seconds
`m`	minutes	`20m` = 20 minutes
`h`	hours	`1h` = 1 hour
`d`	days	`1d` = 1 day

The grammar is used by two groups of fields with slightly different handling of a bare number (one with no suffix):

Pure durations – simulation.time_step and the ramp duration fields (forcing.ramp.duration, forcing.meteorological.ramp.duration, forcing.flow_boundary.ramp.duration). A bare number is interpreted as seconds (time_step: 2.0 is identical to time_step: 2s).
Step intervals – output.step_interval, diagnostics.screen_interval and checkpoint.write_interval. A bare integer is interpreted as a count of time steps (step_interval: 3600 means every 3600 steps). A suffixed duration must be evenly divisible by time_step; for example 20m with time_step: 7s errors because 1200 s is not a multiple of 7 s.

Rules:

Fractional values are allowed: 0.5h = 30 minutes, 0.25d = 6 hours.
0 disables an interval (used for write_interval to disable checkpointing).

Examples:

simulation:
  time_step: 2s                   # 2-second time step (or: 2.0)

forcing:
  ramp:
    duration: 12h                 # 12-hour spinup ramp (or: 43200)

output:
  step_interval: 15m              # Every 15 minutes (= 450 steps)

diagnostics:
  screen_interval: 2h             # Every 2 hours (= 3600 steps)

checkpoint:
  enabled: true
  write_interval: 12h             # Every 12 hours (= 21600 steps)

Unit Conventions

Cocoa follows the following conventions for input units:

Quantity	Input Units	Internal Units
Tidal frequency	rad/s	rad/hr
Angles (phase, equilibrium_arg)	degrees	radians
Amplitude	meters	meters
Time step	seconds	seconds
Ramp duration	days	days

Environment Variables

Cocoa uses standard environment variables for runtime configuration:

Variable	Description	Default
`OMP_NUM_THREADS`	Number of OpenMP threads (CPU backend)	All available
`CUDA_VISIBLE_DEVICES`	GPU device selection (CUDA backend)	0