microfluidica/porousmicrotransport repository overview

porousMicroTransport^1⁠ is a set of additional solvers and related libraries for OpenFOAM developed for the purposes of simulating flow and transport in porous media, with an emphasis on paper-based microfluidics

⁠Installation

porousMicroTransport requires OpenFOAM⁠, as distributed by OpenCFD (openfoam.com). Compatible OpenFOAM versions are v2112 and newer.

Versions produced by the OpenFOAM Foundation (openfoam.org) (e.g. OpenFOAM 12, OpenFOAM 13) are not compatible. macOS users may want to consider OpenFOAM.app⁠.

⁠With styro⁠

porousMicroTransport can be installed with the styro⁠ package manager:

styro install porousmicrotransport

⁠Install from source

⁠Optional: reagency⁠

porousMicroTransport can be used with the optional reagency⁠ library for reaction modeling. To install porousMicroTransport with reagency, clone the reagency repository alongside porousMicroTransport, and install the former first:

git clone https://github.com/gerlero/reagency.git
reagency/Allwmake -j

⁠Download

Download the source code⁠ of porousMicroTransport, or clone this repository with Git:

git clone https://github.com/gerlero/porousMicroTransport.git

⁠Compile and install

To build and install porousMicroTransport, just invoke the top-level Allwmake script:

cd porousMicroTransport
./Allwmake -j

If necessary, activate/source the correct OpenFOAM environment before running Allwmake.

⁠Test

Optionally, you can verify the installation of porousMicroTransport by running the included test suite (requires Python 3.7 or later):

tests/Alltest

⁠Docker image

Alternatively, porousMicroTransport is also available in the form of Docker images⁠. These images include porousMicroTransport precompiled and ready to use. Assuming Docker⁠ is installed, the following command will run the latest image and mount the current directory so that you can access the files inside:

docker run --rm -it -v $PWD:/root -w /root microfluidica/porousmicrotransport

Or, if you use OpenFOAM's openfoam-docker script⁠ (which takes care of making the working directory available inside the container):

openfoam-docker -image=microfluidica/porousmicrotransport

A slimmer image variant that does not include source code, development tools or tutorial cases is available as microfluidica/porousmicrotransport:slim.

Docker images can also be used with other compatible containerization software, such as Podman and Singularity/Apptainer.

⁠Solvers

⁠moistureDiffusivityFoam

(Unsaturated) capillarity-driven flow in a porous medium, governed by the moisture diffusivity equation^2⁠:

$$\frac{\partial\theta}{\partial t} - \nabla\cdot\left[D\nabla\theta\right] = 0$$

where $\theta$ is the moisture content and $D$ is a saturation-dependent diffusivity as defined by an unsaturated flow model.

⁠microRichardsFoam

Unsaturated flow in a porous medium, governed by the Richards equation^2⁠:

$$C\frac{\partial p}{\partial t} - \nabla\cdot\left[K\nabla p\right] = 0$$

where $p$ is pressure and $C$ and $K$ are pressure-dependent functions defined by an unsaturated flow model. In this formulation, $p$ is the unknown field, and moisture content $\theta$ (a solver output) is considered to be a function of pressure $p$. This formulation is more general and allows for heterogeneous porous media (since $p$, unlike $\theta$, can be assumed continuous across material interfaces) and forced flow. The sign of $p$ is such that $p<0$ corresponds to unsaturated conditions, $p=0$ corresponds to saturation, and $p>0$ corresponds to forced flow.

⁠porousMicroTransportFoam

Transport by steady flow of any number of species in a porous medium, with optional reactions between the species. For each species (concentration $C$), the governing equation is:

$$\frac{\partial R_d \theta C}{\partial t} + \nabla\cdot\left[UC\right] - \nabla\cdot\left[\theta D_{eff}\nabla C\right] = \theta F$$

where $F$ is a reaction term (see below), $R_d$ is defined as:

$$R_d = 1 + \frac{\rho_s\left(1 - \varepsilon_\textrm{tot}\right)K_d}{\theta}$$

and $D_{eff}$ is defined as:

$$D_{eff} = \left(\frac{D_M}{\tau} + \alpha_T|V|\right)I + \left(\alpha_L - \alpha_T\right)\frac{VV}{|V|}$$

with $I$ the identity tensor and $V$ the true velocity of the fluid ($=U/\theta$).

⁠moistureDiffusivityTransportFoam

Capillary flow + reactive transport in a porous medium, coupling the moisture diffusivity equation for flow with the previous transport equation.

⁠microRichardsTransportFoam

Unsaturated flow + reactive transport in a porous medium, coupling the Richards equation for flow with the transport equation described above.

⁠Case layout

The layout of porousMicroTransport cases follows many conventions of porousMultiphaseFoam⁠, especially in field names and entries in the transportProperties dictionary. This allows for easy conversion of cases from porousMultiphaseFoam to porousMicroTransport (and to some extent, vice versa).

⁠Common fields

These variable fields are defined in the time directories:

• theta: moisture content (scalar). Optional for porousMicroTransportFoam; output only for Richards solvers

• p: pressure (scalar). Richards solvers only

• U: Darcy velocity (vector). Optional for flow solvers

⁠Common porous medium properties

Defined as scalar fields in constant or as dictionary entries in transportProperties:

• eps or thetamax: effective porosity ($\varepsilon$)

• K: intrinsic permeability. Flow solvers only

• rs: particle density ($\rho_s$). Transport solvers only

• epsTotal: total porosity ($\varepsilon_\textrm{tot}$). Transport solvers only

• tau: diffusive tortuosity ($\tau$). Transport solvers only

• alphaT: transverse dispersion coefficient ($\alpha_T$). Transport solvers only

• alphaL: longitudinal dispersion coefficient ($\alpha_L$). Transport solvers only

⁠Phase properties

Flow solvers only.

Set these in a phase.theta subdictionary in transportProperties:

• rho: density

• mu: dynamic viscosity

⁠Moisture content options

Flow solvers only.

Defined as scalar fields in constant or as dictionary entries in transportProperties:

• thetamin: minimum (a.k.a. residual) moisture content

• thetamax: maximum moisture content (usually equal to the porosity)

⁠Unsaturated flow models

Flow solvers only.

Supported models of unsaturated flow are:

• BrooksAndCorey: Brooks and Corey^3⁠ model

  • In coefficient dictionary BrooksAndCoreyCoeffs: pc0, alpha, n, l (optional)

• VanGenuchten: Van Genuchten^4⁠ model

  • In coefficient dictionary VanGenuchtenCoeffs: pc0, m or n, l (optional)

• LETxs: LETx + LETs model^5⁠

  • In coefficient dictionary LETCoeffs: pc0, Lw, Ew, Tw, Ls, Es, Ts

• LETd: LETd^6⁠ model

  Moisture-diffusivity formulations only.

  • In coefficient dictionary LETCoeffs: pc0, L, E, T

To choose a model for your simulation, set the unsaturatedFlowModel entry in transportProperties. Then set the model-specific parameters in the corresponding coefficient subdictionary.

⁠Special boundary conditions for flow

Flow solvers only.

Besides the standard OpenFOAM boundary conditions (e.g. zeroGradient, fixedValue), the solvers support these additional boundary conditions for theta:

• darcyGradPressure: follow the boundary condition set for velocity (same as darcyGradPressure in porousMultiphaseFoam⁠).

• exhaustible: models an inlet reservoir with a fixed volume of fluid that is gradually depleted as fluid flows into the domain. A remaining entry is required (volume remaining in the reservoir).

⁠Transported species

Transport solvers only.

A species list in transportProperties contains the names of all transported species.

Each species must also define its own scalar concentration field (named the same as the species).

For each species, the following entries can be set in transportProperties:

• Dm: molecular diffusivity ($D_M$)

• Kd: partitioning coefficient ($K_d$)

⁠Reactions

Transport solvers only.

Reactions are defined in a reactions subdictionary in transportProperties. The reactions dictionary contains a list of subdictionaries, each of which defines a single reaction. A reaction can have an arbitrary name and should contain the following entries:

• reaction: reaction equation. E.g. "A^2 + B = 2C + D", where A, B, C and D are names of defined species

• kf: forward rate constant

• kr: optional reverse rate constant (for reversible reactions)

⁠Automatic timestep control

To enable automatic timestep adjustment, set adjustTimeStep to yes in system/controlDict. Then, configure it as follows:

• For flow, set a tolerance value inside a Picard dictionary in system/fvSolution

• For transport, add a maxDeltaC and/or relMaxDeltaC entry in system/controlDict

⁠Tutorials

Sample cases are available in the tutorials directory⁠.

⁠Citation

If you use porousMicroTransport in your work, please cite our paper:

@article{porousMicroTransport,
    author = {Gerlero, Gabriel S. and Guerenstein, Zahar I. and Franck, Nicolás and Berli, Claudio L. A. and Kler, Pablo A.},
    doi = {10.1016/j.talo.2024.100350},
    journal = {Talanta Open},
    pages = {100350},
    title = {Comprehensive numerical prototyping of paper-based microfluidic devices using open-source tools},
    volume = {10},
    year = {2024}
}

⁠Related projects

• porousMultiphaseFoam⁠^7⁠: toolbox for OpenFOAM for modeling multiphase flow and transport. porousMicroTransport is mostly compatible with porousMultiphaseFoam in terms of case definitions, and can be installed alongside it.

• electroMicroTransport⁠^8⁠: toolbox for OpenFOAM dedicated to electromigrative separations. It includes support for modeling separations in paper-based media, and can also be installed alongside porousMicroTransport.

⁠Footnotes

1. Gerlero, G. S., Guerenstein, Z. I., Franck, N., Berli, C. L. A., & Kler, P. A. (2024). Comprehensive numerical prototyping of paper-based microfluidic devices using open-source tools. Talanta Open, 10, 100350. https://doi.org/10.1016/j.talo.2024.100350⁠ ↩⁠

2. Bear, J., & Cheng, A. H. D. (2010). Modeling groundwater flow and contaminant transport (Vol. 23, p. 834). Dordrecht: Springer. https://doi.org/10.1007/978-1-4020-6682-5⁠ ↩⁠ ↩²⁠

3. Brooks, R., & Corey, T. (1964). Hydraulic properties of porous media. Hydrology Papers Colorado State University. https://mountainscholar.org/bitstream/handle/10217/61288/HydrologyPapers_n3.pdf⁠ ↩⁠

4. Van Genuchten, M. T. (1980). A closed‐form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal, 44(5), 892-898. https://doi.org/10.2136/sssaj1980.03615995004400050002x⁠ ↩⁠

5. Lomeland, F. (2018). Overview of the LET family of versatile correlations for flow functions. In: Proceedings of the International Symposium of Core Analysts, SCA2018-056 http://www.jgmaas.com/SCA/2018/SCA2018-056.pdf⁠ ↩⁠

6. Gerlero, G. S., Valdez, A. R., Urteaga, R., & Kler, P. A. (2022). Validity of capillary imbibition models in paper-based microfluidic applications. Transport in Porous Media, 141(2), 359-378. https://doi.org/10.1007/s11242-021-01724-w⁠ ↩⁠

7. Horgue, P., Renard, F., Gerlero, G. S., Guibert, R., & Debenest, G. (2022). porousMultiphaseFoam v2107: An open-source tool for modeling saturated/unsaturated water flows and solute transfers at watershed scale. Computer Physics Communications, 273, 108278. https://doi.org/10.1016/j.cpc.2021.108278⁠ ↩⁠

8. Gerlero, G. S., Damián, S. M., & Kler, P. A. (2021). electroMicroTransport v2107: Open-source toolbox for paper-based electromigrative separations. Computer Physics Communications, 269, 108143. https://doi.org/10.1016/j.cpc.2021.108143⁠ ↩⁠