Package: volcano-cooking
Volcano CookingLet's make some volcanoes erupt!NOTE:The created datesmuststart before the model start. Running CESM2 from year 1850 with
the first eruption in 1850 will make it crash. Setting the first eruption to 1849,
however, will make it run. The same goes for the end, the model must stop prior to the
last event, otherwise it will crash. This project will make sure one event is placed
ahead of theinityear, but the end will vary depending on number of events created
and their frequency.InstallThe package is published onPyPIand installable viapip:pipinstallvolcano-cookingIf you only plan on using the already present generator classes and only need the CLI
program, it is recommended to install this withpipx:pipxinstallvolcano-cookingUsageThe basicsThere are mainly two CLI programs coming with this project. The main program isvolcano-cooking, which will create a.ncand.npzfile in thedata/outputdirectory. With theview-frcprogram you can quickly view the content of the created
files in a plot. There is also a third program calledsfrc-sparse2linwhich converts
arrays of only non-zero events at arbitrary times to linearly spaced events where times
between the non-zero events are filled with zeros.volcano-cookingOnce installed, run from within this directory with:volcano-cookingAll created files are saved to adata/outputdirectory that will be created inside the
current directory from where thevolcano-cookingcommand is run.For more information, seevolcano-cooking--help[!TIP]It is also possible to run the CLI as a python module. Try:python -m volcano_cooking --help,python -m volcano_cooking.view_forcing --helporpython -m volcano_cooking.sparse_to_lin --help.Option 0 (default, using NCL-script)TL;DR$volcano-cooking-f1-s100Generating with 'GenerateFPP'...$volcano-cooking--run-nclCopyright (C) 1995-2019 - All Rights ReservedUniversity Corporation for Atmospheric ResearchNCAR Command Language Version 6.6.2The use of this software is governed by a License Agreement.See http://www.ncl.ucar.edu/ for more details.(0)in data/originals/createVolcEruptV3.ncl...long_name :   SO2 elevated emissions from explosive volcanoes_FillValue :  9.96921e+36(0)saving stratvolc(0)File creation complete: data/cesm/VolcanEESMv3.11Enger_SO2_850-2016_Mscale_Zreduc_2deg_c20220502-140023.ncLog file created at data/cesm/logs/20220502-140022.logFixing the attributes of the altitude_int coordinate...$volcano-cooking--package-lastSuccessfully placed all latest source files in the 'source-files' directory.$lssource-files20220502-140022.log                     VolcanEESMv3.11Enger_SO2_850-2016_Mscale_Zreduc_2deg_c20220502-140023.ncsynthetic_volcanoes_20220502_135956.nc  synthetic_volcanoes_20220502_135956.npzDependenciesThis option needsvolcano-cookinginstalledA coordinate file (~ 10 kB)nclexecutableCreate source file for forcingRun commandvolcano-cookingwith the options you want. Seevolcano-cooking --help.Create forcing file for CESM2Running thevolcano-cooking --run-nclscript depends on havingnclinstalled. See
installation instructionshere.After having run thevolcano-cookingcommand, the forcing file for CESM2 can be
generated by runningvolcano-cooking--run-nclIf the needed coordinate files are missing, you will be asked if you want to download
them. If you want to use different files, or change the default resolution (default is 2
degrees), edit.env(see./examples/.env.example)
accordingly. In this case, you also need to manually download whatever coordinate file
you want to use. See sectionSetting up manually.Wrap upThe last created files, source files, logs and final output, can be nicely collected and
placed in a directory namedsource-fileswith command:volcano-cooking--package-lastSetting up manuallyTo be able to create forcing files used by CESM2 from the newly created synthetic file,
we need a script from theemissionsdirectory. These are scripts
that use the forcing file this project generates to make a new, full forcing file that
CESM2 accepts (examples of such files can be foundhere). For
example,createVolcEruptV3.nclcan be found in theemissionsdirectory. This need acommon.nclfile, foundhere, in addition to other
standardncllibraries. Make sure to editcreateVolcEruptV3.nclto read the created
file and that the first and last year cover those used in the created file. A working
version ofcreateVolcEruptV3.nclthat uses input files generated byvolcano-cookingcan be found indata/originals. To see what was changed from the
original, rundiff data/originals/createVolcEruptV3.ncl.original src/volcano_cooking/createVolcEruptV3.ncl.Coordinate files are needed when runningcreateVolcEruptV3.nclor similar scripts, and
are locatedhere. For examplefv_1.9x2.5_L30.ncwhich can be used with
two degrees resolution in the atmosphere model. The following commands will download
1 and 2 degree resolution coordinate files, respectively, to thedata/originalsdirectory:wget--no-check-certificatehttps://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/atm/cam/coords/fv_0.9x1.25_L30.nc--directory-prefixdata/originals
wget--no-check-certificatehttps://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/atm/cam/coords/fv_1.9x2.5_L30.nc--directory-prefixdata/originalsOption 1 (directly change forcing file)TL;DR$volcano-cooking-f1-s100-oGenerating with 'GenerateFPP'...DependenciesThis option needsvolcano-cookinginstalledA coordinate file (~ 10 kB)Original CESM2 forcing file (~ 2.2 GB)Run libraryNow the only thing we need to do is runningvolcano-cookingwith the flag-o, and
choose the type of forcing we want (seevolcano-cooking --lst):volcano-cooking-f1-s100-oGet forcing and coordinate files manuallyManually downloading the files and placing them in the correct directory isnotneeded. Running the command as shown above will ask you if you want to download the
files, and place them where they need to be.This option relies on having a working forcing file and coordinate file at hand. We will
use the forcing file that CESM2 places in thestratvolcdirectory of thecammodel.
Download fromthis linkand place it in thedata/originalsdirectory, or run command:wget--no-check-certificatehttps://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/atm/cam/chem/stratvolc/VolcanEESMv3.11_SO2_850-2016_Mscale_Zreduc_2deg_c191125.nc--directory-prefixdata/originalsIt's 2.2 GB file, so it will take some time.We will also need a coordinate file, specificallyfv_1.9x2.5_L30.ncwhich is foundhere. This file is small and quick to download. From the command line:wget--no-check-certificatehttps://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/atm/cam/coords/fv_0.9x1.25_L30.nc--directory-prefixdata/originals
wget--no-check-certificatehttps://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/atm/cam/coords/fv_1.9x2.5_L30.nc--directory-prefixdata/originalsExamplesWhen running the commandvolcano-cooking --run-ncl, a few environment variables will
be used, which can be controlled by setting them in a.envfile. See.env.exampleto see some default values. With this you can
for example easily change the grid resolution to be1degrather than2deg(default).Theexamplesdirectory also include an example on how to use the--fileoption. Cloning this repository and runningvolcano-cooking --file json.jsonfrominsidetheexamplesdirectory will result in some output files generated to a
newdatadirectory insideexamples. If you further rename.env.example→.envyou may also runvolcano-cooking --run-nclandvolcano-cooking --package-last(this assumes you follow option 0, see below).Finally, there is also a scriptcustom_generator.pywhich show how you might define your own generator classes and functions. Run aspython custom_generator.py.view-frcAfter running thevolcano-cookingcommand, files with namessynthetic_volcanoes_...are created with file type.ncand.npz. These can be viewed withview-frc<file.nc>An optional flag can be sent to theview-frcprogram that will save the plot:view-frc -s <file.nc>.For more information, seeview-frc--helpsfrc-sparse2linThis program is available as a convenience tool in the rare case when you have a forcing
file with only the events of eruptions. The program will re-write time array to be
linearly spaced and place the values from the forcing values into a new forcing array
that matches the new linearly spaced time axis.It assumes the file sent to it hasyoes(year, YYYY),moes(month, MM),does(days, DD) andtes(emissions, Tg) fields if it is a.npzfile. If a.ncfile is
used, it must have a dataset with variables "Year_of_Emission", "Month_of_Emission",
"Day_of_Emission" and "Total_Emission".ExtraThis assumes you are using the package from a python script, and not just the CLI.Compare created file with a similar used in a default CESM2 experimentA similar file to those that are created is needed to be able to use some scripts in thehelper_scriptsdirectory. By default, it assumes the file is namedvolcan-eesm_global_2015_so2-emissions-database_v1.0.ncand that it is placed inside
thedata/originalsdirectory. You can find this filehere.ContributingTo contribute to the project, clone and install the full development version (usespoetryfor dependencies):gitclonehttps://github.com/engeir/volcano-cooking.gitcdvolcano-cooking
poetryinstall
pre-commitinstall