===========
Quick Start
===========

Command-Line Usage
------------------

.. code-block:: text

    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
              --device-info       Show the execution space and device a run would use, then exit
      -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:

.. graphviz::
   :align: center
   :caption: Simulation timestep loop

   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"];
     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;
     wetdry -> 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];
   }

Running a Simulation
--------------------

A YAML file configures each simulation. To run one:

.. code-block:: bash

   ./cocoa -i simulation_config.yaml

Example Configuration
---------------------

A minimal configuration file:

.. code-block:: yaml

   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:
     global:
       step_interval: 60

   diagnostics:
     screen_interval: 3600

Expected Output
---------------

After its startup banner, a serial build running the configuration above
prints:

.. code-block:: text

   [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 run, Cocoa prints a progress table:

.. code-block:: text

   +---------------------+-----------+--------+-----------+-----------+----------+---------+--------+
   |   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:

- ``Simulation Time``: current model time
- ``Step``: current timestep / total timesteps
- ``Prog %``: simulation progress
- ``Elapsed``: wall-clock time elapsed
- ``Remaining``: estimated wall-clock 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
----------

- :doc:`configuration` lists every configuration option
- :doc:`../user_guide/mesh_preparation` covers mesh preparation
- :doc:`../user_guide/boundary_conditions` covers boundary conditions