|
| 1 | +# Plume Numerical Weather Prediction Model Emulator |
| 2 | + |
| 3 | +This tool is here to help you with your Plume plugins development. |
| 4 | +You can use it to emulate model runs with Plume loading the plugins from your configuration. |
| 5 | + |
| 6 | +## Features |
| 7 | + |
| 8 | +- Dry run: The NWP emulator can run without Plume to develop new features, or to test your data generation to ensure it fits the purpose of your plugin test. |
| 9 | +- Plume run: The NWP emulator runs Plume with the passed configuration. It can be used to test the Plume framweork, or test Plume plugins. |
| 10 | +- GRIB as input: The NWP emulator can either take a directory containing GRIB files or a GRIB file as input source. It will attempt to serve the data in each file as if it were a single model step. The number of emulator steps run depend on the number of GRIB files in the source folder, or a user-defined maximum number of steps. This approach allows a developer to test a plugin with real data. *Note:* the emulator is not looking recursively into the source folder, any subdirectory will be ignored. |
| 11 | +- Config as input: The NWP emulator can take a configuration file that sets its run parameters (number of steps, grid, number of levels, fields...). The data is synthetically generated by a set of available functions, see [below](#configuration-source) for more details. |
| 12 | + |
| 13 | +## Usage |
| 14 | + |
| 15 | +Once installed (check out [Plume install guide](../../README.md/#installation) for more info), the emulator tool can be used as follows: |
| 16 | +```bash |
| 17 | +mpirun -np 2 nwp_emulator_run [--grib-src=<path> | --config-src=<path>] [--plume-cfg=<path>] [OPTION]... [--help] |
| 18 | +``` |
| 19 | +To make a dry run, omit the `--plume-cfg` flag. |
| 20 | + |
| 21 | +## Quick start |
| 22 | +### GRIB source |
| 23 | + |
| 24 | +The GRIB files are served alphabetically so your source folder should be organised to ensure the data you expect is served in the order you expect. Validation is run on all the source files to make sure they all contain the same fields and levels on the same grid. Check out the [MARS documentation](https://confluence.ecmwf.int/display/UDOC/MARS+user+documentation) if you need a hand to retrieve historical data. |
| 25 | + |
| 26 | +### Configuration source |
| 27 | + |
| 28 | +Currently, the emulator supports five functions for data generation: |
| 29 | +- Vortex Rollup (provided by the [Atlas library](https://confluence.ecmwf.int/display/ATLAS)) |
| 30 | +- Random (uniform or normal distributions) |
| 31 | +- Step |
| 32 | +- Cardinal Sine |
| 33 | +- Gaussian |
| 34 | + |
| 35 | +All functions accept a focus area which can be translated between each time step by a user-defined factor. |
| 36 | +Validation is run on the configuration file to ensure options are valid, but it lies with the user to make sure the selected options achieve their purpose. |
| 37 | + |
| 38 | +Here is an example of YAML configuration file you can use to generate model data, which demonstrate the options that each generation function accept: |
| 39 | + |
| 40 | +```yaml |
| 41 | +emulator: |
| 42 | + n_steps: 5 |
| 43 | + grid_identifier: "N80" |
| 44 | + vertical_levels: 5 |
| 45 | + # can provide area here if all population methods should use a non global area by default |
| 46 | + # range for lon is assumed [-180,180] and lat [-90,90] |
| 47 | + fields: |
| 48 | + 100u: # use the field short name |
| 49 | + levtype: "sfc" |
| 50 | + apply: |
| 51 | + vortex_rollup: |
| 52 | + area: [71.5, -25, 34.5, 45] |
| 53 | + time_variation: 1.1 |
| 54 | + 100v: |
| 55 | + levtype: "sfc" |
| 56 | + apply: |
| 57 | + vortex_rollup: |
| 58 | + time_variation: 1.1 |
| 59 | + u: # no specified levtype means not surface |
| 60 | + apply: # functions applied in the given order |
| 61 | + levels: |
| 62 | + "1": |
| 63 | + random: # no specified area means global |
| 64 | + distribution: "uniform" |
| 65 | + step: |
| 66 | + area: [71.5, -25, 34.5, 45] # rectangle represented by NW and SE (lat,lon) coordinates |
| 67 | + value: 10.0 |
| 68 | + variation: 1.0 |
| 69 | + translation: [1.0, 1.0] # degrees of translation of the area per time step (lat, lon) |
| 70 | + "2": |
| 71 | + sinc: |
| 72 | + modes: 3 # number of peaks or sinks in the generation area |
| 73 | + min: -1.0 |
| 74 | + max: 10.0 |
| 75 | + spread: 10.0 |
| 76 | + sink: false |
| 77 | + "3:": |
| 78 | + gaussian: |
| 79 | + modes: 2 |
| 80 | + min: 0.0 |
| 81 | + max: 1.0 |
| 82 | + max_stddev: 3.0 |
| 83 | + sink: true |
| 84 | + v: "u" |
| 85 | + t: |
| 86 | + apply: |
| 87 | + levels: # this key should not be used for sfc |
| 88 | + "2": # when using levels, they should range from 1-<vertical_levels> |
| 89 | + random: |
| 90 | + area: [71.5, -25, 34.5, 45] |
| 91 | + distribution: "uniform" |
| 92 | + min: 10.0 |
| 93 | + max: 35.0 |
| 94 | + "1,3": |
| 95 | + step: |
| 96 | + probability: 0.1 |
| 97 | + value: 45.0 |
| 98 | + "4:": |
| 99 | + random: |
| 100 | + distribution: "normal" |
| 101 | + mean: 20.0 |
| 102 | + stddev: 20.0 |
| 103 | +``` |
| 104 | +
|
| 105 | +## License |
| 106 | +© 2025 ECMWF. All rights reserved. |
0 commit comments