\input texinfo @comment %**start of header @settitle FullSWOF-utils Reference Manual @syncodeindex pg cp @comment %**end of header @copying This document describes FullSWOF-utils, a set of utility scripts to be used with the FullSWOF shallow flow solver. Copyright @copyright{} 2019 Paul Garlick. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end quotation @end copying @titlepage @title FullSWOF-utils Reference Manual @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @ifnottex @node Top @top FullSWOF-utils Utility scripts for the FullSWOF shallow flow solver @end ifnottex @menu * Installation:: Installing FullSWOF-utils. * Usage:: * GNU Free Documentation License:: The license of this manual. * Index:: Complete Index. @end menu @node Installation, Usage, Top, Top @comment node-name, next, previous, up @chapter Installation @cindex chapter, installation The @emph{fullSWOF-utils} package comprises a single top-level directory and several sub-directories. The package may be installed in the same location as @emph{FullSWOF} itself or any other convenient location. @menu * Requirements:: * Cloning:: * Uninstalling:: @end menu @node Requirements, Cloning, Installation, Installation @comment node-name, next, previous, up @section Requirements To install @emph{fullSWOF-utils} the following packages are required: @itemize @item @url{https://git-scm.com/, Git}, the version control system. @item @url{https://www.gnu.org/software/texinfo/, Texinfo}, the GNU documentation system. @end itemize @node Cloning, Uninstalling, Requirements, Installation @comment node-name, next, previous, up @section Cloning FullSWOF-utils is maintained using git, the version control system. A simple way to install the package is to clone the git repository. To do so, first open a terminal window on a system that has git installed. Then, from within a suitable working directory, execute the command: @example git clone http://cgit.tourbillion-technology.com/fullSWOF-utils @end example A directory named @emph{fullSWOF-utils} will be created. To complete the installation first change directory to the new @emph{fullSWOF-utils} directory. Then execute the command: @example make @end example This command will create the documentation for the package. The documentation is available in two formats; GNU Info format and html. The info file is located in the doc directory. The html files are located in the manual directory. There are two versions. @emph{fullswof-utils.html} contains the complete documentation set out on one page. The subdirectory @emph{html_node} contains a top-level @emph{index.html} file and a separate page for each node. The info file may be read using the @command{info} program. The html files may be read using any web browser. @node Uninstalling, , Cloning, Installation @comment node-name, next, previous, up @section Uninstalling All the files in the @emph{fullSWOF-utils} package are installed under a single directory. To uninstall the package it is sufficient to remove that directory. For example, to remove a clone of the repository, first navigate to the directory on the system where the clone is located. Then execute the command: @example rm -rf fullSWOF-utils @end example @node Usage, GNU Free Documentation License, Installation, Top @comment node-name, next, previous, up @chapter Usage The programs provided in the @emph{fullSWOF-utils} package are written in the @emph{python} programming language. Python version 3.0 or above is recommended. @xref{Runtime Dependencies} for the python packages that are required by each program. To run an individual program it is convenient to create a symbolic link to the corresponding file in the installation directory. For example, from a suitable working directory, execute the following command to create a link to the @emph{makeBoundary} program: @example ln -s /path/to/installation/directory/python/makeBoundary @end example @menu * Runtime Dependencies:: * Invoking makeBoundary:: @end menu @node Runtime Dependencies, , Usage, Usage @comment node-name, next, previous, up @section Runtime Dependencies The @emph{fullSWOF-utils} programs utilise functions provided by the @emph{Python Standard Library}. @emph{FullSWOF-utils} will be able to access these functions on systems that have the @emph{python} package installed. In addition extra packages are required by the individual programs as follows: @table @command @item makeBoundary: @enumerate @item @url{https://matplotlib.org/, Matplotlib}, a library for creating plots and visualisations in Python. @item @url{https://numpy.org/, NumPy}, a Python package for scientific computation. @end enumerate @end table @node Invoking makeBoundary, , Runtime Dependencies, Usage @comment node-name, next, previous, up @section Invoking @command{makeBoundary} The @command{makeBoundary} program creates boundary condition files for the @emph{FullSWOF} solver. The command-line syntax is: @example makeBoundary @option{boundary} @end example where @option{boundary} is one of @code{top}, @code{bottom}, @code{left} and @code{right}. There are five types of boundary condition that are recognised by the solver: @table @asis @item case 1 imposed height condition @item case 2 wall condition @item case 3 Neumann condition @item case 4 periodic condition @item case 5 imposed discharge condition @end table Cases 1 and 5 are implemented in @emph{makeBoundary}. A height value and a discharge value are calculated for each cell along the boundary. At grid cells where the calculated values are zero the wall boundary condition, case 2, is applied. @node GNU Free Documentation License, Index, Usage, Top @appendix GNU Free Documentation License @include fdl-1.3.texi @node Index, , GNU Free Documentation License, Top @unnumbered Index @printindex cp @bye Local Variables: mode: texinfo TeX-master: t End: