SWIM redesign and swimpy

Michel Wortmann

15 March 2024

Uniform code standard to Fortran 95

  • normalised indentation (2 spaces) and other space
  • adherance to -std=f95 (see Makefile)
  • removed deprecated statements
    • e.g. goto, data, pause
  • no compiler warnings allowed
  • global real type (dp)

Modularisation

  • explicit dependencies: use X, only : ...
  • argument passing with intend(in/out/inout)

Explicit module dependency and argument passing

  • argument passing with intent
    • left to right in hierarchy
    • e.g.: swim.f95 → hydrotope.f95
  • use <module>, only: ...
    • from right to left in hieararchy
    • e.g. hydrotope.f95 ← utilities.f95
subroutine hydrotope_open_files(input_dir, output_path)
  use utilities, only : open_file
  character(len=*), intent(in) :: input_dir
  character(len=*), intent(out) :: output_path

Parameters

  • all key = value parameters read via fortran namelist (.bsn, .cod, swim.conf...)
  • defaults defined in the code, i.e. values are not mandatory
! comments are allowed too
&snow_parameters
 prcor = 1.0,
 snow1 = 0.0,
 ulmax0 = 1.0,
 rnew = 0.08,
 tmelt0 = 0.0,
 bsnowmodule = .true.,
 /
&soil_parameters
 ab = 0.02083,
 nn = 10,
 psp = 0.5,
 rtn = 0.15,
 /

Uniform and tidy input

  • all files converted to CSV
  • tidy data: samples in rows, variables in columns
  • all files with column names and integer index
  • input of same spatial unit aggregated
  • columns are identified by name (not index)

  call read_real_column(file_id, "reference_elev", &
    reference_elev, default=0)

Comandline interface


Michels-MBP:$ ./swim -h

  + . . . . . . . . . . . . . . . . . . . . . . . . . . +
  .                                                     .
  .      .      //////// \\    \\      // ||  ||    ||  .
  .     / \     \\        \\    \\    //  ||  ||\\//||  .
  .    /   \     \\\\\\\   \\  //\\  //   ||  || \/ ||  .
  .   /~~~~~\         //    \\//  \\//    ||  ||    ||  .
  .  (~~~~~~~)  ///////      \\    \\     ||  ||    ||  .
  .   \~~~~~/   --------------------------------------  .
  .    -----    Soil   and   Water  Integrated   Model  .
  .                                                     .
  .                     * v2021.1 *                     .
  + . . . . . . . . . . . . . . . . . . . . . . . . . . +

usage: swim [options] [parameter-nml]

  parameter-nml               path to the parameter namelist

options:
  -h, --help                  show this help message
  -v, --version               print version
  -d, --defaults [module]     print default parameters
  -o, --output-variables      print available output variables

Abstract logging and terminal output

  • 4 levels: debug, info, warn, error
  • a simple progress bar
  • main/logger and optional module-specific logs
  • abstract subroutines

  call log_debug(source, message,
                 [log, i1, i2, int, real, ints, reals])

  call log_info / log_warn / log_error(...

Abstract and tidy output

  • common interface for all output (abstracted)
  • flexible output via .nml file
  • tidy CSV file output
  • (most) old output-related code purged/converted
  • easy to add more (3 lines of code)
    • module variable
    • register
    • store variable

Requesting output

input/output.nml

&file
  name = "<string>"
  space = "(catchment | subbasin | hydrotope |
            subbasin_label | hydrotope_label)"
  time = "(daily | monthly | annual)"
  variables = "<list of output variable names>"
 [format = "(csv (default) | bin)"]
/
&file
...

Documentation

Open-source SWIM

m.swim.* GRASS modules

  • ported to SWIM redesign CSV input
  • columns with uniform defaults already set in SWIM removed
  • branches
    • v1_lts: old SWIM input
    • master: redesign input
  • code hosted on Github

swimpy

  • Python API to swim input/output plus helper tools
  • code hosted on Github
  • allows easy configuration, abstraction of common functions
  • includes a multi-objective, evolutionary autocalibration
  • enables the SWIM-Dashboard

SWIM dashboard

  • in Docker container or in a Python environment
  • Try out here

swimpy autocalibration

  • requirements
    • swim project (redesign or develop)
    • observation data
    • objective functions
    • swimpy setup linking all the above
    • (launch/submission script or swimpy function)
  • walk-through…

Parallelism

  • mp: Python multiprocessing on single machine
  • jobs: submit individual Slurm jobs for each run
  • mpi: distribute runs to any number of CPUs on cluster in single job