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

docs

parent 9e5c3062
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/source/conf.py
+ 1
− 0
View file @ df778c68
......@@ -20,6 +20,7 @@ extensions = [
'sphinx.ext.doctest',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.autosectionlabel',
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'nbsphinx',
......
docs/source/custom_scripts.rst
+ 2
− 3
View file @ df778c68
......@@ -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
docs/source/index.rst
+ 27
− 12
View file @ df778c68
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:
......
docs/source/notebooks/tutorial1.ipynb deleted 100644 → 0
+ 0
− 214
View file @ 9e5c3062
%% 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% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment