Getting Started

An Intro to RW3D

RW3D (Random-Walk in 3 Dimensions) is an object-oriented Fortran code designed to solve the fate and transport of conservative and certain reactive solutes in porous media using the random-walk particle-tracking method. Originally developed as a research tool to better understand solute transport in heterogeneous porous media, RW3D has evolved over the years to tackle increasingly complex and realistic problems.

Each development phase has undergone rigorous code validation by comparing solutions against well-established Eulerian methods and, when possible, analytical solutions [HFG14, HFG15].

Today, RW3D can solve both conservative and reactive transport problems, including first-order decay networks, bimolecular reactions, and linear sorption. The code also offers the flexibility to represent all parameters as spatially and temporally variable.

Additionally, the code is now able to read different types of input file formats, including NetCDF and DFS, a binary data file format typically used in the MIKE Powered by DHI software.

As an open-source project, any contribution to improve and extend the code is welcome.

How do I get set up?

Get the code

The code will be released soon (expected during fall 2025). To access it, clone (or download) the project’s repository here:

git clone https://github.com/upc-ghs/RW3D

Run the executable

A built Windows executable and required dll files are provided in the folder exe. We cannot guarantee that the exe file will run on your machine. Alternatively, the code can be built to ensure compatibility with your system.

Build a solution

RW3D is a Fortran 90 code. The Intel Fortran compiler (ifort) and gfortran have been successfully used to build the code. Other compilers, including the newest Intel compiler (ifx), have not been tested yet. In particular, issues concerning the compilation of the netCDF-Fortran library using ifx have been reported. If you choose to work with Intel, the use of ifort is advised.

Two build paths are available depending on your platform:

  • Visual Studio (Windows): recommended for Windows users who need DFS support; supports both NetCDF and DFS file formats

  • Makefile (Linux/Mac/Windows): recommended for Linux and Mac users, and for Windows users who does not need DFS support. Only NetCDF file format is supported.

Important

RW3D source files contain use netcdf and use MzDfs statements, meaning the code requires both the netCDF-Fortran and DFS reader libraries to compile by default. On Linux and Mac, DFS support is disabled at compile time using a preprocessor flag (see Makefile section below), and only netCDF-Fortran is required.

Dependencies

The following libraries are required to build RW3D:

Makefile

A Makefile is provided in the folder make. It is the recommended build method on Linux and Mac, and can also be used on Windows via MinGW/MSYS2.

Project structure

  • Source files are located in ../src/

  • Object files are compiled into ./objtemp/

  • The final executable is created in the current directory (./) and named rw3d

Install dependencies

On Linux, the required libraries can be installed via:

sudo apt install liblapack-dev libblas-dev libnetcdff-dev

On Mac, using Homebrew:

brew install lapack netcdf

Build the project

To compile all source files and create the executable:

make

This will:

  • Create the objtemp directory if it does not exist

  • Compile all .f90 and .F90 source files into object files

  • Link them into the final executable rw3d

DFS support is disabled by default when using the Makefile, since the DHI libraries are not available on Linux and Mac. The preprocessor flag USE_DFS is not defined, so all #ifdef USE_DFS blocks in the source code are excluded at compile time.

Tip

Using MinGW via MSYS2 on Windows

To build the project using the provided Makefile on Windows, we recommend using MinGW along with the MSYS2 shell. From our experience, this handles required dependencies (especially the NetCDF library) in the most straightforward and stable manner. This link provides useful information to install MinGW and configure Visual Studio Code. Here, we summarize the installation process:

Install MSYS2

  1. Download and install MSYS2 from https://www.msys2.org or directly from here.

  2. Open the MSYS2 MSYS terminal and run:

pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain

  1. Add the path of your MinGW-w64 bin folder to the Windows PATH environment variable (by default: C:\msys64\ucrt64\bin)

Install required packages

pacman -S mingw-w64-x86_64-gcc-fortran
pacman -S mingw-w64-x86_64-gcc make
pacman -S mingw-w64-ucrt-x86_64-lapack
pacman -S mingw-w64-ucrt-x86_64-netcdf-fortran

You should now be able to build the code using the make command.

Note that building with DFS support via the Makefile on Windows is not currently supported. Use Visual Studio instead if DFS file reading is required.

Tip

Running rw3d.exe built via MSYS2

The executable built via the Makefile on MSYS2/UCRT64 depends on several DLLs (LAPACK, BLAS, netCDF, and related libraries) located in C:\msys64\ucrt64\bin. To run rw3d.exe outside of the MSYS2 terminal (e.g., by double-clicking it or running it from a regular Windows Command Prompt), add this folder to your Windows PATH environment variable:

  1. Open Settings → System → About → Advanced system settings → Environment Variables

  2. Under User variables (or System variables), select Path and click Edit

  3. Click New and add: C:\msys64\ucrt64\bin

  4. Click OK to confirm all dialogs

Alternatively, you can run rw3d.exe directly from the MSYS2 UCRT64 terminal, where these DLLs are already accessible without modifying the system PATH.

Visual Studio

The code was (and still is) mostly developed on Windows using Visual Studio. The IDE streamlines the software development process by offering intelligent code completion, debugging tools, and integration with version control systems like Git.

A Visual Studio solution file (.sln) is provided in the repository for convenience. It was developed and tested with Visual Studio 2022 and Intel Fortran Essentials. It may require adjustments on other configurations, particularly regarding library paths which are machine-specific.

The following instructions (as of 15/01/2025) guide you through building RW3D from scratch.

Download and install

  1. Download and install Microsoft Visual Studio following these instructions

  2. Download and install Intel Fortran Essentials (make sure that oneMKL is selected during installation; this will provide the LAPACK and BLAS libraries)

Build the netCDF-Fortran library

The netCDF-Fortran library must be built before compiling RW3D. Some issues have been observed on Windows. If you encounter difficulties, this thread provides some guidance. The build process will produce two libraries needed when linking RW3D:

  • netcdff.lib — the Fortran interface library

  • netcdf.lib — the underlying C library

Note the paths to these files, as they will be needed when configuring the RW3D project properties.

Tip

A common approach on Windows is to use pre-built binaries distributed by Unidata for the C library, and to build only the Fortran wrapper against it. This can simplify the process significantly.

Build the DFS reader libraries

Follow the instructions in the DFS reader libraries section below to build MzF90.lib and MzF90c.lib before proceeding.

If you do not need to read DFS files, this step can be skipped, provided you remove the USE_DFS preprocessor flag from the project settings (see below).

Build RW3D

  1. In Visual Studio: File \(\to\) New \(\to\) Project

  2. In the New Project window: Template \(\to\) Intel(R) Visual Fortran (appears when the compiler has been correctly installed) \(\to\) Empty Project (provide a name and location)

  3. In the Solution Explorer panel: drag all Fortran source files into the folder Source files

  4. Right-click on the project name to open Property Pages

  5. Select the desired configuration: Debug (slower but with detailed error messages) or Release (faster, lighter)

  6. Under Configuration Properties \(\to\) Fortran \(\to\) Preprocessor \(\to\) Preprocessor Definitions: add USE_DFS to enable DFS support. Remove or leave empty to build without DFS support

  7. Under Configuration Properties \(\to\) Fortran \(\to\) Preprocessor \(\to\) Preprocess Source File: select Yes

  8. Under Configuration Properties \(\to\) Fortran \(\to\) General: fill Additional Include Directories with the path to the netCDF-Fortran include files

  9. Under Configuration Properties \(\to\) Fortran \(\to\) Libraries: select Parallel in Use Intel Math Kernel Library

  10. Under Configuration Properties \(\to\) Linker \(\to\) General: set Link Library Dependencies to Yes

  11. Under Configuration Properties \(\to\) Linker \(\to\) Input: fill Additional Dependencies with the following libraries (including their full paths):

    • netcdff.lib — netCDF Fortran library

    • netcdf.lib — netCDF C library

    • MzF90.lib — DFS Fortran wrapper (only if building with DFS support)

    • MzF90c.lib — DFS C wrapper (only if building with DFS support)

    Tip

    To keep the solution portable across machines, use the $(SolutionDir) macro to specify paths relative to the solution file rather than absolute paths. For example:

    $(SolutionDir)..\MzFortranWrappers_VS_with_dependencies\x64\Release\MzF90.lib

  12. Click OK to validate the changes

  13. Build the solution: Build \(\to\) Build Solution

  14. The generated executable will be located in the newly created Debug\ or Release\ folder

Important

When using preprocessor directives in Fortran source files (.F90), the # character must always be placed in column 1 (no leading spaces or indentation). Intel Fortran enforces this strictly — indented directives will be ignored by the preprocessor and the code will fail to compile.

Runtime setup

Before running rw3d.exe, make sure the following .dll files are present in the same folder as the executable:

  • The .dll files generated when building the DFS libraries (from x64\Release\ or x64\Debug\) (only if built with DFS support)

  • Any .dll files required by the netCDF libraries (typically distributed alongside the pre-built binaries)

Without these files, the executable will fail to launch.

DFS reader libraries

This section describes how to build the DHI DFS reader libraries on Windows. This is required when building RW3D with Visual Studio. On Linux and Mac, this step can be skipped.

Step 1 — Install the DHI NuGet packages

  1. In Visual Studio, navigate to Tools → NuGet Package Manager → Manage NuGet Packages for Solution

  2. Search for and install the package DHI.DFS (version 23.0.3 recommended; other versions may also work)

  3. This will automatically install dependent packages and create a packages folder containing subfolders such as:

    • DHI.DFS.23.0.3

    • DHI.DHIfl.23.0.3

    • DHI.EUM.23.0.3

    • DHI.PFS.23.0.3

Important

The packages folder must be located in the same folder as the Visual Studio solution file (.sln).

Step 2 — Extract the Fortran wrapper source files

  1. Locate MzFortranWrappers_VS_with_dependencies.zip in the RW3D repository (under lib/dfs/)

  2. Extract the archive into the same folder as the packages folder. The resulting structure should look like:

your_folder/
├── packages/
│   ├── DHI.DFS.23.0.3/
│   ├── DHI.DHIfl.23.0.3/
│   └── ...
├── MzFortranWrappers_VS_with_dependencies/
│   ├── MzF90.sln
│   ├── MzF90_lib/   (C source files)
│   └── MzF90/       (Fortran source files)

Step 3 — Build the libraries

  1. Open MzF90.sln in Visual Studio

  2. Select the build configuration (Debug or Release) matching the one you intend to use for RW3D

  3. Build the projects in the following order (the Fortran library depends on the C library):

    1. Build the static C library: MzF90_lib

    2. Build the static Fortran library: MzF90

The following files will be generated in the x64\Release\ (or x64\Debug\) subfolder:

  • MzF90.lib — static Fortran interface library

  • MzF90c.lib — static C library

  • Several .dll files — required at runtime (see `Runtime setup`_ below)

Note the path to these files, as they will be needed when configuring the RW3D project properties.

How to run RW3D?

Once you have located the executable file (rw3d.exe), just run it and follow the code’s instructions (i.e., provide a parameter file, as described here Input Instructions).