Usage & Workflow
================

Running ``rbsolve`` consists of an initialization phase and the main time-stepping loop. This document walks through setting up a run, configuring NetCDF4 output, and managing long simulations via restarts.

1. Generating Initial Conditions
--------------------------------

Before the code can step forward in time, it requires an initial state. This corresponds to step `0`. 

First, ensure `param.h`, `config.h`, and `param_namelist` correctly match your desired grid and physics. Then run:

.. code-block:: bash

    ./inicond

* This binary reads the current configuration.
* It sets the initial velocity field (typically to a rest state or a small seed).
* It perturbs the temperature field slightly to break symmetry and kickstart convection.
* It outputs a single baseline file. In NetCDF mode, this creates **rb_0000000.nc**, which contains only step `0`.

2. Running the Simulation
-------------------------

Once step `0` exists, you can execute the main simulation binary:

.. code-block:: bash

    ./rb

``rb`` automatically detects the current timestamp from ``rb_0000000.nc`` and integrates forward up to the absolute timestep defined by `ttot` in `param_namelist`.

NetCDF Output Staggering
------------------------

If `NETCDF_OUTPUT` is enabled (highly recommended), the code performs automatic file rotation to prevent monolithic data structures.

Assuming ``nsnc = 1000`` and ``nsave = 250``:
* **rb_0000000.nc**: Generated by `inicond`. Contains step `0`.
* **rb_0000000.nc**: Generated continuously by `rb`. Collects steps `250`, `500`, `750`.
* **rb_0001000.nc**: Seamlessly opened when the code crosses step `1000`. Collects steps `1000`, `1250`, `1500`, `1750`.
* **rb_0002000.nc**: Opened when crossing step `2000`. And so on.

3. Restarts
-----------

To continue a simulation that has reached its ``ttot`` limit, or to recover a crashed run:

1. Open `param_namelist`.
2. Increase the absolute target `ttot` to your new desired final step.
3. Simply execute ``./rb`` again.

The code will automatically:
* Identify the highest fully-written chunk.
* Perform a "read-all" command, extracting the exact physical state (u, v, w, t) and converting it back into the pseudo-spectral arrays.
* Continue time-stepping exactly as if the run had never stopped.

Data Analysis
-------------

Data saved by the NetCDF routine uses physical space `(x, z, y, time)`. Because it transforms and standardizes the coordinate formats automatically, users can immediately view the results using community tools like `ncview` or Python's `xarray`.

.. code-block:: python

    import xarray as xr
    import matplotlib.pyplot as plt

    ds = xr.open_dataset('rb_0001000.nc')
    ds.t.isel(time=-1, y=64).plot()
    plt.title("Mid-plane Temperature")
    plt.show()