Skip to content
Snippets Groups Projects
Commit df778c68 authored by lkugler's avatar lkugler
Browse files

docs

parent 9e5c3062
Branches
No related tags found
No related merge requests found
......@@ -20,6 +20,7 @@ extensions = [
'sphinx.ext.doctest',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.autosectionlabel',
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'nbsphinx',
......
......@@ -19,8 +19,6 @@ A workflow method is for example :meth:`dartwrf.workflows.WorkFlows.assimilate`,
Calling :meth:`dartwrf.workflows.WorkFlows.assimilate` triggers the execution of the script `dartwrf/assimilate.py`.
- Why do I need a separate script (in this case `assimilate.py`) to execute a script?
Because some users need to use SLURM, which can only call scripts, not run python code directly.
Recipe to add new functionality
*******************************
......@@ -31,4 +29,5 @@ If you need write a new script, you need to
#. write a workflow method (`dartwrf/workflows.py`), e.g. copy and modify an existing one,
#. therein you call the script with :meth:`dartwrf.utils.ClusterConfig.run_job` available via `self.cluster.run_job`, be careful which command-line arguments you need
#. write the script and parse the command-line arguments
#. call whatever python functions you may need
\ No newline at end of file
#. call whatever python functions you may need
Welcome to the DART-WRF documentation!
======================================
DART-WRF documentation
=======================
**DART-WRF** is a python package which allows you to
* run the `weather research and forecast model` (`WRF <https://www2.mmm.ucar.edu/wrf/users/docs/docs_and_pubs.html>`_),
* generate (satellite) observations from a nature run,
* and assimilate these observations in ensemble data assimilation using `DART <https://docs.dart.ucar.edu/en/latest/>`_,
* on a computing cluster or on your local machine.
**DART-WRF** is a python package to run an Ensemble Data Assimilation system using the data assimilation suite `DART <https://docs.dart.ucar.edu/en/latest/README.html>`_ and the weather research and forecast model `WRF <https://www2.mmm.ucar.edu/wrf/users/docs/docs_and_pubs.html>`_.
Installation
------------
*************
DART-WRF is available at `github.com/lkugler/DART-WRF <https://github.com/lkugler/DART-WRF>`_ using the command line. To use it, you don't need to install it, but only its requirements:
DART-WRF can be downloaded from `github.com/lkugler/DART-WRF <https://github.com/lkugler/DART-WRF>`_. To use it, you don't need to install it, but only its requirements:
.. code-block::
git clone https://github.com/lkugler/DART-WRF.git
pip install xarray netCDF4 docopt pysolar==0.10.0
Note that `pysolar` is only necessary if you will be using satellite observations.
Note that `pysolar` is necessary to generate synthetic satellite observations.
Other helpful resources
-----------------------
**DART documentation** `[here] <https://docs.dart.ucar.edu/en/latest/README.html>`_
**WRF user guide** `[here] <http://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/v4.2/WRFUsersGuide_v42.pdf>`_
First steps
************
To get started, go through the tutorials in the :ref:`tutorials` section.
:ref:`tutorial1` shows you how to configure DART-WRF, generate observations and assimilate them.
:ref:`tutorial2` shows you how to run a WRF forecast with the output from data assimilation.
:ref:`tutorial3` shows you how assimilation and forecast can be run in a cycle.
.. toctree::
:hidden:
......@@ -37,6 +42,16 @@ Other helpful resources
notebooks/tutorial2
notebooks/tutorial3
custom_scripts
Other helpful resources
=======================
**DART documentation** `[here] <https://docs.dart.ucar.edu/en/latest/README.html>`_
**WRF user guide** `[here] <http://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/v4.2/WRFUsersGuide_v42.pdf>`_
.. toctree::
:hidden:
......
%% Cell type:markdown id:fd5c3005-f237-4495-9185-2d4d474cafd5 tags:
# Tutorial 1: The assimilation step
DART-WRF is a python package which automates many things like configuration, saving configuration and output, handling computing resources, etc.
The data for this experiment is accessible for students on the server srvx1.
%% Cell type:markdown id:93d59d4d-c514-414e-81fa-4ff390290811 tags:
## Configuring the hardware
In case you use a cluster which is not supported, copy an existing cluster configuration and modify it, e.g. `config/jet.py`.
## Configuring the experiment
Firstly, you need to configure the experiment.
Copy the existing template and modify it `cp config/exp_template.py config/exp1.py`.
Customize your settings:
- expname should be a unique identifier and will be used as folder name
- model_dx is the model resolution in meters
- n_ens is the ensemble size
- update_vars are the WRF variables which shall be updated by the assimilation
```python
exp = utils.Experiment()
exp.expname = "test_newcode"
exp.model_dx = 2000
exp.n_ens = 40
exp.update_vars = ['U', 'V', 'W', 'THM', 'PH', 'MU', 'QVAPOR', 'QCLOUD', 'QICE', 'PSFC']
```
### Generating observations
In case you want to generate new observations, like for an observing system simulations experiment (OSSE), set
```python
exp.use_existing_obsseq = False
```
in this case, you need to set the path to WRF nature run files from where DART can generate observations:
```python
exp.nature_wrfout_pattern = '/usr/data/sim_archive/exp_v1_nature/*/1/wrfout_d01_%Y-%m-%d_%H:%M:%S'
```
### Using pre-existing observation files
You can use pre-existing observation files with
```python
exp.use_existing_obsseq = '/usr/data/sim_archive/exp_ABC/obs_seq_out/%Y-%m-%d_%H:%M_obs_seq.out'
```
where times are filled, depending on the assimilation time.
### Customizing the DART namelist
By default, the DART namelist of the build directory will be used (copied).
If you want to modify any parameters, specify your changes in a python dictionary like below. For a description of the parameters, see [the official DART documentation](https://docs.dart.ucar.edu/).
```python
exp.dart_nml = {'&assim_tools_nml':
dict(filter_kind='1',
sampling_error_correction='.true.',
),
'&filter_nml':
dict(ens_size=exp.n_ens,
num_output_state_members=exp.n_ens,
num_output_obs_members=exp.n_ens,
inf_flavor=['0', '4'],
output_members='.true.',
output_mean='.true.',
output_sd='.true.',
stages_to_write='output',
),
'&quality_control_nml':
dict(outlier_threshold='-1',
),
'&location_nml':
dict(horiz_dist_only='.false.',
'&model_nml':
dict(wrf_state_variables =
[['U', 'QTY_U_WIND_COMPONENT', 'TYPE_U', 'UPDATE','999',],
['V', 'QTY_V_WIND_COMPONENT', 'TYPE_V', 'UPDATE','999',],
['W', 'QTY_VERTICAL_VELOCITY', 'TYPE_W', 'UPDATE','999',],
['PH', 'QTY_GEOPOTENTIAL_HEIGHT', 'TYPE_GZ', 'UPDATE','999',],
['THM', 'QTY_POTENTIAL_TEMPERATURE','TYPE_T', 'UPDATE','999',],
['MU', 'QTY_PRESSURE', 'TYPE_MU', 'UPDATE','999',],
['QVAPOR','QTY_VAPOR_MIXING_RATIO', 'TYPE_QV', 'UPDATE','999',],
['QICE', 'QTY_ICE_MIXING_RATIO', 'TYPE_QI', 'UPDATE','999',],
['QCLOUD','QTY_CLOUDWATER_MIXING_RATIO','TYPE_QC', 'UPDATE','999',],
['CLDFRA','QTY_CLOUD_FRACTION', 'TYPE_CFRAC','UPDATE','999',],
['PSFC', 'QTY_SURFACE_PRESSURE', 'TYPE_PSFC', 'UPDATE','999',],
['T2', 'QTY_2M_TEMPERATURE', 'TYPE_T', 'UPDATE','999',],
['TSK', 'QTY_SKIN_TEMPERATURE', 'TYPE_T', 'UPDATE','999',],
['REFL_10CM','QTY_RADAR_REFLECTIVITY','TYPE_REFL', 'UPDATE','999',]]),
}
```
Any parameters in this dictionary will be overwritten compared to the default namelist.
### Single observation experiment
If you want to assimilate one observation, use
```python
t = dict(plotname='Temperature', plotunits='[K]',
kind='RADIOSONDE_TEMPERATURE',
n_obs=1, # number of observations
obs_locations=[(45., 0.)], # location of observations
error_generate=0.2, # observation error used to generate observations
error_assimilate=0.2, # observation error used for assimilation
heights=[1000,], # for radiosondes, use range(1000, 17001, 2000)
loc_horiz_km=50, # horizontal localization half-width
loc_vert_km=2.5 # vertical localization half-width
)
exp.observations = [t,] # select observations for assimilation
```
### Assimilating multiple observations
To generate a grid of observations, use
```python
vis = dict(plotname='VIS 0.6µm', plotunits='[1]',
kind='MSG_4_SEVIRI_BDRF', sat_channel=1,
n_obs=961, obs_locations='square_array_evenly_on_grid',
error_generate=0.03, error_assimilate=0.03,
loc_horiz_km=50)
exp.observations = [t, vis,]
```
Caution, n_obs should only be one of the following:
- 22500 for 2km observation density/resolution
- 5776 for 4km;
- 961 for 10km;
- 256 for 20km;
- 121 for 30km
For vertically resolved data, like radar, `n_obs` is the number of observations at each observation height level.
%% Cell type:markdown id:16bd3521-f98f-4c4f-8019-31029fd678ae tags:
## Configuring the assimilation experiment
We start by importing some modules:
```python
import datetime as dt
from dartwrf.workflows import WorkFlows
```
To assimilate observations at dt.datetime `time` we set the directory paths and times of the prior ensemble forecasts:
```python
prior_path_exp = '/users/students/lehre/advDA_s2023/data/sample_ensemble/'
prior_init_time = dt.datetime(2008,7,30,12)
prior_valid_time = dt.datetime(2008,7,30,12,30)
assim_time = prior_valid_time
```
To set up the experiment, call
```python
w = WorkFlows(exp_config='exp1.py', server_config='srvx1.py')
```
It will also create the output folders and backup the configuration files and scripts.
Finally, we run the data assimilation by calling
```python
w.assimilate(assim_time, prior_init_time, prior_valid_time, prior_path_exp)
```
Congratulations! You're done!
%% Cell type:code id:82e809a8-5972-47f3-ad78-6290afe4ae17 tags:
``` python
```
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment