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

This guide will help you run your first Cocoa simulation.

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

.. code-block:: text

    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:

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

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

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

.. code-block:: bash

   ./cocoa -i simulation_config.yaml

Examples
^^^^^^^^

**Basic run:**

.. code-block:: bash

   ./cocoa -i my_config.yaml

**With verbose logging:**

.. code-block:: bash

   ./cocoa -i config.yaml --verbose

**With specific thread count (OpenMP backend):**

.. code-block:: bash

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

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

Here's a minimal example 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:
     step_interval: 60

   diagnostics:
     screen_interval: 3600

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

Cocoa will produce output similar to:

.. code-block:: text

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

.. code-block:: text

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

- See :doc:`configuration` for detailed configuration options
- See :doc:`../user_guide/mesh_preparation` for mesh preparation guidance
- See :doc:`../user_guide/boundary_conditions` for setting up boundary conditions