Quick Start

This guide will help you run your first Cocoa simulation.

Command-Line Usage

Cocoa - Coastal and Ocean Circulation on Accelerators
Usage: ./cocoa [options]

Cocoa Options:
  -i <file>              Input configuration file (YAML)
  -v, --verbose          Enable verbose logging (debug level)
  -V, --version          Show version information and exit
  -h, --help             Show this help message
  --partition <file>     Use specified partition file
                         If file exists, use it; otherwise create it
  --create-partition <N> Create partition for N subdomains and exit
                         Use to pre-compute partitions offline
  --kokkos-help          Show Kokkos command line options
  --kokkos-enable-warnings
                         Enable Kokkos warning messages

Kokkos Options:
  --kokkos-*             Various Kokkos runtime options
                         (use --kokkos-help for complete list)

Default config file: cocoa_config.yaml

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

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

Examples

Basic run:

./cocoa -i my_config.yaml

With verbose logging:

./cocoa -i config.yaml --verbose

With specific thread count (OpenMP backend):

./cocoa -i config.yaml --kokkos-num-threads=4

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

Next Steps