Tutorial 2: Run a forecast
###########################

There are two options to initialize a forecast.

* Initialization from sounding profiles, i.e. defined profiles of temperature, humidity and wind, from ``wrf_profile`` files (see WRF guide). Only usable for WRF's idealized mode.
* Initialization from an previous forecast, i.e. from WRF restart files - optionally with updates from data assimilation.


a) Initialization from sounding profiles
----------------------------------------

It is necessary to set the path to the prepared WRF input soundings as argument to :class:`dartwrf.utils.Config`.

.. code-block:: python

    input_profile = '/jetfs/scratch/wrf_profiles/raso.fc.<iens>.wrfprof'

where `<iens>` is a placeholder, since there is one file for each member, from `raso.fc.001.wrfprof` to `raso.fc.040.wrfprof`.

The input profiles are then copied into the WRF ensemble directories by ``w.prepare_WRFrundir(cfg)``.
Finally, with ``w.run_ideal(cfg)``, WRF's ideal.exe program is called for all ensemble members 
to create initial condition files, called `wrfinput_d01`, for each member.

Now we can go to step 3 to run the forecast.


b) Initialization from a previous forecast
------------------------------------------

Let's say you want to run a forecast starting at 9 UTC until 12 UTC.
We use initial conditions of a previous experiment ``/user/test/data/sim_archive/exp_abc`` 
which was initialized at 6 UTC and there are WRF restart files for 9 UTC.
Documentation can be found at :func:`dartwrf.workflows.WorkFlows.prepare_IC_from_prior`.

.. code-block:: python

    import datetime as dt
    cfg.update(
        time = dt.datetime(2008, 7, 30, 6),
        prior_init_time = dt.datetime(2008, 7, 30, 6),
        prior_valid_time = dt.datetime(2008, 7, 30, 9),
        prior_path_exp = '/user/test/data/sim_archive/exp_abc/',)
    w.prepare_IC_from_prior(cfg)

Now, we are ready to run the forecast, or update the initial conditions with increments from assimilation.


Optional: Update posterior with increments from assimilation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To continue a forecast after assimilation you need the posterior = prior (1) + increments (2)

.. code-block:: python

    w.prepare_IC_from_prior(cfg)
    w.update_IC_from_DA(cfg) 

The second step updates the initial conditions, i.e. the WRFrst files (that were copied to the run_WRF directories), 
with assimilation increments at ``time``.
Now we can run the forecast ensemble.


Run the forecast
----------------

Set important parameters,

* ``WRF_start``: start time of the WRF simulation
* ``WRF_end``: end time of the WRF simulation
* ``hist_interval_s`` (int): history output frequency in seconds
* ``restart``: whether it uses a restart file
* ``restart_interval``: interval in minutes to write restart files

and run

.. code-block:: python

        cfg.update( WRF_start=t, 
                    WRF_end=t+timedelta_integrate, 
                    restart=True, 
                    restart_interval=restart_interval,
                    hist_interval_s=300,
        )
        id = w.run_WRF(cfg)


More documentation is in the docstring of :func:`dartwrf.workflows.WorkFlows.run_WRF`.