From e5fb2c16ea3ffb898d860690d9f48d7b26b66823 Mon Sep 17 00:00:00 2001
From: lkugler <lukas.kugler@gmail.com>
Date: Thu, 18 Jan 2024 13:14:56 +0100
Subject: [PATCH] docs
---
docs/source/index.rst | 2 +-
docs/source/notebooks/tutorial2.ipynb | 147 --------------------------
docs/source/tutorial2.rst | 145 +++++++++++++++++++++++++
3 files changed, 146 insertions(+), 148 deletions(-)
delete mode 100644 docs/source/notebooks/tutorial2.ipynb
create mode 100644 docs/source/tutorial2.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 9e017f4..cc70fd8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -40,7 +40,7 @@ To get started, go through the tutorials in the :ref:`tutorials` section.
:caption: Tutorials
tutorial1
- notebooks/tutorial2
+ tutorial2
notebooks/tutorial3
custom_scripts
diff --git a/docs/source/notebooks/tutorial2.ipynb b/docs/source/notebooks/tutorial2.ipynb
deleted file mode 100644
index e10f786..0000000
--- a/docs/source/notebooks/tutorial2.ipynb
+++ /dev/null
@@ -1,147 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "id": "fd5c3005-f237-4495-9185-2d4d474cafd5",
- "metadata": {
- "tags": []
- },
- "source": [
- "# Tutorial 2: Forecast after DA\n",
- "\n",
- "\n",
- "**Goal**: To run an ensemble of forecasts. \n",
- "[free_forecast.py ](https://github.com/lkugler/DART-WRF/blob/master/free_forecast.py) contains examples.\n",
- "\n",
- "Initialize the forecast with either (1) or (2). Run the forecast with (3)\n",
- "\n",
- "1) Initialize a forecast from defined profiles of temperature, humidity and wind, i.e. from a `wrf_profile` (see WRF guide)\n",
- "2) Initialize a forecast from an existing forecast, i.e. from WRF restart files - optionally with updates from data assimilation.\n",
- "3) Run the forecast\n",
- "\n",
- "\n",
- "### 1) Initialize from sounding profiles\n",
- "\n",
- "It is necessary to set the path to the prepared WRF input soundings in `config/cfg.py` like this\n",
- "```python\n",
- "exp.input_profile = '/users/students/lehre/advDA_s2023/data/initial_profiles/raso.fc.<iens>.wrfprof'\n",
- "```\n",
- "where `<iens>` is a placeholder, since there is one file for each member, from `raso.fc.001.wrfprof` to `raso.fc.040.wrfprof`.\n",
- "\n",
- "Then, we set up the workflows as usual and prepare the input profiles.\n",
- "```python\n",
- "import datetime as dt\n",
- "from dartwrf.workflows import WorkFlows\n",
- "\n",
- "w = WorkFlows(exp_config='cfg.py', server_config='srvx1.py')\n",
- "\n",
- "begin = dt.datetime(2008, 7, 30, 7)\n",
- "w.prepare_WRFrundir(begin)\n",
- "```\n",
- "\n",
- "Finally, the WRF's ideal.exe program is called for all ensemble members to create initial condition files, called `wrfinput_d01`, for each member.\n",
- "```python\n",
- "w.run_ideal()\n",
- "```\n",
- "Now we can go to step 3 to run the forecast.\n",
- "\n",
- "\n",
- "### 2) Initialize a forecast from a previous forecast\n",
- "To run a forecast from initial conditions of a previous forecasts, we import these modules\n",
- "```python\n",
- "import datetime as dt\n",
- "from dartwrf.workflows import WorkFlows\n",
- "```\n",
- "\n",
- "Let's say you want to run a forecast starting at 9 UTC until 12 UTC.\n",
- "Initial conditions shall be taken from a previous experiment in `/user/test/data/sim_archive/exp_abc` which was initialized at 6 UTC and there are WRF restart files for 9 UTC.\n",
- "Then the code would be\n",
- "\n",
- "```python\n",
- "prior_path_exp = '/user/test/data/sim_archive/exp_abc'\n",
- "prior_init_time = dt.datetime(2008,7,30,6)\n",
- "prior_valid_time = dt.datetime(2008,7,30,9)\n",
- "\n",
- "w = WorkFlows(exp_config='cfg.py', server_config='srvx1.py')\n",
- "\n",
- "begin = dt.datetime(2008, 7, 30, 9)\n",
- "end = dt.datetime(2008, 7, 30, 12)\n",
- "\n",
- "w.prepare_WRFrundir(begin)\n",
- "\n",
- "w.prepare_IC_from_prior(prior_path_exp, prior_init_time, prior_valid_time)\n",
- "```\n",
- "\n",
- "#### 2b) Optional: Update posterior with increments from assimilation\n",
- "\n",
- "In order to continue a forecast after assimilation you need the posterior = prior (1) + increments (2)\n",
- "\n",
- "1. Prepare initial conditions from a prior forecast:\n",
- "```python\n",
- "w.prepare_IC_from_prior(prior_path_exp, prior_init_time, prior_valid_time)\n",
- "```\n",
- "\n",
- "\n",
- "2. Update the initial conditions from data assimilation:\n",
- "```python\n",
- "w.update_IC_from_DA(time)\n",
- "```\n",
- "\n",
- "After this, the wrfrst files are updated with assimilation increments from DART output and copied to the WRF's run directories so you can continue to run the forecast ensemble.\n",
- "\n",
- "### 3) Run the forecast\n",
- "Define how long you want to run the forecast and when you want WRF-restart files. Since they take a lot of space, we want as few as possible.\n",
- "\n",
- "```python\n",
- "timedelta_integrate = dt.timedelta(hours=5)\n",
- "\n",
- "w.run_ENS(begin=begin, # start integration from here\n",
- " end=time + timedelta_integrate, # integrate until here\n",
- " output_restart_interval=9999, # do not write WRF restart files\n",
- " )\n",
- "```\n",
- "\n",
- "If you want to assimilate in 15 minutes again, use\n",
- "```python\n",
- "timedelta_integrate = dt.timedelta(hours=5)\n",
- "timedelta_btw_assim = dt.timedelta(minutes=15)\n",
- "output_restart_interval = timedelta_btw_assim.total_seconds()/60\n",
- "\n",
- "w.run_ENS(begin=time, # start integration from here\n",
- " end=time + timedelta_integrate, # integrate until here\n",
- " output_restart_interval=output_restart_interval\n",
- " )\n",
- "```\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "400244f1-098b-46ea-b29d-2226c7cbc827",
- "metadata": {},
- "outputs": [],
- "source": []
- }
- ],
- "metadata": {
- "kernelspec": {
- "display_name": "nwp 2023.1 - 3.10",
- "language": "python",
- "name": "nwp2023.1"
- },
- "language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.9"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}
diff --git a/docs/source/tutorial2.rst b/docs/source/tutorial2.rst
new file mode 100644
index 0000000..200e5ae
--- /dev/null
+++ b/docs/source/tutorial2.rst
@@ -0,0 +1,145 @@
+Tutorial 1: The assimilation step
+##################################
+
+DART-WRF is a python package which automates many things like configuration, program dependencies, archiving code, configuration and output, handling computing resources, etc.
+
+This tutorial can be executed with pre-existing input data accessible for students of the "University of Vienna - Department of Meteorology and Geophysics" on the server `srvx1`/Teachinghub.
+
+The main control scripts are in the main folder of DART-WRF, e.g. ``analysis_only.py``.
+A control script defines the jobs (work packages, programs) which need to be completed and in which order they need to be done.
+Every control script starts with setting up the experiment.
+
+.. code-block:: python
+
+ from dartwrf.workflows import WorkFlows
+ w = WorkFlows(exp_config='exp_template.py', server_config='srvx1.py')
+
+
+
+Tutorial 2: Forecast after DA
+###############################
+
+**Goal**: To run an ensemble of forecasts.
+`[free_forecast.py] <https://github.com/lkugler/DART-WRF/blob/master/free_forecast.py>`_ contains examples.
+
+Initialize the forecast with either (1) or (2). Run the forecast with (3)
+
+#. Initialize a forecast from defined profiles of temperature, humidity and wind, i.e. from a `wrf_profile` (see WRF guide)
+#. Initialize a forecast from an existing forecast, i.e. from WRF restart files - optionally with updates from data assimilation.
+#. Run the forecast
+
+
+1) Initialize from sounding profiles
+***********************************
+
+It is necessary to set the path to the prepared WRF input soundings in `config/cfg.py` like this
+
+.. code-block:: python
+
+ exp.input_profile = '/users/students/lehre/advDA_s2023/data/initial_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`.
+
+Then, we set up the workflows as usual and prepare the input profiles.
+
+.. code-block:: python
+
+ import datetime as dt
+ from dartwrf.workflows import WorkFlows
+
+ w = WorkFlows(exp_config='cfg.py', server_config='srvx1.py')
+
+ begin = dt.datetime(2008, 7, 30, 7)
+ w.prepare_WRFrundir(begin)
+
+
+Finally, the WRF's ideal.exe program is called for all ensemble members to create initial condition files, called `wrfinput_d01`, for each member.
+
+.. code-block:: python
+
+ w.run_ideal()
+
+
+Now we can go to step 3 to run the forecast.
+
+
+2) Initialize a forecast from a previous forecast
+*************************************************
+
+To run a forecast from initial conditions of a previous forecasts, we import these modules
+
+.. code-block:: python
+
+ import datetime as dt
+ from dartwrf.workflows import WorkFlows
+
+Let's say you want to run a forecast starting at 9 UTC until 12 UTC.
+Initial conditions shall be taken from a previous experiment in `/user/test/data/sim_archive/exp_abc` which was initialized at 6 UTC and there are WRF restart files for 9 UTC.
+Then the code would be
+
+.. code-block:: python
+
+ prior_path_exp = '/user/test/data/sim_archive/exp_abc'
+ prior_init_time = dt.datetime(2008,7,30,6)
+ prior_valid_time = dt.datetime(2008,7,30,9)
+
+ w = WorkFlows(exp_config='cfg.py', server_config='srvx1.py')
+
+ begin = dt.datetime(2008, 7, 30, 9)
+ end = dt.datetime(2008, 7, 30, 12)
+
+ w.prepare_WRFrundir(begin)
+
+ w.prepare_IC_from_prior(prior_path_exp, prior_init_time, prior_valid_time)
+
+
+2b) Optional: Update posterior with increments from assimilation
+-------------------------------------------------------------------
+
+In order to continue a forecast after assimilation you need the posterior = prior (1) + increments (2)
+
+1. Prepare initial conditions from a prior forecast:
+
+.. code-block:: python
+
+ w.prepare_IC_from_prior(prior_path_exp, prior_init_time, prior_valid_time)
+
+
+
+2. Update the initial conditions from data assimilation:
+
+.. code-block:: python
+
+ w.update_IC_from_DA(time)
+
+
+After this, the wrfrst files are updated with assimilation increments from DART output and copied to the WRF's run directories so you can continue to run the forecast ensemble.
+
+1) Run the Forecast
+*******************
+
+Define how long you want to run the forecast and when you want WRF-restart files. Since they take a lot of space, we want as few as possible.
+
+.. code-block:: python
+
+ timedelta_integrate = dt.timedelta(hours=5)
+
+ w.run_ENS(begin=begin, # start integration from here
+ end=time + timedelta_integrate, # integrate until here
+ output_restart_interval=9999, # do not write WRF restart files
+ )
+
+If you want to assimilate in 15 minutes again, use
+
+.. code-block:: python
+
+ timedelta_integrate = dt.timedelta(hours=5)
+ timedelta_btw_assim = dt.timedelta(minutes=15)
+ output_restart_interval = timedelta_btw_assim.total_seconds()/60
+
+ w.run_ENS(begin=time, # start integration from here
+ end=time + timedelta_integrate, # integrate until here
+ output_restart_interval=output_restart_interval
+ )
+
+By default, it assumes that the input data is a WRF restart file. To use WRF input file as initial conditions, set keyword ``input_is_restart=False``.
\ No newline at end of file
--
GitLab