Package: djs
DJSDJS is an open-source python library for adjusting parameters and completing concurrent WRF-Hydro/National Water Model simulations. It provides tools that simplify model usage and executions that are operable across operating systems. The framework consists of two main pieces:Perturbation Enginefor scaling and stochastically generating model parameter sets.Job Schedulerfor spawning and managing concurrent model simulations.Most users should utilize DJS'sclickcommand line interface to access and use the perturbation engine and job scheduler. The CLI takesyamlinput files that tell the perturbation engine and job scheduler what files to work on and how to work on them. See the example and docs for greater detail.InstallationNote, if you just want to vary model parameters, you can skip topackage installation.DockerPrior to the package installation, first installDocker. Windows and macOS users should installDocker Desktop, Linux users should installDocker Developer Tools.macOS users withhomebrewinstalled can install Docker as such.brewcaskinstalldockerPull the NWM/WRF-Hydro Docker ImagesPull the docker images from docker hub, so DJS can use them to run models. View all available images onDocker Hub.# For NWM version 2.0dockerpullaaraney/nwm-djs:2.0# For NWM version 1.2dockerpullaaraney/nwm-djs:1.2# For WRF-Hydrodockerpullaaraney/wrf-hydro:5.1.1
dockerpullaaraney/wrf-hydro:5.1.0
dockerpullaaraney/wrf-hydro:5.0.3Package InstallationDJS requires Python 3.5 or higher and is available usingpip. It's recommend to install DJS into a virtual environment or a conda environment as a best practice. Personally, I think conda is a little easier, but admittedly a little more bloated.To create a virtual environment run the following in terminalpython3-mvenvdjs-env# If on Mac or Linuxsourcedjs-env/bin/activate# If on Windows.\djs-env\Scripts\activateTo create an environment using conda do the following in terminal. You caninstall miniconda here.condacreate--namedjspython=3.8
condaactivatedjsInstall DJS using pippipinstall--upgradedjsExample caseFiles for this exampleNCAR Pocono, PA test casecan be downloaded and extracted for recreation purposes.In this example, a set of varied model parameter files will be created and used to run NWM version 2.0 simulations.Create varied parameter filesLet's take a look insidepe_setup.ymlbefore varying the parameters. Documentation on the perturbation engine yaml setup file can be found by runningdjs perturbation-engine --helpor in the docs.# Perturbation Engine setup yml fileprimary/DOMAIN/Route_Link.nc:-nCC:scalar:'*1.3'output:'nCC_route_link.nc'primary/DOMAIN/soil_properties.nc:-mfsno:uniform:Trueoutput:'mfsno_soil_properties.nc'primary/DOMAIN/Fulldom_hires.nc:-OVROUGHRTFAC:scalar:'-0.2'output:'OVROUGHRTFAC_fulldom_hires.nc'-multi_group:output:'RETDEPRTFAC_OVROUGHRTFAC_fulldom_hires.nc'OVROUGHRTFAC:norm:Falsescalar:'-0.3'RETDEPRTFAC:scalar:'-0.05'For those following along navigate to the location you extracted thepocono_test_case.zipusing the terminal/command prompt.Create a varied parameter set is as simple as running:djsperturbation-enginepe_setup.ymlVaried parameter files should now exist in thepocono_test_casedirectory.Run NWM SimulationsFirst, ensure that Docker is running. Next, let's take a peak at the Job Scheduler setup files. Documentation on the perturbation engine yaml setup file can be found by runningdjs job-scheduler --helpor in the docs.# Job Scheduler setup yml fileprimary:'primary'alternative-files:--'nCC_route_link.nc'-'mfsno_soil_properties.nc'-'OVROUGHRTFAC_fulldom_hires.nc'-'RETDEPRTFAC_OVROUGHRTFAC_fulldom_hires.nc'image:'aaraney/nwm-djs:2.0'max-jobs:2cpus:'0-2'mpi-np:2To start the simulations run:djsjob-schedulerjs_setup.ymlNotice above that'nCC_route_link.nc'and'mfsno_soil_properties.nc'are nested within a list, this tells the job scheduler to use both files within the same simulation. Whereas the other files will have their own simulations.New directories starting with the prefixrep-should appear in thepocono_test_casedirectory. These directories hold each of the model simulations.Contributors:Austin Raney,Iman Maghami,Yenchia Feng