Merge branch 'rel/0.1.0'

Author: Peter Bräuer

Project.toml

@@ -2,7 +2,7 @@ name = "TUVtools"
 uuid = "345a537c-f292-11e8-1826-5db092d7553c"
 authors = ["Peter Bräuer <pb866@york.ac.uk>"]
 julia = "≥0.7"
-version = "0.1.0-DEV"
+version = "0.1.0"
 
 [deps]
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"

README.md

@@ -1 +1,151 @@
 TUVtools
+========
+
+TUV developer tools to auto-generate TUV input files, include files to link
+TUV to the boxmodel [DSMACC](https://github.com/pb866/DSMACC-testing.git) or
+generate markdown files for the TUV wiki.
+
+
+Installation
+------------
+
+Go to the package manager and add first the unregistered package 
+[filehandling](https://github.com/pb866/filehandling.git) and then TUVtools.
+You may want to `activate` an environment as optional second step, if you
+don't want the project installed in the main julia environment (where `.` can
+be replaced by any path to any existing Project.toml or to a new folder
+creating a new environment).
+
+```julia
+julia> ]
+pkg> activate .
+pkg> add https://github.com/pb866/filehandling.git
+pkg> add https://github.com/pb866/TUVtools.git
+pkg> instantiate
+pkg> precompile
+```
+
+
+Usage
+-----
+
+Import package with `using` or import `import`:
+
+```julia
+using Pkg
+Pkg.activate("path/to/Project.toml") #if not in main julia environment
+using TUVtools
+```
+
+**_Currently all functions work only for the MCM/GECKO-A TUV version 5.2.x., where source code has been moved to a separate source folder!_**
+Additional flags to use with the original TUV version will be introduced in the future.
+
+
+### Function setrxns
+
+Auto-generates The reaction part of the TUV input files from the reaction labels
+defined in the rxn files/subroutines. Options exist to reset flags.
+
+
+
+```julia
+setrxns(tuvdir::String; inputfiles::Union{String,Vector{String}}="", setflags::Int64=-1)
+```
+
+Specify the location of the TUV main folder with `tuvdir`. TUV input files have to exist
+already and only the mechanisims section is overwritten. By default all files in the `INPUTS`
+folders are re-written. Use keyword argument `inputfiles` to select a subset.
+
+Use kwarg `setflags` to reset flags for TUV output. By default the same flags are used as
+previously. If you add/delete reactions, you will have to insert/delete flags at the
+corresponding lines (you only need to provide the flag at the first character of the line,
+the remaining line will be auto-filled). Other options are:
+
+- `0`: Set all flags to false (`F`)
+- `1`: Set all flags to true (`T`)
+- `2`: Set output to `T` for reactions in the MCM/GECKO-A mechanism, remaining flags to `F`
+- `3`: Set output to `T` for reactions in the MCMv3.3.1 (and older) mechanism, remaining flags to `F`
+
+
+### Function generate_incfiles
+
+Auto-generates include files for the boxmodel 
+[DSMACC](https://github.com/pb866/DSMACC-testing.git) to link TUV and DSMACC
+reaction numbers in the model.
+
+```julia
+generate_incfiles(tuvdir::String)
+```
+
+Specify the main folder of the TUV version you are using 
+(needs to be the MCM/GECKO-A TUV version rather than original TUV), from
+which the function will derive the TUV reaction numbers.
+DSMACC reaction numbers are saved in `src/data/MCMv32.db`, `src/data/MCMv331.db`,
+and `src/data/MCM-GECKO-A.db` for the respective MCM versions. 
+
+If you use additonal photolysis reactions or altered the photolysis numbers 
+in any way, you need to modify these number either by cloning this repository
+and making sure to load the cloned version into julia or you can `develop` the
+package with the help of the package manager.
+
+Include files will be auto-generated for every MCM version and written to the
+main folder of the specified TUV version.
+
+
+### Function generate_wiki
+
+This is a more advanced routine for developers of the MCM/GECKO-A TUV version
+to maintain the wiki pages of the repository.
+
+Function `generate_wiki` can auto-generate wiki pages for the reaction numbers
+used in MCM/GECKO-A and TUV and the improved MCM photolysis parameterisations.
+
+By default, no wiki files are generated unless you specify a template for the wiki page(s) 
+or the `parameter.csv` from [MCMphotolysis](https://github.com/pb866/MCMphotolysis.git).
+
+```julia
+generate_wiki(tuvdir::String; wikitemplates::Union{String, Vector{String}}="",
+  wikioutput::Union{String, Vector{String}}="WIKI.md", MCMcollength::Union{Int64,Vector{Int64}}=10,
+  MCMversion::Union{Int64,Vector{Int64}}=4, parinput::String="",
+  paroutput::String="../MCM-Photolysis-Parameters.md")
+```
+
+Specify the main folder of the TUV version used in `tuvdir` to get the TUV
+reaction numbers. If you want to generate wiki page(s) for the reaction numbers,
+make sure the DSMACC reaction numbers are correct in the database files
+(see [function `generate_incfiles`](#function-generate_incfiles)).
+
+Create templates for all wiki pages using markdown code. Type any text you like
+in the page. Where you want tables with the reaction numbers, only provide the header.
+Put the reaction string starting at the first character of the line for every reaction
+you want in the tables at the correct positon in the template. The script will auto-fill-in
+the correct MCM/GECKO-A and TUV reaction numbers in the first two columns and the
+reaction label in the third. Reaction labels have to be the same as in TUV.
+Examples of templates can be found in `src/data`.
+
+Specify the templates with the kwarg `wikitemplates` as `String` for single file
+or as `Vector{String}` for multiple files. Define as many output file names as
+templates with `wikioutput` in the same manor. Specify, which version of the MCM
+you are using for each wiki page as `Int64` or `Vector{Int64}` using `3` for
+MCMv3.3.1 or older and `4` for MCM/GECKO-A. Optionally you can specify the column
+length of the MCM/GECKO-A reaction number column for nicer formatting of the table
+in the md files. TUV columns will always be for 3-digit integers.
+
+If you want to generate the parameter list for the improved MCM/GECKO-A
+photolysis parameterisations, specify the location and file name of the
+`parameters.csv` from [MCMphotolysis](https://github.com/pb866/MCMphotolysis.git)
+with kwarg `parinput`. To specify a location and file name for the 
+auto-generated markdown file use kwarg `paroutput`.
+
+
+Version history
+===============
+
+Version 0.1.0
+-------------
+- New function `setrxns` to auto-generate TUV input files
+- New function `generate_incfiles` to auto-generate DSMACC include files
+  to link TUV to DSMACC
+- New function `generate_wiki` to auto-generate wiki files for the 
+  MCM/GECKO-A and TUV reaction numbers and for the improved MCM/GECKO-A
+  photolysis parameterisations

src/TUVtools.jl

@@ -19,10 +19,12 @@ using filehandling
 using Printf
 
 export setrxns,
-       generate_incfiles
+       generate_incfiles,
+       generate_wiki
 
 # Include private functions
 include("setrxns.jl")
+include("generate_wiki.jl")
 
 """
     setrxns(tuvdir::String; inputfiles::Union{String,Vector{String}}="", setflags::Int64=-1)
@@ -57,6 +59,11 @@ function setrxns(tuvdir::String; inputfiles::Union{String,Vector{String}}="",
 end #function setrxns
 
 
+"""
+    generate_incfiles(tuvdir::String)
+
+Generate include files to link TUV in directory `tuvdir` to the box model DSMACC.
+"""
 function generate_incfiles(tuvdir::String)
 
   # Save current directory
@@ -72,4 +79,32 @@ function generate_incfiles(tuvdir::String)
   cd(currdir)
 end
 
+
+"""
+    generate_wiki(tuvdir::String, kwargs)
+
+Generate markdown files from templates specified kwarg `wikitemplates`, where
+reactions numbers from TUV in `tuvdir` and in MCM/GECKO-A are listed for every
+reaction listed at the beginning of each template line and written to files specified
+by kwarg `wikioutput`. The table `MCMcollength` can be specifief with a kwarg, for nicer
+md file formatting. The `MCMversion` needs to be specified for every wiki template.
+"""
+function generate_wiki(tuvdir::String; wikitemplates::Union{String, Vector{String}}="",
+  wikioutput::Union{String, Vector{String}}="WIKI.md", MCMcollength::Union{Int64,Vector{Int64}}=10,
+  MCMversion::Union{Int64,Vector{Int64}}=4, parinput::String="",
+  paroutput::String="../MCM-Photolysis-Parameters.md")
+  # Save current directory
+  currdir = pwd()
+  # Find files related to photolysis mechanism
+  rxnfiles, callfiles, tuvdir = getfiles(tuvdir)
+  # get list of reactions in order for input files
+  rxnlist = generate_rxns(rxnfiles, callfiles)
+
+  # Auto-generate inc files for TUV_DSMACC
+  write_wiki(rxnlist, tuvdir, wikitemplates, wikioutput, MCMcollength, MCMversion, currdir)
+  write_params(parinput, paroutput, currdir)
+  # Go back to original directory
+  cd(currdir)
+end #function generate_wiki
+
 end # module TUVtools

src/data/MCM-GECKO-A.db

@@ -93,11 +93,10 @@ MCM/GECKO-A | TUVlabel
     22091   | DIBK -> NI products
     22101   | di-sec-butyl ketone -> NI products
     22111   | di-t-butyl ketone -> NI products
-    22121   | 4-octanone -> NI products
-    22131   | n-C3H7COCH(CH3)2 -> NI products
-    22141   | n-C3H7COCH(CH3)2 -> i-C3H7COCH3 + C2H4
-    22151   | CH3COCH2C(CH3)3 -> NI products
-    22161   | di-sec-butyl ketone -> sec-C4H9COCH2CH3 + C2H4
+    22121   | n-C3H7COCH(CH3)2 -> NI products
+    22131   | n-C3H7COCH(CH3)2 -> i-C3H7COCH3 + C2H4
+    22141   | CH3COCH2C(CH3)3 -> NI products
+    22151   | di-sec-butyl ketone -> sec-C4H9COCH2CH3 + C2H4
     23011   | CH3COCH=CH2 -> CH3 + C2H3CO
     23021   | CH3CH2COCH=CH2 -> C2H5 + C2H3CO
     24011   | c-C3H4O -> C2H4 + CO