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:

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

After its startup banner, Cocoa will produce output similar to (a serial build running the configuration above):

[info    ] Cocoa version: 0.6.0
[info    ] ==== Cocoa Execution Space Configuration ====
[info    ] Execution Space: Serial (single-thread, CPU)
[info    ]   Memory Space: Host
[info    ] =============================================
[info    ] Reading configuration from: simulation_config.yaml
[info    ] Mesh id: cm1_...
[info    ] Starting simulation: 2025-01-01T00:00:00 to 2025-01-02T00:00:00

The configuration and model-setup details are logged at debug level; add --verbose to see them. A build with cocoa_PRINT_LOG_TIME prefixes each line with the wall-clock time.

During the simulation, a progress table is displayed:

+---------------------+-----------+--------+-----------+-----------+----------+---------+--------+
|   Simulation Time   |   Step    | Prog % |  Elapsed  | Remaining | Max Elev | Max Vel | Wet %  |
+---------------------+-----------+--------+-----------+-----------+----------+---------+--------+
| 2025-01-01T10:00:00 | 3600/8640 |  41.7% |   0:00:21 |   0:00:29 |    0.311 |   0.302 | 100.0% |
| 2025-01-01T20:00:00 | 7200/8640 |  83.3% |   0:00:44 |   0:00:08 |    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 (implicit solver only; the column sits between Remaining and Max Elev)

• Max Elev: Maximum water surface elevation (m)

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

• Wet %: Percentage of wet nodes

Next Steps

• See Configuration for detailed configuration options

• See Mesh Preparation for mesh preparation guidance

• See Boundary Conditions for setting up boundary conditions