NAME Model Documentation

The Numerical Atmospheric-Dispersion Modelling Environment, NAME, is the Met Office's Lagrangian atmospheric dispersion model. NAME is used for predicting the transport of airborne pollutants and their deposition to the ground surface.

These pages provide full scientific and technical details of the NAME model in the NAME Technical Specification Documentation section.

Building the documentation

The build script, build_namedoc.py, is located in the root of the NAME doc project. It performs the following actions:

1. Compile (1 or more) of the NAME model documents
2. Populate the NAME Technical Specification Documentation page with links to the built documents
3. (Optionally) Install the complete set of documentation within a given directory

Requirements

NAME model documents should be written in LaTeX in order for the build script to compile them.

Running the build script

To build all documentation you should change to the root of your working copy of the NAME doc project and run the build script:

./build_namedoc.py

If you have a working rose-stem installation the script will pick up your site name from the SITE setting in your central Rose configuration automatically. If not, or if your site name is different to this then you must supply it directly, for instance to use the meto site:

./build_namedoc.py --site=meto

The script will check that it can find the required utilities, and inform you of what it is about to do. By default the above command will create the documentation (including copies of the html pages) in a new folder called output, in the same directory as the script.

The script also supports optional arguments --method (-m), --force (-f) and --non-interactive (-y). These control, respectively, the method invoked to compile each pdf file from its source files (auto, latex or pdflatex); the ability to force a non-incremental build of the documentation; and the ability to skip any confirmation prompts when used in a timed-script to routinely build the documentation.

Installing the documentation

You may wish to have the build script install the documentation to an alternate location; for example a suitable public_html directory or other location which is accessible via a web-server to allow others at your site to view the documentation. To enable this you may run the script with a --output-dir argument:

        ./build_namedoc.py --output-dir=~/public_html/namedoc
      

Building the documentation in the above way will create the output in the given directory (including copies of the html pages), and create a symbolic link to that directory called output in the same directory as the build script.

Subsequent runs of the script (when an output directory already exists) will perform an incremental build using the contents of that directory as a starting point, unless the --force argument is provided to force a complete rebuild.

Building a subset of the documents

If you are developing a specific document you may wish to build only that document in order to check the results of your changes. To do this you can supply an optional pattern or set of patterns as the final arguments to the script:

        ./build_namedoc.py A01 B04
      

The above command will build only the A01 and B04 documents. Note that unless you are using --non-interactive mode the script provides a list of the documents it will build for confirmation, allowing you to check that your pattern/s matched the documents you intended.

Adding a new model document

If you wish to create a new NAME model document you must first reserve a suitable document number which hasn't yet been used (please consult the NAME system manager), and create a new subfolder in the source directory with that name. Create your document within that directory.

You must make sure only a single .tex file in the folder contains a \documentclass, as this is how the build system identifies which file to compile.

The process for removing a document is the same, simply delete the folder. There is no need to make any changes to the build script to add or remove a document.