Quick Start

This guide will help you run your first Cocoa simulation.

Command-Line Usage

Usage: cocoa -i FILE [OPTIONS]
Cocoa - Coastal and Ocean Circulation on Accelerators

OPTIONS:
  -h,     --help              Print this help message and exit
  -i,     --input FILE        Input configuration file
  -v,     --verbose           Enable verbose logging (debug level)
  -p,     --partition FILE    Partition cache file: used if it exists, created otherwise
          --create-partition N
                              Create a partition cache for N subdomains and exit (N >= 1)
          --kokkos-help       Show Kokkos command line options
          --kokkos-enable-warnings
                              Enable Kokkos warning messages
  -V,     --version           Show version information and exit

Unrecognized options are passed through to the Kokkos runtime.

Examples:
  cocoa -i my_config.yaml
  cocoa -i config.yaml --verbose
  cocoa -i config.yaml --kokkos-num-threads=4
  mpirun -np 2 cocoa -i config.yaml --partition partition.nc

The -i (--input) option is required and must name an existing YAML configuration file; there is no default configuration file name.

Simulation Flow

Each timestep follows this sequence:

digraph timestep { rankdir=TB; node [shape=box, style="filled,rounded", fontname="Helvetica", fontsize=10]; edge [color="#555555"]; bgcolor="transparent"; start [label="Advance Time Level", fillcolor="#E0E0E0", color="#616161"]; forcing [label="Update Forcing\n(tides, ramp)", fillcolor="#FFF3E0", color="#FB8C00"]; gwce [label="GWCE Solve\n(elevation update)", fillcolor="#E3F2FD", color="#1E88E5"]; ghost1 [label="Ghost Exchange\n(elevation)", fillcolor="#F3E5F5", color="#8E24AA"]; wetdry [label="Wetting / Drying\n(element status)", fillcolor="#E8F5E9", color="#43A047"]; ghost2 [label="Ghost Exchange\n(wet/dry status)", fillcolor="#F3E5F5", color="#8E24AA"]; momentum [label="Momentum Solve\n(velocity, flux)", fillcolor="#E3F2FD", color="#1E88E5"]; bc [label="Apply Elevation/Velocity\nBoundary Conditions", fillcolor="#FFF3E0", color="#FB8C00"]; ghost3 [label="Ghost Exchange\n(velocity, flux)", fillcolor="#F3E5F5", color="#8E24AA"]; diag [label="Diagnostics", fillcolor="#F5F5F5", color="#9E9E9E"]; output [shape=diamond, label="Output\nStep?", fillcolor="#FFEBEE", color="#E53935", fontsize=9]; write [label="Write NetCDF", fillcolor="#FFEBEE", color="#E53935"]; loop [shape=diamond, label="End\nTime?", fillcolor="#E0E0E0", color="#616161", fontsize=9]; start -> forcing -> gwce -> ghost1 -> wetdry -> ghost2; ghost2 -> momentum -> bc -> ghost3 -> diag -> output; output -> write [label="yes", fontsize=9]; output -> loop [label="no", fontsize=9]; write -> loop; loop -> start [label="no", fontsize=9, style=dashed, constraint=false]; }

Fig. 1 Simulation timestep loop

Running a Simulation

Cocoa simulations are configured using YAML files. To run a simulation:

./cocoa -i simulation_config.yaml

Example Configuration

Here’s a minimal example configuration file:

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

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

physics:
  manning_n: 0.025
  tau0: 0.005

numeric:
  solver: explicit
  gwce_coefficients: [0.0, 1.0, 0.0]

forcing:
  ramp:
    enabled: true
    duration: 1d
  tide:
    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 }

output:
  step_interval: 60

diagnostics:
  screen_interval: 3600

Expected Output

Cocoa will produce output similar to:

[2025-01-01 00:00:00.000] [info    ] ==== Cocoa Execution Space Configuration ====
[2025-01-01 00:00:00.000] [info    ] Execution Space: Serial (single-thread, CPU)
[2025-01-01 00:00:00.000] [info    ]   Memory Space: Host
[2025-01-01 00:00:00.000] [info    ] =============================================
[2025-01-01 00:00:00.000] [info    ] Reading configuration from: config.yaml
[2025-01-01 00:00:00.000] [info    ] Loaded configuration from config.yaml
[2025-01-01 00:00:00.000] [info    ] ModelConfiguration created and validated successfully
[2025-01-01 00:00:00.000] [info    ] Starting simulation: 2025-01-01T00:00:00 to 2025-01-02T00:00:00

During the simulation, a progress table is displayed:

+---------------------+---------------+--------+-----------+-----------+------+----------+---------+--------+
|   Simulation Time   |     Step      | Prog % |  Elapsed  | Remaining | Iter | Max Elev | Max Vel | Wet %  |
+---------------------+---------------+--------+-----------+-----------+------+----------+---------+--------+
| 2025-01-01T10:00:00 |   3600/103680 |   3.5% |   0:00:21 |   0:09:49 |   19 |    0.311 |   0.302 | 100.0% |
| 2025-01-01T20:00:00 |   7200/103680 |   6.9% |   0:00:44 |   0:09:55 |   20 |    0.892 |   0.728 |  99.4% |
...

The columns show:

  • Simulation Time: Current model time

  • Step: Current timestep / total timesteps

  • Prog %: Simulation progress percentage

  • Elapsed: Wall-clock time elapsed

  • Remaining: Estimated time remaining

  • Iter: GWCE solver iterations

  • Max Elev: Maximum water surface elevation (m)

  • Max Vel: Maximum velocity magnitude (m/s)

  • Wet %: Percentage of wet nodes

With the internal wave model (Wave Forcing) two more columns follow:

  • Max Hs: the largest significant wave height (m) at the latest coupling, held between couplings; inf where some Hs is not finite, which stops the run (Wave Forcing)

  • Wave Iter: mean outer iterations of the wave couplings since the previous row and, in parentheses, how many there were (10.5 (2)); * in place of the space marks a row where one stopped at its iteration cap, - a row with no coupling (the log file lists each coupling)

The run’s last lines then split the wall time between the hydrodynamics (everything outside the wave couplings: the circulation, its forcing and output) and the wave model, with the wave model’s average iterations per coupling.

Next Steps