Skip to content

Latest commit

 

History

History
179 lines (145 loc) · 5.9 KB

A_SOILWAT2_user_guide.md

File metadata and controls

179 lines (145 loc) · 5.9 KB
Raw

A SOILWAT2 user guide

Note: this document is best viewed as part of the doxygen-built documentation (there may be text artifacts if viewed as standalone-markdown).


The SOILWAT2 program must be downloaded as source code and compiled from the command line. The program is written in C and has no graphical user interface. If you are more familiar with R, then you may prefer to use our R package rSOILWAT2.

We are continuously checking the successful installation, compilation, and passing of logical tests of SOILWAT2 both on a *nix as well as on a Windows OS platform (using cygwin). You can confirm yourself that these checks are passing by visiting the online README page of SOILWAT2 and double check that the badges are green. Thus, if installation doesn't work for you and our checks are passing, then it is likely a problem on your side.

  • If you believe that you have found a bug in our code, then please report it with a minimal reproducible example as an issue.
  • However, we do not have the resources to offer support.

Minimal requirements

  • on any platform:
    • to compile the SOILWAT2 simulation program
    • to compile the SOILWAT2 tests program (using googletest)
    • GNU-compliant make
    • git to download the code from the github repository
  • additionally, on Windows OS:
    • a *nix emulator, e.g., an installation of cygwin or docker
  • on Mac OSX:
    • xcode command line tools (run xcode-select --install on the command line)
    • having agreed to the xcode license (run xcodebuild -license)
    • or, alternatively, the full xcode installation
  • to build the documentation (optional)
    • doxygen (ideally >= v1.9.3) and
    • a minimal latex installation (see below)
  • to build with netCDF support (optional)
    • the netCDF-C library
  • to build with udunits2 support (optional)
    • the udunits2 library

Example instructions for a minimal latex installation

  • details on tinytex
  • install the R package tinytex
    install.packages("tinytex")
    tinytex::install_tinytex()
  • if you don't have write permission to /usr/local/bin, then appropriate symlinks are not generated; thus, locate the path to tlmgr, e.g., with help of tinytex::tinytex_root(), and fix symlinks with escalated privileges
    sudo [path/to/]tlmgr path add

Download

  • Note: Downloading the SOILWAT2 code as zip file (via green button on website) or directly from here doesn't work out of the box because this will not download required code for the "submodules".

  • Use git to download the latest version of SOILWAT2 from our repository on github, e.g.,

    git clone -b master --single-branch --recursive https://github.com/DrylandEcology/SOILWAT2.git SOILWAT2
  • Download a specific version of SOILWAT2, e.g., version 5.0.0,
    git clone -b v5.0.0 --single-branch --recursive https://github.com/DrylandEcology/SOILWAT2.git SOILWAT2
  • If you are a developer, then clone the repository (instead of a single branch), e.g.,
  git clone --recursive https://github.com/DrylandEcology/SOILWAT2.git SOILWAT2

Compilation

  • Compile an executable binary with text-based input/output, e.g.,
    make
  • Compile an executable binary with netCDF support, e.g.,
    CPPFLAGS=-DSWNETCDF make
  • User-specified paths to netCDF header and library can be provided, e.g.,
    CPPFLAGS=-DSWNETCDF NC_CFLAGS="-I/path/to/include" NC_LIBS="-L/path/to/lib" make
  • User-specified username and hostname, e.g.,
    USERNAME=nobody HOSTNAME=nowhere make

Documentation

  • Code documentation
    cd SOILWAT2/
    make doc
    make doc_open
  • Documentation of user inputs and outputs
    • \subpage doc/additional_pages/SOILWAT2_Inputs.md "SOILWAT2 Inputs"
    • \subpage doc/additional_pages/SOILWAT2_Outputs.md "SOILWAT2 Outputs"

Example

  • The source code contains a complete example simulation project in tests/example/
  • Modify inputs as desired and run a simulation, e.g.,
    make bin_run

or, equivalently,

    make
    bin/SOILWAT2 -d ./tests/example -f files.in
  • The inputs comprise the master file files.in and the content of the Input/ folder. They are explained in detail here.
  • The outputs are written to Output/ including a logfile that contains warnings and errors. The output files are in .csv format and can be opened by a spreadsheet program (e.g., LibreOffice or Excel) or imported into R (e.g., data <- read.csv("tests/example/Output/sw2_yearly.csv")). Outputs are explained in detail here.

Go back to the [main page](README.md).